eclipse-uprotocol · sophokles73 · Sep 1, 2025 · Aug 12, 2025 · Aug 12, 2025
diff --git a/.github/workflows/build_and_test.yml b/.github/workflows/build_and_test.yml
@@ -1,3 +1,16 @@
+# ********************************************************************************
+#  Copyright (c) 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
+# *******************************************************************************/
+
 name: Verify PR
 
 on:
@@ -10,9 +23,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
+      with:
+        submodules: 'recursive'
     - name: Set up JDK 17
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@v4
       with:
         java-version: '17'
         distribution: 'temurin'

diff --git a/.github/workflows/build_deploy.yml b/.github/workflows/build_deploy.yml
@@ -1,4 +1,17 @@
-name: Continuous Integration
+# ********************************************************************************
+#  Copyright (c) 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
+# *******************************************************************************/
+
+name: Publish SNAPSHOT to Maven Central
 
 on:
   push:
@@ -12,19 +25,21 @@ jobs:
       contents: write
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
+      with:
+        submodules: 'recursive'
 
     - name: Set up Apache Maven Central
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@v4
       with: # configure settings.xml
         distribution: 'temurin'
         java-version: '17'
-        server-id: ossrh
-        server-username: OSSRH_USER
-        server-password: OSSRH_PASSWORD
+        server-id: central
+        server-username: MAVEN_CENTRAL_USER
+        server-password: MAVEN_CENTRAL_PASSWORD
 
-    - name: Build and Publish to OSSRH snapshot repo
+    - name: Build and Publish to Maven Central snapshot repository
       run: mvn clean deploy
       env:
-        OSSRH_USER: ${{ secrets.ORG_OSSRH_USERNAME }}
-        OSSRH_PASSWORD: ${{ secrets.ORG_OSSRH_PASSWORD }}
+        MAVEN_CENTRAL_USER: ${{ secrets.CENTRAL_SONATYPE_TOKEN_USERNAME }}
+        MAVEN_CENTRAL_PASSWORD: ${{ secrets.CENTRAL_SONATYPE_TOKEN_PASSWORD }}
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
@@ -1,3 +1,16 @@
+# ********************************************************************************
+#  Copyright (c) 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
+# *******************************************************************************/
+
 name: "CodeQL"
 
 on:
@@ -28,16 +41,18 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          # Analyzes Java code directly from the codebase without a build
+          # use autobuild to also include types generated from proto3 files
           - language: java-kotlin
-            build-mode: none # analyzes Java only
+            build-mode: autobuild
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+            submodules: 'recursive'
 
       # Setup java 17.
       - name: Set up JDK 17
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           java-version: '17'
           distribution: 'temurin'

diff --git a/.github/workflows/coverage-comment-pr.yml b/.github/workflows/coverage-comment-pr.yml
@@ -1,3 +1,16 @@
+# ********************************************************************************
+#  Copyright (c) 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
+# *******************************************************************************/
+
 name: Add coverage comment to PR
 
 on:

diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -1,3 +1,16 @@
+# ********************************************************************************
+#  Copyright (c) 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
+# *******************************************************************************/
+
 name: Java Test and Coverage
 
 on:
@@ -11,42 +24,46 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - run: |
-          git config --global user.name 'eclipse-uprotocol-bot'
-          git config --global user.email 'uprotocol-bot@eclipse.org'
-
       - name: Checkout code
         uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
+        with:
+            submodules: 'recursive'
 
-      - name: Set up Apache Maven Central
-        uses: actions/setup-java@v3
+      - name: Install xmllint
+        run: sudo apt-get update && sudo apt-get install -y libxml2-utils
+
+      - name: Set up Java with Maven
+        uses: actions/setup-java@v4
         with: # configure settings.xml
           distribution: 'temurin'
           java-version: '17'
-          server-id: ossrh
-          server-username: OSSRH_USER
-          server-password: OSSRH_PASSWORD
-          gpg-private-key: ${{ secrets.ORG_GPG_PRIVATE_KEY }}
-          gpg-passphrase: GPG_PASSPHRASE
-
 
       - name: Run tests with coverage
         run: |
-          mvn clean test jacoco:report
-
+          mvn clean verify -Djacoco.skip=false
 
-      - name: Extract JaCoCo report
+      - name: Extract overall coverage from JaCoCo report
         run: |
           echo "Extracting coverage percentage from JaCoCo report"
-          INDEX_PATH="target/site/jacoco/index.html"
-          export COVERAGE_PERCENTAGE=$(grep -oP '(?<=<td class="ctr2">).*?(?=%</td>)' $INDEX_PATH | sed 's/ //g')
-          export COVERAGE_PERCENTAGE=$(printf "%.2f" "$COVERAGE_PERCENTAGE")
-          echo "COVERAGE_PERCENTAGE= $COVERAGE_PERCENTAGE" >> $GITHUB_ENV
-          echo "COVERAGE_PERCENTAGE: $COVERAGE_PERCENTAGE"
+          jacoco_report="target/site/jacoco/jacoco.xml"
+          missed=$(xmllint --xpath "string(//report/counter[@type='INSTRUCTION']/@missed)" "$jacoco_report")
+          covered=$(xmllint --xpath "string(//report/counter[@type='INSTRUCTION']/@covered)" "$jacoco_report")
+          if [ -n "$covered" ] && [ -n "$missed" ]; then
+              total=$((covered + missed))
+              if [ $total -gt 0 ]; then
+                  percentage=$(echo "scale=2; $covered * 100 / $total" | bc -l)
+              else
+                  percentage="0"
+              fi
+          else
+              percentage="N/A"
+          fi
+          echo "COVERAGE_PERCENTAGE=$percentage" >> $GITHUB_ENV
+          echo "COVERAGE_PERCENTAGE: $percentage"
 
 
       - name: Upload JaCoCo Coverage report
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1
         with:
           name: coverage-report
           path: target/site/jacoco

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -1,3 +1,16 @@
+# ********************************************************************************
+#  Copyright (c) 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
+# *******************************************************************************/
+
 name: Java Linting
 
 on:
