SDKS-3917 Journey Module Design and Prototype

Author: witrisna

external-idp/src/main/kotlin/com/pingidentity/idp/journey/IdpCallback.kt

@@ -40,7 +40,7 @@ class IdpCallback : AbstractCallback(), JourneyAware, RequestInterceptor {
 
     override lateinit var journey: Journey
 
-    override fun onAttribute(name: String, value: JsonElement) {
+    override fun init(name: String, value: JsonElement) {
         when (name) {
             "provider" -> this.provider = value.jsonPrimitive.content
             "clientId" -> this.clientId = value.jsonPrimitive.content
@@ -53,7 +53,7 @@ class IdpCallback : AbstractCallback(), JourneyAware, RequestInterceptor {
         }
     }
 
-    override fun asJson() = input(result.token, tokenType)
+    override fun payload() = input(result.token, tokenType)
 
     /**
      * Overrides the request with the resume request if initialized, else return the input request.

external-idp/src/main/kotlin/com/pingidentity/idp/journey/SelectIdpCallback.kt

@@ -25,7 +25,7 @@ class SelectIdpCallback : AbstractCallback() {
 
     var value: String= ""
 
-    override fun onAttribute(name: String, value: JsonElement) {
+    override fun init(name: String, value: JsonElement) {
         when (name) {
             "providers" -> {
                 providers = value.jsonArray.map {
@@ -35,7 +35,7 @@ class SelectIdpCallback : AbstractCallback() {
         }
     }
 
-    override fun asJson(): JsonObject {
+    override fun payload(): JsonObject {
         return input(value)
     }
 

foundation/journey-plugin/README.md

@@ -0,0 +1,156 @@
+<p align="center">
+  <a href="https://github.com/ForgeRock/ping-android-sdk">
+    <img src="https://www.pingidentity.com/content/dam/picr/nav/Ping-Logo-2.svg" alt="Ping Identity Logo" width="200">
+  </a>
+  <hr/>
+</p>
+
+# Journey Plugin
+
+# Journey-Plugin Module
+
+The `Journey-Plugin` module provides a mechanism to extend the functionality of the Journey Module by allowing you to
+implement custom callbacks and register them for use within the Journey workflow. This enables you to inject specific
+logic and data handling at various stages of the user journey.
+
+## Key Features
+
+1. **Callback Implementation:** You can implement your own callback logic by creating classes that adhere to
+   the `Callback` interface. This allows for highly customized behavior tailored to your application's needs.
+
+2. **Callback Registration:** The module provides a centralized registry (`CallbackRegistry`) where you can register
+   your implemented callbacks. This registration associates a Callback type (a string) with your callback
+   implementation, making it discoverable and usable by the Journey Module.
+
+3. **Loose Coupling:** By using the plugin mechanism, your custom logic remains separate from the core Journey Module,
+   promoting modularity and maintainability.
+
+## Getting Started
+
+### 1. Add Dependency
+
+To use the `Journey-Plugin` module in your project, you need to add it as a dependency, add the following line to your
+module's `build.gradle` file (usually the `app/build.gradle` or a feature module's `build.gradle`):
+
+```gradle
+implementation(project(":foundation:android"))
+implementation(project(":foundation:journey-plugin"))
+```
+
+**Note:** Ensure that the path `:foundation:android` correctly points to the location of your `foundation` Android
+module.
+
+### 2. Implement the `Callback` Interface
+
+Create a class that implements the `Callback` interface. This interface defines the contract for your custom callbacks.
+
+```kotlin
+import com.google.gson.JsonObject
+import com.example.foundation.android.journey.Action // Assuming Action interface is in this package
+
+interface Callback : Action {
+    /**
+     * Initializes the callback with the provided JSON object.
+     * @param jsonObject The JSON object containing the callback configuration.
+     * @return The initialized Callback instance.
+     */
+    fun init(jsonObject: JsonObject): Callback
+
+    /**
+     * Returns the payload of the callback.
+     */
+    fun payload(): JsonObject
+}
+```
+
+**Explanation of the `Callback` Interface:**
+
+* **`Callback : Action`**: Your callback interface extends an `Action` interface (the definition of `Action` is not
+  provided in the original text, but it likely represents a base interface for actions within the Journey Module).
+* **`fun init(jsonObject: JsonObject): Callback`**: This function is responsible for initializing your callback instance
+  using a JSON object provided by the Journey Module. This JSON object will likely contain configuration parameters
+  specific to this callback instance. The function should return the initialized `Callback` object.
+* **`fun payload(): JsonObject`**: This function should return a `JsonObject` representing the output or data payload of
+  your callback after it has been executed. This payload will likely be used by subsequent steps in the Journey
+  workflow.
+* **`AbstractCallback : Callback`**: Provides a base implementation of the `Callback` interface. This class can
+  contain common logic or properties that all callbacks might share, reducing code duplication.
+*
+
+**Example Implementation:**
+
+Let's say you want to create a callback that collect the username.
+
+```kotlin
+
+class NameCallback : AbstractCallback() {
+    var prompt: String = ""
+        private set
+
+    //Input
+    var name: String = ""
+
+    override fun init(name: String, value: JsonElement) {
+        when (name) {
+            "prompt" -> this.prompt = value.jsonPrimitive.content
+        }
+    }
+
+    override fun payload() = input(name)
+
+}
+```
+
+### 3. Register Your Callback
+
+To make your custom callback available to the Journey Module, you need to register it with the `CallbackRegistry`. This
+is typically done during your module's startup process. The Journey Module likely provides a mechanism to initialize
+modules.
+
+**Example using `ModuleInitializer`:**
+
+```kotlin
+import com.example.foundation.android.journey.CallbackRegistry
+import com.example.foundation.android.journey.ModuleInitializer
+
+class CollectorRegistry : ModuleInitializer() {
+
+    /**
+     * Initializes the module by registering custom callbacks.
+     */
+    override fun initialize() {
+        CallbackRegistry.register("ChoiceCallback", ::ChoiceCallback)
+        CallbackRegistry.register("NameCallback", ::NameCallback) // Example from the original text
+        // Register other custom callbacks here
+    }
+}
+```
+
+**Explanation:**
+
+* **`CollectorRegistry : ModuleInitializer()`**: This class implements the `ModuleInitializer` interface (assuming this
+  interface exists in the Journey Module).
+* **`override fun initialize()`**: This function is called during the module's initialization.
+* **`CallbackRegistry.register("CHOICE_CALLBACK", ::ChoiceCallback)`**: This line registers your `ChoiceCallback`
+  implementation.
+    * `"ChoiceCallback"`: This is a unique identifier (a string) that the Journey Module will use to invoke this
+      specific callback.
+    * `::ChoiceCallback`: This is a class reference to your `ChoiceCallback` implementation. The `CallbackRegistry`
+      likely uses this reference to create instances of your callback when needed.
+
+**Important Considerations:**
+
+* **Callback Name:** Ensure that the identifier you use when registering your callback matches the one Callback name
+  from server.
+* **Module Initialization:** Ensure you register the ModuleInitializer in the AndroidManifest.xml file.
+```xml
+<provider
+        android:name=".journey.CollectorRegistry"
+        android:authorities="${applicationId}.collectorRegistry"
+        android:enabled="true"
+        android:exported="false"/>
+```
+* **Testing:** Thoroughly test your custom callbacks to ensure they function as expected within the Journey workflow.
+
+By following these steps, you can effectively use the `Journey-Plugin` module to extend the Journey Module with your own
+custom callback logic, making your application more flexible and adaptable to specific user journey requirements.

foundation/journey-plugin/src/main/kotlin/com/pingidentity/journey/plugin/AbstractCallback.kt

@@ -9,6 +9,7 @@ package com.pingidentity.journey.plugin
 
 import kotlinx.serialization.json.JsonArray
 import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.buildJsonArray
 import kotlinx.serialization.json.buildJsonObject
@@ -22,18 +23,21 @@ abstract class AbstractCallback : Callback {
     lateinit var json: JsonObject
         protected set
 
-    protected abstract fun onAttribute(name: String, value: JsonElement)
+    protected abstract fun init(name: String, value: JsonElement)
 
-    override fun init(jsonObject: JsonObject) {
+    override fun init(jsonObject: JsonObject) : Callback {
         this.json = jsonObject
         jsonObject["output"]?.jsonArray?.forEach { outputItem ->
             val outputObject = outputItem.jsonObject
             outputObject["name"]?.jsonPrimitive?.content?.let { name ->
                 outputObject["value"]?.let { value ->
-                    onAttribute(name, value)
+                    if (value !is JsonNull) {
+                        init(name, value)
+                    }
                 }
             }
         }
+        return this
     }
 
     fun input(vararg value: Any): JsonObject {
@@ -112,5 +116,5 @@ abstract class AbstractCallback : Callback {
         return json
     }
 
-    override fun asJson(): JsonObject = json
+    override fun payload(): JsonObject = json
 }

foundation/journey-plugin/src/main/kotlin/com/pingidentity/journey/plugin/Callback.kt

@@ -11,11 +11,21 @@ import com.pingidentity.orchestrate.Action
 import com.pingidentity.orchestrate.ContinueNode
 import kotlinx.serialization.json.JsonObject
 
+/**
+ * Callback interface for handling actions in the journey plugin.
+ */
 interface Callback : Action {
-    fun init(jsonObject: JsonObject)
+    /**
+     * Initializes the callback with the provided JSON object.
+     * @param jsonObject The JSON object containing the callback configuration.
+     *   * @return The initialized Callback instance.
+     */
+    fun init(jsonObject: JsonObject): Callback
 
-    //Callback is more self-contained, it created its own json without depending on other Callback
-    fun asJson(): JsonObject
+    /**
+     * Returns the payload of the callback.
+     */
+    fun payload(): JsonObject
 }
 
 /**

foundation/journey-plugin/src/main/kotlin/com/pingidentity/journey/plugin/CallbackRegistry.kt

@@ -9,42 +9,52 @@ package com.pingidentity.journey.plugin
 
 import com.pingidentity.orchestrate.ContinueNode
 import kotlinx.serialization.json.JsonArray
-import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.jsonObject
 import kotlinx.serialization.json.jsonPrimitive
 
+/**
+ * CallbackRegistry is responsible for managing the registration and retrieval of callbacks.
+ * It allows for the registration of callbacks by type and provides a method to retrieve
+ * callbacks based on a JSON array.
+ */
 object CallbackRegistry {
     private val callbacks: MutableMap<String, () -> Callback> = HashMap()
-    val derivedCallbacks: MutableList<(JsonObject) -> String?> = mutableListOf()
 
+    /**
+     * Registers a callback with the specified type.
+     * @param type The type of the callback.
+     * @param block A lambda function that returns an instance of the callback.
+     */
     fun register(type: String, block: () -> Callback) {
         callbacks[type] = block
     }
 
-    fun registerDerived(block: (JsonObject) -> String?) {
-        derivedCallbacks.add(block)
-    }
-
     /**
-     * Injects the DaVinci and ContinueNode instances into the collectors.
-     * @param davinci The DaVinci instance to be injected.
-     * @param continueNode The ContinueNode instance to be injected.
+     * Injects the Journey instances into the callbacks.
+     * @param journey The Journey instance to be injected.
+     * @param continueNode The ContinueNode instance.
      */
-    fun inject(journey: Journey,  continueNode: ContinueNode) {
+    fun inject(journey: Journey, continueNode: ContinueNode) {
         continueNode.callbacks.forEach { callback ->
             if (callback is JourneyAware) {
                 callback.journey = journey
             }
         }
     }
 
-
+    /**
+     * Retrieves a list of callbacks based on the provided JSON array.
+     * @param array The JSON array containing the callback types.
+     *   * @return A list of initialized Callback instances.
+     */
     fun callback(array: JsonArray): List<Callback> {
         val list = mutableListOf<Callback>()
         array.forEach { item ->
             val jsonObject = item.jsonObject
             val type = jsonObject["type"]?.jsonPrimitive?.content
-            callbacks[type]?.let { list.add(it().apply { init(jsonObject) }) }
+            callbacks[type]?.let {
+                list.add(it().init(jsonObject))
+            }
         }
         return list
     }

foundation/journey-plugin/src/test/kotlin/com/pingidentity/journey/plugin/CallbackRegistryTest.kt

@@ -58,20 +58,20 @@ class CallbackRegistryTest {
 }
 
 class DummyCallback : Callback {
-    override fun init(jsonObject: JsonObject) {
-        // Do nothing
+    override fun init(jsonObject: JsonObject): Callback {
+        return this
     }
 
-    override fun asJson(): JsonObject {
+    override fun payload(): JsonObject {
         return buildJsonObject { }
     }
 }
 class Dummy2Callback : Callback {
-    override fun init(jsonObject: JsonObject) {
-        // Do nothing
+    override fun init(jsonObject: JsonObject): Callback {
+        return this
     }
 
-    override fun asJson(): JsonObject {
+    override fun payload(): JsonObject {
         return buildJsonObject { }
     }
 }

foundation/logger/src/main/kotlin/com/pingidentity/logger/Standard.kt

@@ -20,7 +20,16 @@ open class Standard : Logger {
      * @param message The message to log.
      */
     override fun d(message: String) {
-        Log.d(TAG, message)
+        if (message.length > 4000) {
+            var i = 0
+            while (i < message.length) {
+                val end = (i + 4000).coerceAtMost(message.length)
+                Log.d(TAG, message.substring(i, end))
+                i = end
+            }
+        } else {
+            Log.d(TAG, message)
+        }
     }
 
     /**

foundation/orchestrate/src/main/kotlin/com/pingidentity/orchestrate/SharedContext.kt

@@ -12,6 +12,10 @@ package com.pingidentity.orchestrate
  * @property map The map that holds the shared context.
  */
 class SharedContext(val map: MutableMap<String, Any>) : MutableMap<String, Any> by map {
+
+    infix fun String.to(value: Any) {
+        this@SharedContext[this] = value
+    }
     /**
      * Returns the value of a specific key from the shared context.
      * @param key The key for which the value is to be returned.