Kotlin
Kotlin API migration guide for 1.0.0
The API has been extensively modified with the following goals in mind:
- Enhancing the API to be more idiomatic to Kotlin.
- Match the API rework done through the Rust Zenoh API.
- Abstracting users from the underlying native mechanisms
Default arguments
Throughout the 0.11.0 API we were exposing builders, however we decided to replace all of them with the more Kotlin-idiomatic way of the default arguments.
For instance in 0.11.0:
session.put(keyExpr, value)
+Kotlin
Kotlin API migration guide for 1.0.0
The API has been extensively modified with the following goals in mind:
- Enhancing the API to be more idiomatic to Kotlin.
- Match the API rework done through the Rust Zenoh API.
- Abstracting users from the underlying native mechanisms
Default arguments
Throughout the 0.11.0 API we were exposing builders, however we decided to replace all of them with the more Kotlin-idiomatic way of the default arguments.
For instance in 0.11.0:
session.put(keyExpr, value)
.congestionControl(CongestionControl.BLOCK)
.priority(Priority.REALTIME)
.res()
@@ -9,7 +9,7 @@
congestionControl = CongestionControl.BLOCK,
priority = Priority.REALTIME,
)
-
Notice that the .res() function has been removed. Now functions exposed by the API execute imediately, without the need of .res(). i.e. When doing session.put(...) the put is run immediately.
This applies to all the builders that were in 0.11.0. Generally all the parameters on each builder now have their corresponding argument available in the functions.
Encoding rework
The Encoding class has been modified. In 0.11.0. it had the signature
class Encoding(val knownEncoding: KnownEncoding, val suffix: String = "")
+
Notice that the .res() function has been removed. Now functions exposed by the API execute imediately, without the need of .res(). i.e. When doing session.put(...) the put is run immediately.
This applies to all the builders being present on 0.11.0. Generally 1 all the parameters present on each builder have now their corresponding argument available in the functions.
Session opening
Session.open(config: Config) has now been replaced with Zenoh.open(config: Config).
Encoding rework
The Encoding class has been modified. In 0.11.0. it had the signature
class Encoding(val knownEncoding: KnownEncoding, val suffix: String = "")
where KnownEncoding was an enum.
In 0.11.0. an encoding instance would be created as follows:
val encoding = Encoding(knownEncoding = KnownEncoding.TEXT_JSON)
In 1.0.0. we have implemented the following changes:
KnownEncoding enum is removed, instead we provide static Encoding instances containing an ID and a description.- Custom encodings can be created
- The list of pre-defined encodings has been expanded.
In 1.0.0. the previous example would instead now become:
val encoding = Encoding.TEXT_JSON
Custom encodings can be created by specifying an id and suffix string:
val encoding = Encoding(id = 123, suffix = "example suffix")
@@ -22,11 +22,16 @@
>> Receiving sample on 'A/C/D': hello
since both declarations are still alive.
Now the question is, for how long? What happens first, either when:
- you call
undeclare() or close() to the declaration - the session is closed, then all the associated declarations are automatically undeclared.
Key Expression rework
KeyExpr instances are not bound to a native key expression anymore, unless they are declared from a session. It is safe to drop the reference to the key expression instance, but the memory management associated to a key expression will differ:
- If the KeyExpr was not declared from a session, then the garbage collector simply claims back the memory.
- If it was declared from a session, then the session keeps track of it and frees the native memory upon closing the session.
Declaring a KeyExpr on a session results in better performance, since the session is informed that we intend to use a key expression repeatedly.
We also associate a native key expression to a Kotlin key expression instance, avoiding copies.
Config loading
When opening a session, it’s now mandatory to provide a configuration to the session, even for a default config:
val config = Config.default()
-Session.open(config).onSuccess {
+Zenoh.open(config).onSuccess {
// ...
}
-
The Config class has been modified
Config.default(): returns the default configConfig.fromFile(file: File): Result<Config>: allows to load a config file.Config.fromPath(path: Path): Result<Config>: allows to load a config file from a path.Config.fromJson(json: String): Result<Config>: loads the config from a string literal with json formatConfig.fromJson5(json5: String): Result<Config>: loads the config from a string literal with json5 formatConfig.fromYaml(yaml: String): Result<Config>: loads the config from a string literal with yaml formatConfig.fromJsonElement(jsonElement: JsonElement): Result<Config>: loads the config from a kotlin JsonElement.
In case of failure loading the config, a Result.Error is returned.
Reliability
The Reliability config parameter used when declaring a Subscriber has been moved. It now must be specified when declaring a Publisher or when performing a Put or a Delete operaton.
ZBytes serialization / deserialization & replacement of Value
We have created a new abstraction with the name of ZBytes. This class represents the bytes received through the Zenoh network. This new approach has the following implications:
Attachment class is replaced by ZBytes.Value is replaced by the combination of ZBytes and Encoding.- Replacing
ByteArray to represent payloads
With ZBytes we have also introduced a Serialization and Deserialization for conveinent conversion between ZBytes and Kotlin types.
Serialization
We can serialize primitive types into a ZBytes instance, that is, converting the data into bytes processed by the zenoh network:
Primitive types
The following types support serialization:
- Numeric:
Byte, Short, Int, Long, Float and Double. StringByteArray
For the primitive types, there are three ways to serialize them into a ZBytes, for instance let’s suppose
+
The Config class has been modified
Config.default(): returns the default configConfig.fromFile(file: File): Result<Config>: allows to load a config file.Config.fromPath(path: Path): Result<Config>: allows to load a config file from a path.Config.fromJson(json: String): Result<Config>: loads the config from a string literal with json formatConfig.fromJson5(json5: String): Result<Config>: loads the config from a string literal with json5 formatConfig.fromYaml(yaml: String): Result<Config>: loads the config from a string literal with yaml formatConfig.fromJsonElement(jsonElement: JsonElement): Result<Config>: loads the config from a kotlin JsonElement.
In case of failure loading the config, a Result.Error is returned.
Packages rework
The package structure of the API is now aligned with Zenoh Rust package structure.
Changes:
- Removing the “prelude” package
- QoS package now contains:
CongestionCOntrolPriorityReliabilityQoS
- Bytes package is created with:
ZBytes, IntoZBytes, Encoding
- Config package:
Config, ZenohId
- Session package:
SessionInfo
- Query package:
- contains
Query and Queryable - removing queryable package
Reliability
The Reliability config parameter used on when declaring a subscriber, has been moved. It now must be specified when declaring a Publisher or when performing a Put or a Delete operaton.
Logging
There are two main changes regarding logging, the interface and the mechanism.
Lets look at the following example, where we want to run the ZPub example with debug logging. On 1.0.0 we’ll do:
RUST_LOG=debug gradle ZPub
+
If we wanted to enable debug logging and tracing for some specific package, for instance zenoh::net::routing, we’d do:
RUST_LOG=debug,zenoh::net::routing=trace gradle ZPub
+
However, this is not enabled by default.
+In order to enable logging, one of these newly provided functions must be called:
Zenoh.tryInitLogFromEnv()
+
and
Zenoh.initLogFromEnvOr(fallbackFilter: String): Result<Unit>
+
This last function allows to programmatically specify the logs configuration if not provided as an environment variable.
ZBytes serialization / deserialization & replacement of Value
We have created a new abstraction with the name of ZBytes. This class represents the bytes received through the Zenoh network. This new approach has the following implications:
Attachment class is replaced by ZBytes.Value is replaced by the combination of ZBytes and Encoding.- Replacing
ByteArray to represent payloads
With ZBytes we have also introduced a Serialization and Deserialization for conveinent conversion between ZBytes and Kotlin types.
Serialization
We can serialize primitive types into a ZBytes instance, that is, converting the data into bytes processed by the zenoh network:
Primitive types
The following types support serialization:
- Numeric:
Byte, Short, Int, Long, Float and Double. StringByteArray
For the primitive types, there are three ways to serialize them into a ZBytes, for instance let’s suppose
we want to serialize an Int:
- using the
into() syntax:
val exampleInt: Int = 256
val zbytes: ZBytes = exampleInt.into()
- using the
from() syntax:
val exampleInt: Int = 256
@@ -113,7 +118,7 @@
}
}
}
-