@@ -12,18 +25,17 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'
 
       - name: Set up JDK 17
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           java-version: '17'
           distribution: 'temurin'
           cache: maven
 
-      - name: Install dependencies
-        run: mvn install -DskipTests
-
       - name: Run Checkstyle
         run: mvn checkstyle:check
 

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,4 +1,17 @@
-name: Release to maven central
+# ********************************************************************************
+#  Copyright (c) 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
+# *******************************************************************************/
+
+name: Release to Maven Central
 
 on:
   workflow_dispatch:
@@ -19,25 +32,26 @@ jobs:
 
     - uses: actions/checkout@v4
       with:
+        submodules: 'recursive'
         token: ${{ secrets.BOT_GITHUB_TOKEN }}
 
     - name: Set up Apache Maven Central
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@v4
       with: # configure settings.xml
         distribution: 'temurin'
         java-version: '17'
-        server-id: ossrh
-        server-username: OSSRH_USER
-        server-password: OSSRH_PASSWORD
+        server-id: central
+        server-username: MAVEN_CENTRAL_USER
+        server-password: MAVEN_CENTRAL_PASSWORD
         gpg-private-key: ${{ secrets.ORG_GPG_PRIVATE_KEY }}
         gpg-passphrase: GPG_PASSPHRASE
 
     - name: Stage to Nexus and Release to Maven central
       run: |
-        mvn -B release:clean release:prepare -P release release:perform
+        mvn -B release:clean release:prepare release:perform
       env:
-        OSSRH_USER: ${{ secrets.ORG_OSSRH_USERNAME }}
-        OSSRH_PASSWORD: ${{ secrets.ORG_OSSRH_PASSWORD }}
+        MAVEN_CENTRAL_USER: ${{ secrets.CENTRAL_SONATYPE_TOKEN_USERNAME }}
+        MAVEN_CENTRAL_PASSWORD: ${{ secrets.CENTRAL_SONATYPE_TOKEN_PASSWORD }}
         GPG_PASSPHRASE: ${{ secrets.ORG_GPG_PASSPHRASE }}
         GH_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN }}
         GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN }}

diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "up-spec"]
+	path = up-spec
+	url = https://github.com/eclipse-uprotocol/up-spec
diff --git a/README.adoc b/README.adoc
@@ -3,7 +3,7 @@
 
 == Overview
 
-This library implements the https://github.com/eclipse-uprotocol/uprotocol-spec/blob/main/languages.adoc[uProtocol Language Specific Library Requirements] for Java defined in https://github.com/eclipse-uprotocol/uprotocol-spec/tree/main[uProtocol Specifications]. 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.3/languages.adoc[uProtocol v1.6.0-alpha.3 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.
 
@@ -27,35 +27,55 @@ To pull the Library from maven central, setting ${uprotocol.version} to the late
 === Using The Library
 
 .SDK Packages
-[#sdk-packages,width=100%,cols="1,2,5",options="header"]
+[#sdk-packages,width=100%,cols="1,5,2",options="header"]
 |===
 
-| Package | Protocol Layer | Purpose
+| Package | Purpose | Reference
 
 | xref:src/main/java/org/eclipse/uprotocol/communication/README.adoc[`*client*`]
-| https://github.com/eclipse-uprotocol/up-spec/tree/main/up-l3[Application Layer (uP-L3)]
 | Top level client-facing interfaces to communication with USubscription, UDiscovery, and UTwin services.
+| https://github.com/eclipse-uprotocol/up-spec/tree/v1.6.0-alpha.3/up-l3[Application Layer (uP-L3)]
 
 | xref:src/main/java/org/eclipse/uprotocol/communication/README.adoc[`*communication*`]
-| https://github.com/eclipse-uprotocol/up-spec/tree/main/up-l2[communication layer (uP-L2)] 
-| Common implementation of communication messaging patterns (publisher, subscriber, Rpcclient, RpcServer, etc..) tha t is build on top of the L1 transport interface (see below)
+| 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/tree/v1.6.0-alpha.3/up-l2[Communication Layer (uP-L2)] 
 
 | link:src/main/java/org/eclipse/uprotocol/transport/README.adoc[`*transport*`] 
-| https://github.com/eclipse-uprotocol/uprotocol-spec/blob/main/up-l1/README.adoc[Transport Layer (uP-L1)] 
 | 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.3/up-l1/README.adoc[Transport Layer (uP-L1)] 
 
 | link:src/main/java/org/eclipse/uprotocol/uri/README.adoc[`*uuri*`]
-| Basics 
 | uProtocol addressing scheme (UUri) builders, validators, and serializers. 
+| Basics 
 
 
 | link:src/main/java/org/eclipse/uprotocol/uuid/README.adoc[`*uuid*`]
-| Basics
 | uProtocol unique identifier builders, validators, and serializers.
+| Basics
 
 | link:src/main/java/org/eclipse/uprotocol/cloudevent/README.adoc[`*cloudevent*`] 
-| Legacy
 | A representation of uProtocol messages used in older versions of the specifications kept for backwards compatibility.
+| Legacy
 
 |===
 
+=== Building from Source
+
+. Clone the repository:
++
+[source,console]
+----
+git clone --recurse-submodules https://github.com/eclipse-uprotocol/up-java.git
+----
+. Navigate to the project directory:
++
+[source,console]
+----
+cd up-java
+----
+. Build the project using Maven:
++
+[source,console]
+----
+mvn clean install
+----