uProtocol 1.5.8

In 1.5.8 we have made the following changes: - URI: Condense definitions to a single form removing long and micro forms. Simplified the predicates to be easier to use - Updates to uTransport API to support pattern matching for all message types - Updates to UAttributes data model and removed UPayload placing the format in the header and the payload data directly in UMessage - Full 100% code coverage and test - Numerous linting and style fixes and corrections - Switch to Java 17 from Java 11 for CI builds - Refactoring uProtocol custom options into uoptions.proto to add SOME/IP serialization support and explicit topic declaration - Removed Optional variables passing to methods #116
eclipse-uprotocol · Jun 7, 2024 · d4e73a3 · d4e73a3
1 parent f555882
commit d4e73a3
Show file tree

Hide file tree

Showing 76 changed files with 2,806 additions and 9,403 deletions.
diff --git a/.github/workflows/build_and_test.yml b/.github/workflows/build_and_test.yml
@@ -11,10 +11,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up JDK 11
+    - name: Set up JDK 17
       uses: actions/setup-java@v3
       with:
-        java-version: '11'
+        java-version: '17'
         distribution: 'temurin'
         cache: maven
     - name: Build and Test with Maven

diff --git a/.github/workflows/build_deploy.yml b/.github/workflows/build_deploy.yml
@@ -18,7 +18,7 @@ jobs:
       uses: actions/setup-java@v3
       with: # configure settings.xml
         distribution: 'temurin'
-        java-version: '11'
+        java-version: '17'
         server-id: ossrh
         server-username: OSSRH_USER
         server-password: OSSRH_PASSWORD

diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -22,7 +22,7 @@ jobs:
         uses: actions/setup-java@v3
         with: # configure settings.xml
           distribution: 'temurin'
-          java-version: '11'
+          java-version: '17'
           server-id: ossrh
           server-username: OSSRH_USER
           server-password: OSSRH_PASSWORD

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -25,7 +25,7 @@ jobs:
       uses: actions/setup-java@v3
       with: # configure settings.xml
         distribution: 'temurin'
-        java-version: '11'
+        java-version: '17'
         server-id: ossrh
         server-username: OSSRH_USER
         server-password: OSSRH_PASSWORD

diff --git a/README.adoc b/README.adoc
@@ -24,46 +24,27 @@ To pull the Library from maven central, setting ${uprotocol.version} to the late
 
 === Using The Library
 
