Merge branch 'main' into feat/tracing

examples/README.md

@@ -7,13 +7,62 @@
 
 
 ```bash
-  ./gradle <example>
+  gradle <example> --args="<arguments>"
 ```
 
-:warning: Passing arguments to these examples has not been enabled yet for this first version. Altering the Zenoh
-configuration for these examples must be done programmatically. :warning:
+for instance
 
----- 
+```bash
+  gradle ZPub --args="-h"
+```
+
+will return
+```bash
+> Task :examples:ZPub
+Usage: zpub [<options>]
+
+  Zenoh Pub example
+
+Options:
+  -k, --key=<key>             The key expression to write to [default:
+                              demo/example/zenoh-kotlin-pub]
+  -c, --config=<config>       A configuration file.
+  -e, --connect=<connect>...  Endpoints to connect to.
+  -l, --listen=<listen>...    Endpoints to listen on.
+  -m, --mode=<mode>           The session mode. Default: peer. Possible values:
+                              [peer, client, router]
+  -v, --value=<value>         The value to write. [Default: "Pub from Kotlin!"]
+  -a, --attach=<attach>       The attachments to add to each put. The key-value
+                              pairs are &-separated, and = serves as the
+                              separator between key and value.
+  --no-multicast-scouting     Disable the multicast-based scouting mechanism.
+  -h, --help                  Show this message and exit
+
+```
+
+The connect and listen parameters (that are common to all the examples) accept multiple repeated inputs.
+For instance:
+
+```bash
+  gradle ZPub --args="-l tcp/localhost:7447 -l tcp/localhost:7448 -l tcp/localhost:7449"
+```
+
+There is the possibility to provide a Zenoh config file as follows
+```bash
+  gradle ZPub --args="-c path/to/config.json5"
+```
+
+In that case, any other provided configuration parameters through the command line interface will not be taken into consideration.
+
+One last comment regarding Zenoh logging for the examples, remember it can be enabled through the `zenoh.logger` property as follows:
+
+```bash
+  gradle ZPub -Pzenoh.logger=<level>
+```
+
+where `<level>` can be either `info`, `trace`, `debug`, `warn` or `error`.
+
+----
 
 ## Examples description
 
