Jira/iwf 273 Add/fix javadocs for exception thrown (#265)

Author: longquanzheng

src/main/java/io/iworkflow/core/Client.java

@@ -8,6 +8,10 @@
 public abstract class Context {
     public abstract Long getWorkflowStartTimestampSeconds();
 
+    /**
+     * @return the StateExecutionId.
+     * Only applicable for state methods (waitUntil or execute)
+     */
     public abstract Optional<String> getStateExecutionId();
 
     public abstract String getWorkflowRunId();
@@ -16,11 +20,20 @@ public abstract class Context {
 
     public abstract String getWorkflowType();
 
-    // this is the start time of the first attempt of the API call. It's from ScheduledTimestamp of Cadence/Temporal activity.GetInfo
-    // require server version 1.2.2+, return -1 if server version is lower
+    /**
+     * @return the start time of the first attempt of the state method invocation.
+     * Only applicable for state methods (waitUntil or execute)
+     */
     public abstract Optional<Long> getFirstAttemptTimestampSeconds();
 
-    // Attempt starts from 1, and increased by 1 for every retry if retry policy is specified. It's from Attempt of Cadence/Temporal activity.GetInfo
-    // require server version 1.2.2+, return -1 if server version is lower
+    /**
+     * @return attempt starts from 1, and increased by 1 for every retry if retry policy is specified.
+     */
     public abstract Optional<Integer> getAttempt();
+
+    /**
+     * @return the requestId that is used to start the child workflow from state method.
+     * Only applicable for state methods (waitUntil or execute)
+     */
+    public abstract Optional<String> getChildWorkflowRequestId();
 }

src/main/java/io/iworkflow/core/Context.java

@@ -38,6 +38,7 @@
      * Only used when workflow has enabled {@link PersistenceOptions} CachingPersistenceByMemo
      * By default, it's false for high throughput support
      * flip to true to bypass the caching for strong consistent reads
+     * @return true if bypass caching for strong consistency
      */
     boolean bypassCachingForStrongConsistency() default false;
 }

src/main/java/io/iworkflow/core/RPC.java

@@ -182,7 +182,7 @@ public static <I> StateDecision singleNextState(final Class<? extends WorkflowSt
      * singleNextState as non-strongly typing required for input
      * @param stateClass required
      * @param stateInput optional, can be null
-     * @return
+     * @return state decision
      */
     public static StateDecision singleNextStateUntypedInput(final Class<? extends WorkflowState> stateClass, final Object stateInput) {
         return singleNextState(stateClass.getSimpleName(), stateInput, null);

src/main/java/io/iworkflow/core/StateDecision.java

@@ -388,6 +388,7 @@ private Context fromIdlContext(final io.iworkflow.gen.models.Context context, fi
                 .workflowRunId(context.getWorkflowRunId())
                 .workflowStartTimestampSeconds(context.getWorkflowStartedTimestamp())
                 .stateExecutionId(Optional.ofNullable(context.getStateExecutionId()))
+                .childWorkflowRequestId(context.getWorkflowRunId()+"-"+context.getStateExecutionId())
                 .attempt(attempt)
                 .firstAttemptTimestampSeconds(firstAttemptTimestamp)
                 .build();

src/main/java/io/iworkflow/core/WorkerService.java

@@ -16,8 +16,7 @@ public interface Communication {
      * trigger new state movements as the RPC results
      * NOTE: closing workflows like completing/failing are not supported
      * NOTE: Only used in RPC -- cannot be used in state APIs
-     *
-     * @param stateMovements
+     * @param stateMovements the state movements to trigger
      */
     void triggerStateMovements(final StateMovement... stateMovements);
 }

src/main/java/io/iworkflow/core/communication/Communication.java

@@ -2,7 +2,12 @@
 
 import io.iworkflow.core.ClientSideException;
 
-public class NoRunningWorkflowException extends WorkflowNotExistsOrOpenException {
+/**
+ * A friendly named exception to indicate that the workflow does not exist or exists but not running.
+ * It's the same as {@link WorkflowNotExistsException} but with a different name.
+ * It's subclass of {@link ClientSideException} with ErrorSubStatus.WORKFLOW_NOT_EXISTS_SUB_STATUS
+ */
+public class NoRunningWorkflowException extends WorkflowNotExistsException {
     public NoRunningWorkflowException(
             final ClientSideException exception) {
         super(exception);

src/main/java/io/iworkflow/core/exceptions/NoRunningWorkflowException.java

@@ -0,0 +1,14 @@
+package io.iworkflow.core.exceptions;
+
+import io.iworkflow.core.ClientSideException;
+
+/**
+ * A friendly named exception to indicate that the workflow does not exist
+ * It's subclass of {@link ClientSideException} with ErrorSubStatus.WORKFLOW_NOT_EXISTS_SUB_STATUS
+ */
+public class WorkflowNotExistsException extends ClientSideException {
+    public WorkflowNotExistsException(
+            final ClientSideException exception) {
+        super(exception);
+    }
+}