-
-.Package Folders
-[#pkg-folders,width=100%,cols="20%,80%",options="header"]
-|===
-
-| Folder | Purpose
-
-| `*builder*` or `*factory*`
-| Contains factory methods for creating uProtocol data types
-
-| `*serializer*`
-| Contains serializers to convert the objects into byte or string form representation of said object
-
-| `*validator*`
-| Contains validators to validate the data types and report errors if the objects are missing or incorrect
-
-|===
-
-
 .SDK Packages
 [#sdk-packages,width=100%,cols="20%,80%",options="header"]
 |===
 
 | Package | Purpose
 
+| xref:src/main/java/org/eclipse/uprotocol/communication/README.adoc[`*communication*`]
+| Top level client-facing  https://github.com/eclipse-uprotocol/up-spec/tree/main/up-l2[communication layer (uP-L2)] interfaces that applications and services use to implement the publisher/subscriber, notification, and RPC patterns on top of the transport layer (uTransport) API. 
+
 | link:src/main/java/org/eclipse/uprotocol/uri/README.adoc[`*uuri*`]
-| Uniform Resource Identifier (RFC3986), how uProtocol addresses things (devices, software, methods, topics, etc...) on the network
+| Builders, validators, and serializers for uProtocol addressing scheme (UUri). 
 
 
 | link:src/main/java/org/eclipse/uprotocol/uuid/README.adoc[`*uuid*`] 
 | Identifier used to uniquely identify (and timestamp) messages that are sent
 
 | link:src/main/java/org/eclipse/uprotocol/transport/README.adoc[`*transport*`] 
-| Interface declaration used for bidirectional point-2-point communication between uEs. This interface is then implemented by https://github.com/eclipse-uprotocol/uprotocol-spec/blob/main/upclient.adoc[uPClient] libraries for a given underlining transport (ex. Binder, MQTT, Zenoh, SOME/IP, DDS, HTTP, etc…)
+| https://github.com/eclipse-uprotocol/uprotocol-spec/blob/main/up-l1/README.adoc[uP-L1 Transport Layer] interface and data model that wraps communication middlewares like zenoh, mqtt, http, etc... into a thin and simple to use transport interface. This model is used by the communication layer (uP-L2) to send and receive messages and transports are expected to implement the link:src/main/java/org/eclipse/uprotocol/transport/UTransport.java[uTransport] interface.
 
 | link:src/main/java/org/eclipse/uprotocol/cloudevent/README.adoc[`*cloudevent*`] 
-| Common way to represent uProtocol messages using CloudEvent data model used by some transports (ex. MQTT, HTTP, etc…)
-
-| link:src/main/java/org/eclipse/uprotocol/rpc/README.adoc[`*rpc*`] 
-| RPC client and server-side interfaces that are to be implemented by uLink libraries
+| A representation of uProtocol messages used in older versions of the specifications and kept for backwards compatibility.
 
 |===
 
diff --git a/pom.xml b/pom.xml
@@ -23,10 +23,8 @@
     <url>https://github.com/eclipse-uprotocol/up-java/</url>    
 
     <properties>
-        <java.version>11</java.version>
+        <java.version>17</java.version>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <maven.compiler.source>11</maven.compiler.source>
-        <maven.compiler.target>11</maven.compiler.target>
         <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
         <junit.platform.version>1.9.1</junit.platform.version>
         <junit-jupiter.version>5.9.1</junit-jupiter.version>
@@ -35,7 +33,7 @@
         <slf4j.version>2.6.18</slf4j.version>
         <cloudevents.version>2.4.2</cloudevents.version>
         <protobuf.version>3.21.10</protobuf.version>
-        <git.tag.name>uprotocol-core-api-1.5.7</git.tag.name>
+        <git.tag.name>main</git.tag.name>
     </properties>
 
     <licenses>
@@ -90,8 +88,8 @@
                                 <argument>clone</argument>
                                 <argument>--branch</argument>
                                 <argument>${git.tag.name}</argument>
-                                <argument>https://github.com/eclipse-uprotocol/up-core-api.git</argument>
-                                <argument>${project.build.directory}/up-core-api</argument>
+                                <argument>https://github.com/eclipse-uprotocol/up-spec.git</argument>
+                                <argument>${project.build.directory}/up-spec</argument>
                             </arguments>
                             <!-- Allow non-zero exit code (error) -->
                             <successCodes>
@@ -108,7 +106,7 @@
                         </goals>
                         <configuration>
                             <executable>git</executable>
-                            <workingDirectory>${project.build.directory}/up-core-api</workingDirectory>
+                            <workingDirectory>${project.build.directory}/up-spec/up-core-api</workingDirectory>
                             <arguments>
                                 <argument>pull</argument>
                                 <argument>origin</argument>
@@ -125,7 +123,7 @@
                     <source>${java.version}</source>
                     <target>${java.version}</target>
                 </configuration>
-                <version>3.10.1</version> <!-- 3.8.1 -->
+                <version>3.13.0</version> <!-- 3.8.1 -->
             </plugin>
             <!-- clean lifecycle, see https://maven.apache.org/ref/current/maven-core/lifecycles.html#clean_Lifecycle -->
             <plugin>
@@ -152,9 +150,7 @@
                 </executions>
                 <configuration>
                     <protocArtifact>com.google.protobuf:protoc:3.17.3:exe:${os.detected.classifier}</protocArtifact>
-                    <protoSourceRoot>${project.build.directory}/up-core-api/uprotocol</protoSourceRoot>
-                    <outputDirectory>${project.build.directory}/generated-sources/protobuf/java</outputDirectory>
-
+                    <protoSourceRoot>${project.build.directory}/up-spec/up-core-api</protoSourceRoot>
                 </configuration>
             </plugin>
             <plugin>
@@ -196,12 +192,19 @@
                         <goals>
                             <goal>report</goal>
                         </goals>
+                        <!-- Exclude specific packages or classes -->
+                        <configuration>
+                            <excludes>
+                                <exclude>org/eclipse/uprotocol/core/**</exclude>
+                                <exclude>org/eclipse/uprotocol/v1/**</exclude>
+                            </excludes>
+                        </configuration>
                     </execution>
                 </executions>
                 <configuration>
                     <includes>
                         <include>**/cloudevent/**</include>
-                        <include>**/rpc/**</include>
+                        <include>**/communication/**</include>
                         <include>**/transport/**</include>
                         <include>**/uri/**</include>
                         <include>**/uuid/**</include>
@@ -415,14 +418,15 @@
       </repository>
     </distributionManagement>
 
+<!--
     <pluginRepositories>
         <pluginRepository>
             <id>dash-licenses-snapshots</id>
             <url>https://repo.eclipse.org/content/repositories/dash-licenses-releases/</url>
         </pluginRepository>
 
     </pluginRepositories>
-
+-->    
     <profiles>
         <profile>
             <id>release</id>

diff --git a/src/main/java/org/eclipse/uprotocol/cloudevent/README.adoc b/src/main/java/org/eclipse/uprotocol/cloudevent/README.adoc
@@ -5,98 +5,33 @@
 
 == Overview
 
-https://github.com/eclipse-uprotocol/up-spec/blob/main/basics/cloudevents.adoc[uProtocol CloudEvents] is a common message envelope that could be used to carry way to represent uProtocol transport layer information `UUri` (source), `UPayload`, and `UAttributes`. `CloudEvents` are used by a number of Device-2-Cloud and Cloud-2-Device based transports such as MQTT and HTTP, however it could also be used by any transport (ex. Binder).
+https://github.com/eclipse-uprotocol/up-spec/blob/main/basics/cloudevents.adoc[uProtocol CloudEvents] is a common message envelope that could be used to carry uProtocol messages across the transport. CloudEvents were historically used exclusively in older versions of uProtocol (ex. 1.3.6) and as such are maintained in this project for backwards compatibility support. 
 
+This module contains the following classes:
 
-=== CloudEventFactory
-Factory class that builds the various types of CloudEvents for uProtocol (publish, notification, request, response)
+.uProtocol CloudEvent Interfaces
+[#ce-interfaces, cols="1,3"]
+|===
+|Class |Description
 
+| `*UCloudEvent*`
+|A class that wraps a CloudEvent and provides utility methods to extract uProtocol specific attributes from the CloudEvent
 
-== Examples
+| `*UCloudEventAttributes*`
+|A class that represents the uProtocol specific attributes that are added to the CloudEvent
 
-=== Building an uuri
-[source,java]
-----
-      UEntity use = UEntity.newBuilder().setName("body.access").build();
-      UResource res= (UResource.newBuilder().setName("door").setInstance("front_left").setMessage("Door").build();
-      UUri uri = UUri.newBuilder().setEntity(use).setResource(res).build();
-      String source = LongUriSerializer.instance().serialize(uri);
-----
+|`*CloudEventFactory*`
+|Factory class that builds the various types of CloudEvents for uProtocol (publish, notification, request, response)
 
-=== Build proto payload
-[source,java]
+| `*CloudEventSerializer*`
+| A class that serializes and deserializes CloudEvents to and from protobuf and/or JSON formats used in some transports like MQTT in the past
 
-----
+| `*CloudEventValidator*`
+| Validates that the CloudEvent contains the correct uProtocol information and format for the various messages types (publish, notification, request, response)
 
-    io.cloudevents.v1.proto.CloudEvent cloudEventProto = io.cloudevents.v1.proto.CloudEvent.newBuilder()
-            .setSpecVersion("1.0")
-            .setId("hello")
-            .setSource("https://example.com")
-            .setType("example.demo")
-            .setProtoData(Any.newBuilder().build())
-            .build();
-    Any proto_payload= Any.pack(cloudEventProto);
+|===
 
 
-----
-
-=== Build UCloudEvent Attributes
-[source,java]
-
-----
-
-
-UCloudEventAttributes uCloudEventAttributes = new UCloudEventAttributes.UCloudEventAttributesBuilder()
-                .withHash("somehash")
-                .withPriority(UPriority.UPRIORITY_CS1)
-                .withTtl(3)
-                .withToken("someOAuthToken")
-                .build();
-
-----
-
-=== Build publish cloud event
-[source,java]
-
-----
-
-
-CloudEvent cloudEvent = CloudEventFactory.publish(source, protoPayload, uCloudEventAttributes);
-# test all attributes
- assertEquals("1.0", cloudEvent.getSpecVersion().toString());
- assertNotNull(cloudEvent.getId());
- assertEquals(source, cloudEvent.getSource().toString());
- assertEquals(UCloudEvent.getEventType(UMessageType.UMESSAGE_TYPE_PUBLISH), cloudEvent.getType());
- assertFalse(cloudEvent.getExtensionNames().contains("sink"));
- assertEquals("somehash", cloudEvent.getExtension("hash"));
- assertEquals(UPriority.UPRIORITY_CS1.name(), cloudEvent.getExtension("priority"));
- assertEquals(3, cloudEvent.getExtension("ttl"));
- assertArrayEquals(protoPayload.toByteArray(), Objects.requireNonNull(cloudEvent.getData()).toBytes());
-
-
-----
-
-
-=== Build cloudevent ↔ umessage 
-[source,java]
-
-----
-
-UMessage result = UCloudEvent.toMessage(cloudEvent);
-assertNotNull(result);
-assertTrue(UCloudEvent.getRequestId(cloudEvent).isPresent());
-assertTrue(UCloudEvent.getTtl(cloudEvent).isPresent());
-assertEquals(UCloudEvent.getTtl(cloudEvent).get(), result.getAttributes().getTtl());
-assertEquals(UCloudEvent.getPayload(cloudEvent).toByteString(),result.getPayload().getValue());
-assertEquals(UCloudEvent.getSource(cloudEvent),LongUriSerializer.instance().serialize(result.getSource()));
-assertTrue(UCloudEvent.getPriority(cloudEvent).isPresent());
-assertEquals(UCloudEvent.getPriority(cloudEvent).get(), result.getAttributes().getPriority().name());
-
-final CloudEvent cloudEvent1 = UCloudEvent.fromMessage(result);
-assertEquals(cloudEvent,cloudEvent1);
-
-
-----
 
 
 

diff --git a/src/main/java/org/eclipse/uprotocol/cloudevent/datamodel/UCloudEventAttributes.java b/src/main/java/org/eclipse/uprotocol/cloudevent/datamodel/UCloudEventAttributes.java
@@ -1,27 +1,15 @@
-/*
- * Copyright (c) 2023 General Motors GTO LLC
+/**
+ * SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
  *
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements.  See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership.  The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License.  You may obtain a copy of the License at
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
  *
- *   http://www.apache.org/licenses/LICENSE-2.0
+ * 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
  *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
- * specific language governing permissions and limitations
- * under the License.
- * SPDX-FileType: SOURCE
- * SPDX-FileCopyrightText: 2023 General Motors GTO LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-
 package org.eclipse.uprotocol.cloudevent.datamodel;
 
 import org.eclipse.uprotocol.v1.UPriority;