@@ -25,7 +74,11 @@ The path/value will be received by all matching subscribers, for instance the [Z
 Usage:
 
 ```bash
-./gradle ZPub
+gradle ZPub
+```
+or
+```bash
+gradle ZPub --args="-k demo/example/test -v 'hello world'"
 ```
 
 ### ZSub
@@ -36,7 +89,11 @@ the subscriber's key expression, and will print this notification.
 Usage:
 
 ```bash
-./gradle ZSub
+gradle ZSub
+```
+or
+```bash
+gradle ZSub --args="-k demo/example/test"
 ```
 
 ### ZGet
@@ -46,9 +103,14 @@ The queryables with a matching path or selector (for instance [ZQueryable](#zque
 will receive this query and reply with paths/values that will be received by the query callback.
 
 ```bash
-./gradle ZGet
+gradle ZGet
+```
+or
+
+```bash
+gradle ZGet --args="-s demo/example/get"
 ```
-    
+
 ### ZPut
 
 Puts a path/value into Zenoh.
@@ -57,7 +119,13 @@ The path/value will be received by all matching subscribers, for instance the [Z
 Usage:
 
 ```bash
-./gradle ZPut
+gradle ZPut
+```
+
+or
+
+```bash
+gradle ZPut --args="-k demo/example/put -v 'Put from Kotlin!'"
 ```
 
 ### ZDelete
@@ -66,7 +134,13 @@ Performs a Delete operation into a path/value into Zenoh.
 Usage:
 
 ```bash
-./gradle ZDelete
+gradle ZDelete
+```
+
+or
+
+```bash
+gradle ZDelete --args="-k demo/example/delete"
 ```
 
 ### ZQueryable
@@ -78,7 +152,13 @@ with a selector that matches the key expression, and will return a value to the
 Usage:
 
 ```bash
-./gradle ZQueryable
+gradle ZQueryable
+```
+
+or
+
+```bash
+gradle ZQueryable --args="-k demo/example/query"
 ```
 
 ### ZPubThr & ZSubThr
@@ -90,11 +170,11 @@ put operations and a subscriber receiving notifications of those puts.
 Subscriber usage:
 
 ```bash
-./gradle ZSubThr
+gradle ZSubThr
 ```
 
 Publisher usage:
 
 ```bash
-./gradle ZPubThr
+gradle ZPubThr <payload_size>
 ```

examples/build.gradle.kts

@@ -14,6 +14,7 @@
 
 plugins {
     kotlin("jvm")
+    kotlin("plugin.serialization")
 }
 
 kotlin {
@@ -24,6 +25,8 @@ dependencies {
     implementation(project(":zenoh-kotlin"))
     implementation("commons-net:commons-net:3.9.0")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
+    implementation("com.github.ajalt.clikt:clikt:4.2.2")
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
 }
 
 tasks {

examples/src/main/kotlin/io.zenoh/Config.kt

@@ -0,0 +1,78 @@
+//
+// Copyright (c) 2023 ZettaScale Technology
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+//
+// Contributors:
+//   ZettaScale Zenoh Team, <zenoh@zettascale.tech>
+//
+
+package io.zenoh
+
+import io.zenoh.sample.Attachment
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.encodeToJsonElement
+import kotlin.io.path.Path
+
+@Serializable
+data class ConfigData(
+    @SerialName("connect") var connect: Connect? = null,
+    @SerialName("listen") var listen: Listen? = null,
+    @SerialName("mode") var mode: String? = null,
+    @SerialName("scouting") var scouting: Scouting? = null,
+)
+
+@Serializable
+data class Connect(
+    @SerialName("endpoints") var endpoints: List<String>
+)
+
+@Serializable
+data class Listen(
+    @SerialName("endpoints") var endpoints: List<String>
+)
+
+@Serializable
+data class Scouting(
+    @SerialName("multicast") var multicast: Multicast,
+)
+
+@Serializable
+data class Multicast(
+    @SerialName("enabled") var enabled: Boolean,
+)
+
+internal fun loadConfig(
+    emptyArgs: Boolean,
+    configFile: String?,
+    connectEndpoints: List<String>,
+    listenEndpoints: List<String>,
+    noMulticastScouting: Boolean,
+    mode: String?
+): Config {
+    val config = if (emptyArgs) {
+        Config.default()
+    } else {
+        configFile?.let { Config.from(Path(it)) } ?: run {
+            val connect = Connect(connectEndpoints)
+            val listen = Listen(listenEndpoints)
+            val scouting = Scouting(Multicast(!noMulticastScouting))
+            val configData = ConfigData(connect, listen, mode, scouting)
+            val jsonConfig = Json.encodeToJsonElement(configData)
+            Config.from(jsonConfig)
+        }
+    }
+    return config
+}
+
+internal fun decodeAttachment(attachment: String): Attachment {
+    val pairs = attachment.split("&").map { it.split("=").let { (k, v) -> k.toByteArray() to v.toByteArray() } }
+    return Attachment.Builder().addAll(pairs).res()
+}

examples/src/main/kotlin/io.zenoh/ZDelete.kt

@@ -14,18 +14,49 @@
 
 package io.zenoh
 
+import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.parameters.options.*
 import io.zenoh.keyexpr.intoKeyExpr
 
-fun main() {
-    println("Opening session...")
-    Session.open().onSuccess { session ->
-        session.use {
-            "demo/example/zenoh-kotlin-put".intoKeyExpr().onSuccess { keyExpr ->
-                keyExpr.use {
-                    println("Deleting resources matching '$keyExpr'...")
-                    session.delete(keyExpr).res()
+class ZDelete(private val emptyArgs: Boolean) : CliktCommand(
+    help = "Zenoh Delete example"
+) {
+
+    private val connect: List<String> by option(
+        "-e", "--connect", help = "Endpoints to connect to.", metavar = "connect"
+    ).multiple()
+    private val listen: List<String> by option(
+        "-l", "--listen", help = "Endpoints to listen on.", metavar = "listen"
+    ).multiple()
+    private val configFile by option("-c", "--config", help = "A configuration file.", metavar = "config")
+    private val key by option(
+        "-k", "--key", help = "The key expression to write to [default: demo/example/zenoh-kotlin-put]", metavar = "key"
+    ).default("demo/example/zenoh-kotlin-put")
+    private val mode by option(
+        "-m",
+        "--mode",
+        help = "The session mode. Default: peer. Possible values: [peer, client, router]",
+        metavar = "mode"
+    ).default("peer")
+    private val noMulticastScouting: Boolean by option(
+        "--no-multicast-scouting", help = "Disable the multicast-based scouting mechanism."
+    ).flag(default = false)
+
+    override fun run() {
+        val config = loadConfig(emptyArgs, configFile, connect, listen, noMulticastScouting,mode)
+
+        println("Opening session...")
+        Session.open(config).onSuccess { session ->
+            session.use {
+                key.intoKeyExpr().onSuccess { keyExpr ->
+                    keyExpr.use {
+                        println("Deleting resources matching '$keyExpr'...")
+                        session.delete(keyExpr).res()
+                    }
                 }
             }
         }
     }
 }
+
+fun main(args: Array<String>) = ZDelete(args.isEmpty()).main(args)