docs: Add Documentation for Authentication

eclipse-kuksa · Feb 22, 2024 · ddcd0b6 · ddcd0b6
1 parent b449410
commit ddcd0b6
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 27 deletions.
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
@@ -25,7 +25,9 @@ fun connectInsecure(host: String, port: Int) {
             .usePlaintext()
             .build()
 
-        val connector = DataBrokerConnector(managedChannel)
+        // or jsonWebToken = null when authentication is disabled
+        val jsonWebToken = JsonWebToken("someValidJwt") 
+        val connector = DataBrokerConnector(managedChannel, jsonWebToken)
         try {
             dataBrokerConnection = connector.connect()
             // Connection to the Databroker successfully established
@@ -42,7 +44,10 @@ void connectInsecure(String host, int port) {
         .usePlaintext()
         .build();
 
-    DataBrokerConnector connector = new DataBrokerConnector(managedChannel);
+    // or jsonWebToken = null when authentication is disabled
+    JsonWebToken jsonWebToken = new JsonWebToken("someValidJwt");
+
+    DataBrokerConnector connector = new DataBrokerConnector(managedChannel, jsonWebToken);
     connector.connect(new CoroutineCallback<DataBrokerConnection>() {
         @Override
         public void onSuccess(DataBrokerConnection result) {
@@ -82,11 +87,15 @@ fun update() {
 fun subscribe() {
     val property = Property("Vehicle.Speed", listOf(Field.FIELD_VALUE))
     val propertyListener = object : PropertyListener {
-        override fun onPropertyChanged(vssPath: String, field: Types.Field, updatedValue: Types.DataEntry) {
-             when (vssPath) {
-                "Vehicle.Speed" -> {
-                    val speed = updatedValue.value.float
-                }
+        override fun onPropertyChanged(entryUpdates: List<KuksaValV1.EntryUpdate>) {
+            entryUpdates.forEach { entryUpdate ->
+                val updatedValue = entryUpdate.entry
+
+                // handle property change
+                when (updatedValue.path) {
+                    "Vehicle.Speed" -> {
+                        val speed = updatedValue.value.float
+                    }
             }
         }
     }
@@ -124,12 +133,12 @@ void subscribe() {
     Property property = new Property("Vehicle.Speed", Collections.singleton(Types.Field.FIELD_VALUE));
     dataBrokerConnection.subscribe(property, new PropertyListener() {
         @Override
-        public void onPropertyChanged(
-            @NonNull String vssPath,
-            @NonNull Types.Field field,
-            @NonNull Types.DataEntry updatedValue) {
-
-            switch (vssPath) {
+        public void onPropertyChanged(@NonNull List<EntryUpdate> entryUpdates) {
+            for (KuksaValV1.EntryUpdate entryUpdate : entryUpdates) {
+            Types.DataEntry updatedValue = entryUpdate.getEntry();
+
+            // handle property change
+            switch (updatedValue.getPath()) {
                 case "Vehicle.Speed":
                 float speed = updatedValue.getValue().getFloat();
             }
@@ -188,30 +197,31 @@ Vehicle.Speed:
 ```
 
 *Example model*
+
 ```kotlin
 data class VssSpeed @JvmOverloads constructor(
     override val `value`: Float = 0f,
-  ) : VssProperty<Float> {
+) : VssProperty<Float> {
     override val comment: String
-      get() = ""
+        get() = ""
 
     override val description: String
-      get() = "Vehicle speed."
+        get() = "Vehicle speed."
 
     override val type: String
-      get() = "sensor"
+        get() = "sensor"
 
     override val uuid: String
-      get() = "efe50798638d55fab18ab7d43cc490e9"
+        get() = "efe50798638d55fab18ab7d43cc490e9"
 
     override val vssPath: String
-      get() = "Vehicle.Speed"
+        get() = "Vehicle.Speed"
 
     override val children: Set<VssSpecification>
-      get() = setOf()
+        get() = setOf()
 
-    override val parentClass: KClass<*>?
-      get() = VssVehicle::class
+    override val parentClass: KClass<*>
+        get() = VssVehicle::class
 }
 ```
 

diff --git a/docs/kuksa-sdk_class-diagram.puml b/docs/kuksa-sdk_class-diagram.puml
@@ -19,6 +19,7 @@ package kuksa {
         class SetResponse
         class GetResponse
         class DataEntryError
+        class EntryUpdate
     }
 
     DataBrokerConnector -down-> DataBrokerException
@@ -32,6 +33,7 @@ package kuksa {
     DataBrokerSubscriber -up-> DataBrokerTransporter
     MultiListener -right-> DisconnectListener
     TimeoutConfig -left-* DataBrokerConnector
+    JsonWebToken -right-* DataBrokerConnector
 
     class DataBrokerConnector {
         + connect(): DataBrokerConnection
@@ -43,6 +45,8 @@ package kuksa {
     }
 
     class DataBrokerTransporter {
+        + jsonWebToken: JsonWebToken
+
         + fetch(vssPath: String, Collection<Field>): GetResponse
         + update(vssPath: String, Collection<Field>, Types.Datapoint): SetResponse
         + subscribe(vssPath: String, Field): Subscription
@@ -57,6 +61,7 @@ package kuksa {
 
     class DataBrokerConnection {
         + disconnectListeners: MultiListener<DisconnectListener>
+        + jsonWebToken: JsonWebToken
 
         + subscribe(Property, PropertyListener)
         + subscribe<T : VssSpecification>(T, Collection<Field>, VssSpecificationListener<T>)
@@ -70,7 +75,7 @@ package kuksa {
     }
 
     interface PropertyListener {
-        + onPropertyChanged(vssPath: String, Types.DataEntry)
+        + onPropertyChanged(List<EntryUpdate>)
         + onError(Throwable)
     }
 
@@ -89,6 +94,11 @@ package kuksa {
     interface DisconnectListener {
         + onDisconnect()
     }
+
+    class JsonWebToken {
+        + authScheme: String
+        + authParameters: String
+    }
 }
 
 DataBrokerConnector -up-> ManagedChannel

diff --git a/samples/src/main/java/com/example/sample/JavaActivity.java b/samples/src/main/java/com/example/sample/JavaActivity.java
@@ -28,6 +28,7 @@
 import org.eclipse.kuksa.DisconnectListener;
 import org.eclipse.kuksa.PropertyListener;
 import org.eclipse.kuksa.VssSpecificationListener;
+import org.eclipse.kuksa.authentication.JsonWebToken;
 import org.eclipse.kuksa.model.Property;
 import org.eclipse.kuksa.proto.v1.KuksaValV1;
 import org.eclipse.kuksa.proto.v1.KuksaValV1.GetResponse;
@@ -67,7 +68,9 @@ public void connectInsecure(String host, int port) {
             .usePlaintext()
             .build();
 
-        DataBrokerConnector connector = new DataBrokerConnector(managedChannel);
+        // or jsonWebToken = null when authentication is disabled
+        JsonWebToken jsonWebToken = new JsonWebToken("someValidToken");
+        DataBrokerConnector connector = new DataBrokerConnector(managedChannel, jsonWebToken);
         connector.connect(new CoroutineCallback<DataBrokerConnection>() {
             @Override
             public void onSuccess(DataBrokerConnection result) {
@@ -105,7 +108,10 @@ public void connectSecure(String host, int port, String overrideAuthority) {
         }
 
         ManagedChannel managedChannel = channelBuilder.build();
-        DataBrokerConnector connector = new DataBrokerConnector(managedChannel);
+
+        // or jsonWebToken = null when authentication is disabled
+        JsonWebToken jsonWebToken = new JsonWebToken("someValidToken");
+        DataBrokerConnector connector = new DataBrokerConnector(managedChannel, jsonWebToken);
         connector.connect(new CoroutineCallback<DataBrokerConnection>() {
             @Override
             public void onSuccess(DataBrokerConnection result) {

diff --git a/samples/src/main/kotlin/com/example/sample/KotlinActivity.kt b/samples/src/main/kotlin/com/example/sample/KotlinActivity.kt
@@ -32,6 +32,7 @@ import org.eclipse.kuksa.DataBrokerException
 import org.eclipse.kuksa.DisconnectListener
 import org.eclipse.kuksa.PropertyListener
 import org.eclipse.kuksa.VssSpecificationListener
+import org.eclipse.kuksa.authentication.JsonWebToken
 import org.eclipse.kuksa.model.Property
 import org.eclipse.kuksa.proto.v1.KuksaValV1
 import org.eclipse.kuksa.proto.v1.Types
@@ -56,7 +57,9 @@ class KotlinActivity : AppCompatActivity() {
                 .usePlaintext()
                 .build()
 
-            val connector = DataBrokerConnector(managedChannel)
+            // or jsonWebToken = null when authentication is disabled
+            val jsonWebToken = JsonWebToken("someValidToken")
+            val connector = DataBrokerConnector(managedChannel, jsonWebToken)
             try {
                 dataBrokerConnection = connector.connect()
                 dataBrokerConnection?.disconnectListeners?.register(disconnectListener)
@@ -89,7 +92,10 @@ class KotlinActivity : AppCompatActivity() {
 
         lifecycleScope.launch {
             val managedChannel = channelBuilder.build()
-            val connector = DataBrokerConnector(managedChannel)
+
+            // or jsonWebToken = null when authentication is disabled
+            val jsonWebToken = JsonWebToken("someValidToken")
+            val connector = DataBrokerConnector(managedChannel, jsonWebToken)
             try {
                 dataBrokerConnection = connector.connect()
                     .apply {