Reviewing and some updates

Author: Evanthx

core/src/main/java/io/temporal/samples/nexus_messaging/README.md

@@ -1,15 +1,15 @@
 This sample shows how to expose a long-running workflow's queries, updates, and signals as Nexus
 operations. There are two self-contained examples, each in its own directory:
 
-| | `callerpattern/` | `ondemandpattern/` |
-|---|---|---|
-| **Pattern** | Signal an existing workflow | Create and run workflows on demand |
-| **Who creates the workflow?** | The handler worker starts it on boot | The caller starts it via a Nexus operation |
-| **Who knows the workflow ID?** | Only the handler | The caller chooses and passes it in every operation |
-| **Nexus service** | `NexusGreetingService` | `NexusRemoteGreetingService` |
+| | `callerpattern/` | `ondemandpattern/`                                           |
+|---|---|--------------------------------------------------------------|
+| **Pattern** | Signal an existing workflow | Create and run workflows on demand, and send signals to them |
+| **Who creates the workflow?** | The handler worker starts it on boot | The caller starts it via a Nexus operation                   |
+| **Who knows the workflow ID?** | Only the handler | The caller chooses and passes it in every operation          |
+| **Nexus service** | `NexusGreetingService` | `NexusRemoteGreetingService`                                 |
 
-Each directory is fully self-contained with its own `service/`, `handler/`, and caller code. The
-`GreetingWorkflow` and `GreetingWorkflowImpl` classes are **identical** between the two — only the
+Each directory is fully self-contained for clarity. The
+`GreetingWorkflow`, `GreetingWorkflowImpl`, `GreetingActivity` and `GreetingActivityImpl` classes are **identical** between the two — only the
 Nexus service interface and its implementation differ. This highlights that the same workflow can be
 exposed through Nexus in different ways depending on whether the caller needs lifecycle control.
 

core/src/main/java/io/temporal/samples/nexus_messaging/callerpattern/README.md

@@ -4,6 +4,8 @@ The handler worker starts a single `GreetingWorkflow` with a fixed workflow ID.
 `NexusGreetingServiceImpl` holds that ID and routes every Nexus operation to it. The caller's
 inputs contain only business data — no workflow IDs.
 
+Refer to the on demand pattern examples and you will see how to expand this example to not just a single fixed workflow ID - the NexusGreetingServiceImpl simply needs to be able to map something from the inputs to a Workflow ID. For example if the workflow ID is a user ID with a prefix, then if the Nexus inputs include a User ID, then Nexus can simple prepend the same string to get the desired workflow ID.
+
 The caller workflow:
 1. Queries for supported languages (`getLanguages` — backed by a `@QueryMethod`)
 2. Changes the language to Arabic (`setLanguage` — backed by an `@UpdateMethod` that calls an activity)

core/src/main/java/io/temporal/samples/nexus_messaging/callerpattern/caller/CallerStarter.java

@@ -24,6 +24,8 @@ public static void main(String[] args) {
                 .setTaskQueue(CallerWorker.TASK_QUEUE)
                 .build());
 
+    // Launch the worker, passing in an identifier which the Nexus service will use
+    // to find the matching workflow  (See NexusGreetingServiceImpl::getWorkflowId)
     List<String> log = workflow.run("user-1");
     log.forEach(System.out::println);
   }

core/src/main/java/io/temporal/samples/nexus_messaging/callerpattern/caller/CallerWorkflowImpl.java

