[#194] Update to up-spec v1.6.0.alpha-5

Amended code with OpenFastTrace specitems and added configuration for tracing requirements based on up-spec v1.6.0.alpha-5. Added Cucumber based tests that implement the scenarios defined by Gherkin feature files that had been added in v1.6.0.alpha-5. Removed obsolete files and improved cohesion and readability of unit tests. Fixes #194
eclipse-uprotocol · sophokles73 · Sep 17, 2025 · Sep 16, 2025 · Sep 16, 2025 · 421072dea47846ad39e5ace5abd3b50a028bf6cf
commit 421072dea47846ad39e5ace5abd3b50a028bf6cf
diff --git a/.env.oft-current b/.env.oft-current
@@ -13,11 +13,11 @@
 
 # The file patterns that specify the relevant parts of the latest uProtocol Specification
 # that this component is supposed to implement
-UP_SPEC_FILE_PATTERNS="up-spec/*.adoc up-spec/*.md up-spec/basics"
+UP_SPEC_FILE_PATTERNS="up-spec/*.adoc up-spec/*.md up-spec/basics up-spec/up-l1/README.adoc up-spec/up-l2/api.adoc"
 
 # The file patterns that specify this component's resources which contain specification items
 # that cover the requirements
-COMPONENT_FILE_PATTERNS="*.adoc *.md *.java pom.xml *.feature .github src"
+COMPONENT_FILE_PATTERNS="*.adoc *.md .github src"
 
 OFT_FILE_PATTERNS="$UP_SPEC_FILE_PATTERNS $COMPONENT_FILE_PATTERNS"
-OFT_TAGS="_"
+OFT_TAGS="_,LanguageLibrary"
diff --git a/.env.oft-latest b/.env.oft-latest
@@ -17,7 +17,7 @@ UP_SPEC_FILE_PATTERNS="up-spec/*.adoc up-spec/*.md up-spec/basics up-spec/up-l1/
 
 # The file patterns that specify this component's resources which contain specification items
 # that cover the requirements
-COMPONENT_FILE_PATTERNS="*.adoc *.md *.java pom.xml *.feature .github src"
+COMPONENT_FILE_PATTERNS="*.adoc *.md .github src"
 
 OFT_FILE_PATTERNS="$UP_SPEC_FILE_PATTERNS $COMPONENT_FILE_PATTERNS"
 OFT_TAGS="_,LanguageLibrary"
diff --git a/.github/workflows/build_and_test.yml b/.github/workflows/build_and_test.yml
@@ -14,11 +14,16 @@
 name: Verify PR
 
 on:
+  # the repository is configured to require a PR for
+  # making changes to the main branch
+  # so every check made here is effectively
+  # made before merging to main
   pull_request:
     branches:
       - '*'
 
 jobs:
+  # [impl->req~up-language-ci-build~1]
   verify-pr:
     runs-on: ubuntu-latest
 
@@ -33,4 +38,8 @@ jobs:
         distribution: 'temurin'
         cache: maven
     - name: Build and Test with Maven
+      # the package goal includes running the tests
+      # [impl->req~up-language-ci-test~1]
+      # and also builds the JavaDocs
+      # [impl->req~up-language-ci-api-docs~1]
       run: mvn -B package --file pom.xml
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -19,6 +19,7 @@ on:
       - main
 
 jobs:
+  # req~up-language-test-coverage~1
   test-and-coverage:
     name: Test with coverage
     runs-on: ubuntu-latest

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -20,6 +20,7 @@ on:
     branches: [main]
 
 jobs:
+  # [impl->req~up-language-ci-linter~1]
   lint:
     runs-on: ubuntu-latest
 

diff --git a/README.adoc b/README.adoc
@@ -1,22 +1,26 @@
 = Eclipse uProtocol Java Library
 :toc:
 
+[.specitem,oft-sid="uman~up-java-readme~1",oft-covers="req~up-language-documentation~1",tags="LanguageLibrary"]
 == Overview
 
-This is the https://github.com/eclipse-uprotocol/uprotocol-spec/blob/v1.6.0-alpha.4/languages.adoc[uProtocol v1.6.0-alpha.4 Language Library] for the Java programming language. The library is organized into packages that are described in <<sdk-packages>> below and organized by the layers of the protocol.
+This is the https://github.com/eclipse-uprotocol/uprotocol-spec/blob/v1.6.0-alpha.5/languages.adoc[uProtocol v1.6.0-alpha.5 Language Library] for the Java programming language. The library is organized into packages that are described in <<sdk-packages>> below and organized by the layers of the protocol.
 
-Each package contains a README.adoc file that describes the purpose of the package and how to use it.
-
-The module contains the factory methods, serializers, and validators for all data types defined in the specifications, and any data models that either haven't or couldn't be defined in up-core-api yet.
+Each package folder contains a `README.adoc` file that describes the purpose of the package and how to use it.
 
 == Getting Started
 
-=== Importing the Library
-
-To pull the Library from maven central, setting ${uprotocol.version} to the latest version of this library in your pom.xml file:
-[source]
+=== Adding the Library
+
+The library is available from [Maven Central](https://search.maven.org/artifact/org.eclipse.uprotocol/up-java) and can be added as a dependency to your Maven or Gradle project.
+
+[.specitem,oft-sid="impl~up-java-deps-resolution~1",oft-covers="req~up-language-build-deps~1",tags="LanguageLibrary"]
+----
+The following dependency needs to be added to your Maven POM file, setting `${uprotocol.version}` to the desired version of the library:
+----
+
+[source,xml]
 ----
-<!-- uProtocol Core -->
 <dependency>
     <groupId>org.eclipse.uprotocol</groupId>
     <artifactId>up-java</artifactId>
@@ -34,21 +38,20 @@ To pull the Library from maven central, setting ${uprotocol.version} to the late
 
 | xref:src/main/java/org/eclipse/uprotocol/client/README.adoc[`*client*`]
 | Top level client-facing interfaces to communication with USubscription, UDiscovery, and UTwin services.
-| https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.4/up-l3/README.adoc[Application Layer (uP-L3)]
+| https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l3/README.adoc[Application Layer (uP-L3)]
 
 | xref:src/main/java/org/eclipse/uprotocol/communication/README.adoc[`*communication*`]
 | Common implementation of communication messaging patterns (publisher, subscriber, RpcClient, RpcServer, etc..) that are built on top of the L1 transport interface (see below).
-| https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.4/up-l2/api.adoc[Communication Layer (uP-L2)] 
+| https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l2/api.adoc[Communication Layer (uP-L2)] 
 
 | xref:src/main/java/org/eclipse/uprotocol/transport/README.adoc[`*transport*`] 
 | Interface and data model for how to send() and receive() messages in a common way across various transport technologies (ex. zenoh, mqtt, http, etc...). the interface is implemented by transports (ex. up-transport-android-java), and the interface is then used to build the uProtocol layer 2 communication layer implementation.
-| https://github.com/eclipse-uprotocol/uprotocol-spec/blob/v1.6.0-alpha.4/up-l1/README.adoc[Transport Layer (uP-L1)] 
+| https://github.com/eclipse-uprotocol/uprotocol-spec/blob/v1.6.0-alpha.5/up-l1/README.adoc[Transport Layer (uP-L1)] 
 
 | xref:src/main/java/org/eclipse/uprotocol/uri/README.adoc[`*uuri*`]
 | uProtocol addressing scheme (UUri) builders, validators, and serializers. 
 | Basics 
 
-
 | xref:src/main/java/org/eclipse/uprotocol/uuid/README.adoc[`*uuid*`]
 | uProtocol unique identifier builders, validators, and serializers.
 | Basics
@@ -57,6 +60,11 @@ To pull the Library from maven central, setting ${uprotocol.version} to the late
 
 === Building from Source
 
+[.specitem,oft-sid="impl~up-java-build-system~1",oft-covers="req~up-language-build-sys~1",tags="LanguageLibrary"]
+----
+The library is built using the [Apache Maven](https://apache.org/maven) build system and is published to [Maven Central](https://search.maven.org/artifact/org.eclipse.uprotocol/up-java).
+----
+
 . Clone the repository:
 +
 [source,console]

diff --git a/pom.xml b/pom.xml
@@ -96,6 +96,13 @@
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
+            <dependency>
+                <groupId>io.cucumber</groupId>
+                <artifactId>cucumber-bom</artifactId>
+                <version>7.25.0</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 
@@ -144,6 +151,12 @@
             <scope>test</scope>
         </dependency>
 
+        <dependency>
+            <groupId>org.junit.platform</groupId>
+            <artifactId>junit-platform-suite</artifactId>
+            <scope>test</scope>
+        </dependency>
+
         <dependency>
             <groupId>org.mockito</groupId>
             <artifactId>mockito-core</artifactId>
@@ -173,6 +186,16 @@
             <artifactId>jul-to-slf4j</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>io.cucumber</groupId>
+            <artifactId>cucumber-java</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.cucumber</groupId>
+            <artifactId>cucumber-junit-platform-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>
@@ -294,10 +317,19 @@
             </plugin>
             <plugin>
                 <artifactId>maven-surefire-plugin</artifactId>
-                <version>3.5.3</version>
+                <!-- 
+                    do NOT use 3.5.3 as it is incompatible with Cucumber
+                    https://github.com/cucumber/cucumber-jvm/issues/2984
+                 -->
+                <version>3.5.2</version>
                 <configuration>
                     <!--  allow to use unnamed modules -->
                     <useModulePath>false</useModulePath>
+                    <properties>
+                        <configurationParameters>
+                            cucumber.junit-platform.naming-strategy=surefire
+                        </configurationParameters>
+                    </properties>
                 </configuration>
             </plugin>
             <plugin>

diff --git a/src/main/java/org/eclipse/uprotocol/client/usubscription/v3/USubscriptionClient.java b/src/main/java/org/eclipse/uprotocol/client/usubscription/v3/USubscriptionClient.java
@@ -32,7 +32,7 @@
 /**
  * The client-side interface for interacting with a USubscription service instance.
  *
- * @see <a href="https://github.com/eclipse-uprotocol/up-spec/tree/v1.6.0-alpha.4/up-l3/usubscription/v3">
+ * @see <a href="https://github.com/eclipse-uprotocol/up-spec/tree/v1.6.0-alpha.5/up-l3/usubscription/v3">
  * USubscription service specification</a>
  */
 public interface USubscriptionClient {

diff --git a/src/main/java/org/eclipse/uprotocol/communication/AbstractCommunicationLayerClient.java b/src/main/java/org/eclipse/uprotocol/communication/AbstractCommunicationLayerClient.java
@@ -17,6 +17,7 @@
 import org.eclipse.uprotocol.transport.LocalUriProvider;
 import org.eclipse.uprotocol.transport.UTransport;
 
+// [impl->dsn~communication-layer-impl-default~1]
 public class AbstractCommunicationLayerClient {
     private final UTransport transport;
     private final LocalUriProvider uriProvider;

diff --git a/src/main/java/org/eclipse/uprotocol/communication/CallOptions.java b/src/main/java/org/eclipse/uprotocol/communication/CallOptions.java
@@ -21,6 +21,7 @@
 /**
  * This class is used to pass metadata to method invocation on the client side.
  */
+// [impl->dsn~communication-layer-api-declaration~1]
 public record CallOptions (Integer timeout, UPriority priority, String token) {
     public static final int TIMEOUT_DEFAULT = 10000; // Default timeout of 10 seconds
 

diff --git a/src/main/java/org/eclipse/uprotocol/communication/InMemoryRpcClient.java b/src/main/java/org/eclipse/uprotocol/communication/InMemoryRpcClient.java
@@ -45,6 +45,7 @@
  *         or directly use the {@link UTransport} to send RPC requests and register listeners that
  *         handle the RPC responses.
  */
+// [impl->dsn~communication-layer-impl-default~1]
 public class InMemoryRpcClient extends AbstractCommunicationLayerClient implements RpcClient {
     // Map to store the futures that needs to be completed when the response comes in
     private final Map<UUID, CompletableFuture<UMessage>> mRequests = new ConcurrentHashMap<>();

diff --git a/src/main/java/org/eclipse/uprotocol/communication/InMemoryRpcServer.java b/src/main/java/org/eclipse/uprotocol/communication/InMemoryRpcServer.java
@@ -48,6 +48,7 @@
  *                or directly use a {@link UTransport} to register listeners that handle 
  *                RPC requests and send RPC responses.
  */
+// [impl->dsn~communication-layer-impl-default~1]
 public class InMemoryRpcServer extends AbstractCommunicationLayerClient implements RpcServer {
     private static final Logger LOGGER = LoggerFactory.getLogger(InMemoryRpcServer.class);
 

diff --git a/src/main/java/org/eclipse/uprotocol/communication/InMemorySubscriber.java b/src/main/java/org/eclipse/uprotocol/communication/InMemorySubscriber.java
@@ -59,6 +59,7 @@
  * registered with the listener. When a subscription change notification arrives from the USubscription
  * service, the corresponding handler is being looked up and invoked.
  */
+// [impl->dsn~communication-layer-impl-default~1]
 public final class InMemorySubscriber implements Subscriber {
     private static final Logger LOGGER = LoggerFactory.getLogger(InMemorySubscriber.class);
 

diff --git a/src/main/java/org/eclipse/uprotocol/communication/Notifier.java b/src/main/java/org/eclipse/uprotocol/communication/Notifier.java
@@ -21,9 +21,10 @@
 /**
  * A client for sending Notification messages to a uEntity.
  *
- * @see <a href="https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.4/up-l2/api.adoc">
+ * @see <a href="https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l2/api.adoc">
  * Communication Layer API Specifications</a>
  */
+// [impl->dsn~communication-layer-api-declaration~1]
 public interface Notifier {
 
     /**

diff --git a/src/main/java/org/eclipse/uprotocol/communication/Publisher.java b/src/main/java/org/eclipse/uprotocol/communication/Publisher.java
@@ -17,9 +17,10 @@
 /**
  * A client for publishing messages to a topic.
  *
- * @see <a href="https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.4/up-l2/api.adoc">
+ * @see <a href="https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l2/api.adoc">
  * Communication Layer API Specifications</a>
  */
+// [impl->dsn~communication-layer-api-declaration~1]
 public interface Publisher {
     /**
      * Publishes a message to a topic.

diff --git a/src/main/java/org/eclipse/uprotocol/communication/RequestHandler.java b/src/main/java/org/eclipse/uprotocol/communication/RequestHandler.java
@@ -19,6 +19,7 @@
  * RequestListener is used by the RpcServer to handle incoming requests and automatically sends
  * back the response to the client. <br>
  */
+// [impl->dsn~communication-layer-api-declaration~1]
 public interface RequestHandler {
     /**
      * Method called to handle/process request messages.

diff --git a/src/main/java/org/eclipse/uprotocol/communication/RpcClient.java b/src/main/java/org/eclipse/uprotocol/communication/RpcClient.java
@@ -19,9 +19,10 @@
 /**
  * A client for performing Remote Procedure Calls (RPC) on (other) uEntities.
  *
- * @see <a href="https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.4/up-l2/api.adoc">
+ * @see <a href="https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l2/api.adoc">
  * Communication Layer API specification</a>
  */
+// [impl->dsn~communication-layer-api-declaration~1]
 public interface RpcClient {
     /**
      * Invokes a method on a service.

diff --git a/src/main/java/org/eclipse/uprotocol/communication/RpcServer.java b/src/main/java/org/eclipse/uprotocol/communication/RpcServer.java
@@ -21,9 +21,10 @@
 /**
  * A server for exposing Remote Procedure Call (RPC) endpoints.
  *
- * @see <a href="https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.4/up-l2/api.adoc">
+ * @see <a href="https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l2/api.adoc">
  * Communication Layer API specification</a>
  */
+// [impl->dsn~communication-layer-api-declaration~1]
 public interface RpcServer {
     /**
      * Registers an endpoint for RPC requests.

diff --git a/src/main/java/org/eclipse/uprotocol/communication/SimpleNotifier.java b/src/main/java/org/eclipse/uprotocol/communication/SimpleNotifier.java
@@ -32,6 +32,7 @@
  * their own or directly use the {@link UTransport} to send notifications and register
  * listeners.
  */
+// [impl->dsn~communication-layer-impl-default~1]
 public class SimpleNotifier extends AbstractCommunicationLayerClient implements Notifier {
 
     /**

diff --git a/src/main/java/org/eclipse/uprotocol/communication/SimplePublisher.java b/src/main/java/org/eclipse/uprotocol/communication/SimplePublisher.java
@@ -28,6 +28,7 @@
  * <em>NOTE:</em> Developers are not required to use these APIs, they can implement their own
  *  or directly use the {@link UTransport} to send notifications and register listeners.
  */
+// [impl->dsn~communication-layer-impl-default~1]
 public class SimplePublisher extends AbstractCommunicationLayerClient implements Publisher {
 
     /**

diff --git a/src/main/java/org/eclipse/uprotocol/communication/Subscriber.java b/src/main/java/org/eclipse/uprotocol/communication/Subscriber.java
@@ -25,9 +25,10 @@
 /**
  * A client for subscribing to topics.
  *
- * @see <a href="https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.4/up-l2/api.adoc">
+ * @see <a href="https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l2/api.adoc">
  * Communication Layer API Specifications</a>
  */
+// [impl->dsn~communication-layer-api-declaration~1]
 public interface Subscriber {
     /**
      * Registers a handler to invoke for messages that have been published to a given topic.

diff --git a/src/main/java/org/eclipse/uprotocol/communication/SubscriptionChangeHandler.java b/src/main/java/org/eclipse/uprotocol/communication/SubscriptionChangeHandler.java
@@ -20,6 +20,7 @@
  * 
  * This interface provides APIs to handle subscription state changes for a given topic.
  */
+// [impl->dsn~communication-layer-api-declaration~1]
 public interface SubscriptionChangeHandler {
     /**
      * Method called to handle/process subscription state changes for a given topic.

diff --git a/src/main/java/org/eclipse/uprotocol/communication/UClient.java b/src/main/java/org/eclipse/uprotocol/communication/UClient.java
@@ -23,6 +23,7 @@
 /**
  * A client for Communication Layer APIs.
  */
+// [impl->dsn~communication-layer-impl-default~1]
 public final class UClient implements RpcServer, Notifier, Publisher, RpcClient {
 
     private final RpcServer rpcServer;

diff --git a/src/main/java/org/eclipse/uprotocol/communication/UPayload.java b/src/main/java/org/eclipse/uprotocol/communication/UPayload.java
@@ -28,6 +28,7 @@
 /**
  * Wrapper class that stores the payload as {@link UPayloadFormat}.
  */
+// [impl->dsn~communication-layer-api-declaration~1]
 public record UPayload (ByteString data, UPayloadFormat format) {
 
     // Empty UPayload

diff --git a/src/main/java/org/eclipse/uprotocol/communication/UStatusException.java b/src/main/java/org/eclipse/uprotocol/communication/UStatusException.java
@@ -20,6 +20,7 @@
 /**
  * The unchecked exception which carries uProtocol error model.
  */
+// [impl->dsn~communication-layer-api-declaration~1]
 public class UStatusException extends RuntimeException {
     private final UStatus mStatus;
 

diff --git a/src/main/java/org/eclipse/uprotocol/communication/package-info.java b/src/main/java/org/eclipse/uprotocol/communication/package-info.java
@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+// This program and the accompanying materials are made available under the
+// terms of the Apache License Version 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// SPDX-License-Identifier: Apache-2.0
+
+// [impl->dsn~communication-layer-api-namespace~1]
+package org.eclipse.uprotocol.communication;
diff --git a/src/main/java/org/eclipse/uprotocol/transport/LocalUriProvider.java b/src/main/java/org/eclipse/uprotocol/transport/LocalUriProvider.java
@@ -20,6 +20,7 @@
  * Implementations may use arbitrary mechanisms to determine the information that
  * is necessary for creating URIs, e.g. environment variables, configuration files etc.
  */
+// [impl->dsn~localuriprovider-declaration~1]
 public interface LocalUriProvider {
     /**
      * Gets the <em>authority</em> used for URIs representing this uEntity's resources.
-Original file line number
+Diff line change
@@ Expand Up / @@ -20,6 +20,7 @@ on: @@
         branches: [main]
     jobs:
+      # [impl->req~up-language-ci-linter~1]
       lint:
         runs-on: ubuntu-latest
@@ Expand Down @@