Examples fat JARs

Adding tasks for creating executable jar's for the examples.
The gradle task `buildExamples` will output fat jar's for each of the examples, which can be later run with
```
java -jar <Example>.jar
```

Author: DariusIMP

build.gradle.kts

@@ -23,6 +23,7 @@ buildscript {
         classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0")
         classpath("org.mozilla.rust-android-gradle:plugin:0.9.6")
         classpath("com.android.tools.build:gradle:7.4.2")
+        classpath("com.gradleup.shadow:shadow-gradle-plugin:9.0.0-beta6")
     }
 }
 

examples/README.md

@@ -1,15 +1,73 @@
-# Zenoh Kotlin examples
+# Zenoh Java examples
 
 ----
 
 ## Start instructions
 
+For running the examples, there are two approaches. Either you run the gradle example task with the syntax `gradle <example> --args="<arguments>"` or you can build fat JARs the examples through the task `gradle buildExamples`.
+
+While both are valid, in this document we'll follow the second approach; when running `gradle buildExamples`, all the JARs will be located under `/examples/build/libs`, which can later be executed
+
+```bash
+java -jar <Example>.jar <arguments>
+```
+
+for instance
+
 ```bash
-  ./gradle <example>
+java -jar ZPub.jar -h
 ```
 
-: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:
+will return
+
+```bash
+Usage: ZPub [-hV] [--no-multicast-scouting] [-a=<attachment>] [-c=<configFile>]
+            [-k=<key>] [-m=<mode>] [-v=<value>] [-e=<connect>[,
+            <connect>...]]... [-l=<listen>[,<listen>...]]...
+Zenoh Pub example
+  -a, --attach=<attachment>
+                        The attachments to add to each put. The key-value pairs
+                          are &-separated, and = serves as the separator
+                          between key and value.
+  -c, --config=<configFile>
+                        A configuration file.
+  -e, --connect=<connect>[,<connect>...]
+                        Endpoints to connect to.
+  -h, --help            Show this help message and exit.
+  -k, --key=<key>       The key expression to write to [default:
+                          demo/example/zenoh-java-pub].
+  -l, --listen=<listen>[,<listen>...]
+                        Endpoints to listen on.
+  -m, --mode=<mode>     The session mode. Default: peer. Possible values:
+                          [peer, client, router].
+      --no-multicast-scouting
+                        Disable the multicast-based scouting mechanism.
+  -v, --value=<value>   The value to write. [default: 'Pub from Java!']
+  -V, --version         Print version information and exit.
+```
+
+The connect and listen parameters (that are common to all the examples) accept multiple repeated inputs.
+For instance:
+
+```bash
+java -jar ZPub.jar -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
+java -jar ZPub.jar -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, logs from the native library can be enabled through the environment variable `RUST_LOG` as follows:
+
+```bash
+RUST_LOG=<level> java -jar ZPub.jar
+```
+
+where `<level>` is the log filter (for instance `debug`, `warn`, `error`... (see the [Rust documentation](https://docs.rs/env_logger/latest/env_logger/#enabling-logging))).
 
 ----
 
@@ -23,7 +81,13 @@ The path/value will be received by all matching subscribers, for instance the [Z
 Usage:
 
 ```bash
-./gradle ZPub
+java -jar ZPub.jar
+```
+
+or
+
+```bash
+java -jar ZPub.jar -k demo/example/test -v "hello world"
 ```
 
 ### ZSub
@@ -35,7 +99,13 @@ the subscriber's key expression, and will print this notification.
 Usage:
 
 ```bash
-./gradle ZSub
+java -jar ZSub.jar
+```
+
+or
+
+```bash
+java -jar ZSub.jar -k demo/example/test
 ```
 
 ### ZGet
@@ -45,7 +115,13 @@ 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
+java -jar ZGet.jar
+```
+
+or
+
+```bash
+java -jar ZGet.jar -s demo/example/get
 ```
 
 ### ZPut
@@ -56,7 +132,13 @@ The path/value will be received by all matching subscribers, for instance the [Z
 Usage:
 
 ```bash
-./gradle ZPut
+java -jar ZPut.jar
+```
+
+or
+
+```bash
+java -jar ZPut.jar -k demo/example/put -v 'Put from Java!'
 ```
 
 ### ZDelete
@@ -66,7 +148,13 @@ Performs a Delete operation into a path/value into Zenoh.
 Usage:
 
 ```bash
-./gradle ZDelete
+java -jar ZDelete.jar
+```
+
+or
+
+```bash
+java -jar ZDelete.jar -k demo/example/delete
 ```
 
 ### ZQueryable
@@ -78,7 +166,13 @@ with a selector that matches the key expression, and will return a value to the
 Usage:
 
 ```bash
-./gradle ZQueryable
+java -jar ZQueryable.jar
+```
+
+or
+
+```bash
+java -jar ZQueryable.jar -k demo/example/query
 ```
 
 ### ZPubThr & ZSubThr
@@ -90,11 +184,63 @@ put operations and a subscriber receiving notifications of those puts.
 Subscriber usage:
 
 ```bash
-./gradle ZSubThr
+java -jar ZSubThr.jar
 ```
 
 Publisher usage:
 
 ```bash
-./gradle ZPubThr
+java -jar ZPubThr.jar <payload_size>
+```
+
+### ZPing & ZPong
+
+Latency tests
+
+```bash
+java -jar ZPing.jar
+```
+
+```bash
+java -jar ZPong.jar
+```
+
+### ZScout
+
+A scouting example. Will show information from other nodes in the Zenoh network.
+
+```bash
+java -jar ZScout.jar
+```
+
+### Liveliness examples
+
+#### ZLiveliness
+
+The ZLiveliness example, it just announces itself to the Zenoh network by default to the key expression `group1/zenoh-java`.
+
+Usage:
+
+```bash
+java -jar ZLiveliness
+```
+
+It can be used along with the following liveliness examples:
+
+#### ZGetLiveliness
+
+Gets the liveliness tokens, by default to `group1/zenoh-java`.
+
+Usage:
+
+```bash
+java -jar ZGetLiveliness
+```
+
+#### ZSubLiveliness
+
+Subscribes to liveliness events:
+
+```bash
+java -jar ZSubLiveliness
 ```

examples/build.gradle.kts

@@ -12,9 +12,12 @@
 //   ZettaScale Zenoh Team, <[email protected]>
 //
 
+import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
+
 plugins {
     kotlin("jvm")
     kotlin("plugin.serialization") version "1.9.0"
+    id("com.gradleup.shadow")
 }
 
 kotlin {
@@ -50,6 +53,29 @@ tasks {
         "ZSubThr"
     )
 
+    examples.forEach { example ->
+        register<ShadowJar>("${example}Jar") {
+            group = "build"
+            description = "Build a fat JAR for the $example example"
+            from(sourceSets["main"].output)
+            manifest {
+                attributes["Main-Class"] = "io.zenoh.${example}"
+            }
+            configurations.empty()
+            configurations.add(project.configurations.getByName("runtimeClasspath"))
+
+            archiveBaseName.set(example)
+            archiveVersion.set("")
+            archiveClassifier.set("")
+        }
+    }
+
+    register("buildExamples") {
+        group = "build"
+        description = "Build all fat JARs for the Zenoh Java examples"
+        dependsOn(examples.map { "${it}Jar" })
+    }
+
     examples.forEach { example ->
         register(example, JavaExec::class) {
             dependsOn("CompileZenohJNI")