[#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

Author: sophokles73

.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"

.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"

.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

.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

.github/workflows/lint.yml

@@ -20,6 +20,7 @@ on:
     branches: [main]
 
 jobs:
+  # [impl->req~up-language-ci-linter~1]
   lint:
     runs-on: ubuntu-latest
 

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]

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>

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 {

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;

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