@@ -29,20 +29,30 @@ public class CallerWorkflowImpl implements CallerWorkflow {
 
   @Override
   public List<String> run(String userId) {
+
+    // Messages in the log array are passed back to the caller who will then log them to report what
+    // is happening.
+    // The same message is also logged for demo purposes, so that things are visible in the caller
+    // workflow output.
     List<String> log = new ArrayList<>();
 
-    // 👉 Call a Nexus operation backed by a query against the entity workflow.
+    // Call a Nexus operation backed by a query against the entity workflow.
+    // The workflow must already be running on the handler, otherwise you will
+    // get an error saying the workflow has already terminated.
     NexusGreetingService.GetLanguagesOutput languagesOutput =
         greetingService.getLanguages(new NexusGreetingService.GetLanguagesInput(false, userId));
     log.add("Supported languages: " + languagesOutput.getLanguages());
     logger.info("Supported languages: {}", languagesOutput.getLanguages());
 
-    // 👉 Call a Nexus operation backed by an update against the entity workflow.
+    // Following are examples for each of the three messaging types -
+    // update, query, then signal.
+
+    // Call a Nexus operation backed by an update against the entity workflow.
     Language previousLanguage =
         greetingService.setLanguage(
             new NexusGreetingService.SetLanguageInput(Language.ARABIC, userId));
 
-    // 👉 Call a Nexus operation backed by a query to confirm the language change.
+    // Call a Nexus operation backed by a query to confirm the language change.
     Language currentLanguage =
         greetingService.getLanguage(new NexusGreetingService.GetLanguageInput(userId));
     if (currentLanguage != Language.ARABIC) {
@@ -53,7 +63,7 @@ public List<String> run(String userId) {
     log.add("Language changed: " + previousLanguage.name() + " -> " + Language.ARABIC.name());
     logger.info("Language changed from {} to {}", previousLanguage, Language.ARABIC);
 
-    // 👉 Call a Nexus operation backed by a signal against the entity workflow.
+    // Call a Nexus operation backed by a signal against the entity workflow.
     greetingService.approve(new NexusGreetingService.ApproveInput("caller", userId));
     log.add("Workflow approved");
     logger.info("Workflow approved");

core/src/main/java/io/temporal/samples/nexus_messaging/callerpattern/handler/HandlerWorker.java

@@ -24,9 +24,13 @@ public static void main(String[] args) throws InterruptedException {
             service, WorkflowClientOptions.newBuilder().setNamespace(NAMESPACE).build());
 
     // Start the long-running entity workflow that backs the Nexus service, if not already running.
-    // The workflow ID is derived from the user ID using the same prefix as
-    // NexusGreetingServiceImpl.
+    // Create a workflow ID derived from the given user ID.
+    // This would be for a process that would create a workflow for each UserID,
+    // if you had a single long running workflow for all users then you could
+    // remove all the USER_IDs from the inputs and just make everything refer
+    // to a single workflow ID.
     String workflowId = NexusGreetingServiceImpl.getWorkflowId(USER_ID);
+
     GreetingWorkflow greetingWorkflow =
         client.newWorkflowStub(
             GreetingWorkflow.class,

core/src/main/java/io/temporal/samples/nexus_messaging/callerpattern/handler/NexusGreetingServiceImpl.java

@@ -21,6 +21,10 @@ public class NexusGreetingServiceImpl {
 
   static final String WORKFLOW_ID_PREFIX = "GreetingWorkflow_for_";
 
+  // This example assumes you might have multiple workflows, one for each user.
+  // If you had a single workflow for all users, then you could remove the
+  // getWorkflowId method, remove the user ID from each input, and just
+  // use the single worflow ID in the getWorkflowStub method below.
   public static String getWorkflowId(String userId) {
     return WORKFLOW_ID_PREFIX + userId;
   }

core/src/main/java/io/temporal/samples/nexus_messaging/ondemandpattern/caller/CallerRemoteWorkflowImpl.java

@@ -15,7 +15,10 @@ public class CallerRemoteWorkflowImpl implements CallerRemoteWorkflow {
 
   private static final Logger logger = Workflow.getLogger(CallerRemoteWorkflowImpl.class);
 
-  //  private static final String REMOTE_WORKFLOW_ID = "nexus-messaging-remote-greeting-workflow";
+  // This is going to create two workflows and send messages to them.
+  // We need to have an ID to differentiate so that Nexus knows how to name
+  // a workflow and then how to know the correct destination workflow.
+  // So here we are just going to define two workflow IDs with different user IDs.
   private static final String REMOTE_WORKFLOW_ONE = "UserId One";
   private static final String REMOTE_WORKFLOW_TWO = "UserId Two";
 
@@ -40,9 +43,19 @@ public class CallerRemoteWorkflowImpl implements CallerRemoteWorkflow {
 
   @Override
   public List<String> run() {
+    // Messages in the log array are passed back to the caller who will then log them to report what
+    // is happening.
+    // The same message is also logged for demo purposes, so that things are visible in the caller
+    // workflow output.
     List<String> log = new ArrayList<>();
 
-    // 👉 Async Nexus operation — starts a workflow on the handler and returns a handle.
+    // Each call is performed twice in this example. This assumes there are two users we want
+    // to process. The first call starts two workflows, one for each user.
+    // Subsequent calls perform different actions between the two users.
+    // There are examples for each of the three messaging types -
+    // update, query, then signal.
+
+    // This is an Async Nexus operation — starts a workflow on the handler and returns a handle.
     // Unlike the sync operations below (getLanguages, setLanguage, etc.), this does not block
     // until the workflow completes. It is backed by WorkflowRunOperation on the handler side.
     NexusOperationHandle<String> handleOne =

core/src/main/java/io/temporal/samples/nexus_messaging/ondemandpattern/handler/NexusRemoteGreetingServiceImpl.java

@@ -30,11 +30,6 @@ private GreetingWorkflow getWorkflowStub(String workflowId) {
 
   // Starts a new GreetingWorkflow with the caller-specified workflow ID. This is an async
   // Nexus operation backed by WorkflowRunOperation.
-  //
-  // fromWorkflowHandle (rather than fromWorkflowMethod) is used here because the Nexus operation
-  // input (RunFromRemoteInput) differs from the workflow method parameters — run() takes no args.
-  // The input is consumed to set the workflow ID on the stub; the workflow itself is invoked
-  // with no arguments via the ::run method reference.
   @OperationImpl
   public OperationHandler<NexusRemoteGreetingService.RunFromRemoteInput, String> runFromRemote() {
     return WorkflowRunOperation.fromWorkflowHandle(