add some docs

temporalio · Nov 29, 2024 · b645a0f · b645a0f
1 parent b9a6148
commit b645a0f
Show file tree

Hide file tree

Showing 3 changed files with 96 additions and 80 deletions.
diff --git a/temporal-sdk/src/main/java/io/temporal/client/WithStartWorkflowOperation.java b/temporal-sdk/src/main/java/io/temporal/client/WithStartWorkflowOperation.java
@@ -26,7 +26,13 @@
 import java.util.concurrent.atomic.AtomicBoolean;
 import javax.annotation.Nullable;
 
-/** TODO: UwS */
+/**
+ * WithStartWorkflowOperation is a start workflow request that can be executed together with an
+ * update workflow request. See {@link WorkflowClient#startUpdateWithStart} and {@link
+ * WorkflowClient#executeUpdateWithStart}.
+ *
+ * @param <R> type of the workflow result
+ */
 @Experimental
 public final class WithStartWorkflowOperation<R> {
 
@@ -39,7 +45,7 @@ public final class WithStartWorkflowOperation<R> {
   private WithStartWorkflowOperation() {}
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a zero argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a zero argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
@@ -53,24 +59,24 @@ public WithStartWorkflowOperation(Functions.Func<R> startMethod) {
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a one argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a one argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
+   * @param arg1 first workflow method parameter
    */
   public <A1> WithStartWorkflowOperation(Functions.Func1<A1, R> startMethod, A1 arg1) {
     this.startMethod = () -> startMethod.apply(arg1);
     this.args = new Object[] {arg1};
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a two argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a two argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
-   * @param arg2 second request function parameter
+   * @param arg1 first workflow method parameter
+   * @param arg2 second workflow method parameter
    */
   public <A1, A2> WithStartWorkflowOperation(
       Functions.Func2<A1, A2, R> startMethod, A1 arg1, A2 arg2) {
@@ -79,13 +85,13 @@ public <A1, A2> WithStartWorkflowOperation(
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a three argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a three argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
-   * @param arg2 second request function parameter
-   * @param arg3 third request function parameter
+   * @param arg1 first workflow method parameter
+   * @param arg2 second workflow method parameter
+   * @param arg3 third workflow method parameter
    */
   public <A1, A2, A3> WithStartWorkflowOperation(
       Functions.Func3<A1, A2, A3, R> startMethod, A1 arg1, A2 arg2, A3 arg3) {
@@ -94,14 +100,14 @@ public <A1, A2, A3> WithStartWorkflowOperation(
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a four argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a four argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
-   * @param arg2 second request function parameter
-   * @param arg3 third request function parameter
-   * @param arg4 fourth request function parameter
+   * @param arg1 first workflow method parameter
+   * @param arg2 second workflow method parameter
+   * @param arg3 third workflow method parameter
+   * @param arg4 fourth workflow method parameter
    */
   public <A1, A2, A3, A4> WithStartWorkflowOperation(
       Functions.Func4<A1, A2, A3, A4, R> startMethod, A1 arg1, A2 arg2, A3 arg3, A4 arg4) {
@@ -110,15 +116,15 @@ public <A1, A2, A3, A4> WithStartWorkflowOperation(
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a five argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a five argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
-   * @param arg2 second request function parameter
-   * @param arg3 third request function parameter
-   * @param arg4 fourth request function parameter
-   * @param arg5 fifth request function parameter
+   * @param arg1 first workflow method parameter
+   * @param arg2 second workflow method parameter
+   * @param arg3 third workflow method parameter
+   * @param arg4 fourth workflow method parameter
+   * @param arg5 fifth workflow method parameter
    */
   public <A1, A2, A3, A4, A5> WithStartWorkflowOperation(
       Functions.Func5<A1, A2, A3, A4, A5, R> startMethod,
@@ -132,16 +138,16 @@ public <A1, A2, A3, A4, A5> WithStartWorkflowOperation(
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a six argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a six argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
-   * @param arg2 second request function parameter
-   * @param arg3 third request function parameter
-   * @param arg4 fourth request function parameter
-   * @param arg5 fifth request function parameter
-   * @param arg6 sixth request function parameter
+   * @param arg1 first workflow method parameter
+   * @param arg2 second workflow method parameter
+   * @param arg3 third workflow method parameter
+   * @param arg4 fourth workflow method parameter
+   * @param arg5 fifth workflow method parameter
+   * @param arg6 sixth workflow method parameter
    */
   public <A1, A2, A3, A4, A5, A6> WithStartWorkflowOperation(
       Functions.Func6<A1, A2, A3, A4, A5, A6, R> startMethod,
@@ -156,7 +162,7 @@ public <A1, A2, A3, A4, A5, A6> WithStartWorkflowOperation(
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a zero argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a zero argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
@@ -170,24 +176,24 @@ public WithStartWorkflowOperation(Functions.Proc startMethod) {
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a one argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a one argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
+   * @param arg1 first workflow method parameter
    */
   public <A1> WithStartWorkflowOperation(Functions.Proc1<A1> startMethod, A1 arg1) {
     this.startMethod = () -> startMethod.apply(arg1);
     this.args = new Object[] {arg1};
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a two argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a two argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
-   * @param arg2 second request function parameter
+   * @param arg1 first workflow method parameter
+   * @param arg2 second workflow method parameter
    */
   public <A1, A2> WithStartWorkflowOperation(
       Functions.Proc2<A1, A2> startMethod, A1 arg1, A2 arg2) {
@@ -196,13 +202,13 @@ public <A1, A2> WithStartWorkflowOperation(
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a three argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a three argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
-   * @param arg2 second request function parameter
-   * @param arg3 third request function parameter
+   * @param arg1 first workflow method parameter
+   * @param arg2 second workflow method parameter
+   * @param arg3 third workflow method parameter
    */
   public <A1, A2, A3> WithStartWorkflowOperation(
       Functions.Proc3<A1, A2, A3> startMethod, A1 arg1, A2 arg2, A3 arg3) {
@@ -211,14 +217,14 @@ public <A1, A2, A3> WithStartWorkflowOperation(
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a four argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a four argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
-   * @param arg2 second request function parameter
-   * @param arg3 third request function parameter
-   * @param arg4 fourth request function parameter
+   * @param arg1 first workflow method parameter
+   * @param arg2 second workflow method parameter
+   * @param arg3 third workflow method parameter
+   * @param arg4 fourth workflow method parameter
    */
   public <A1, A2, A3, A4> WithStartWorkflowOperation(
       Functions.Proc4<A1, A2, A3, A4> startMethod, A1 arg1, A2 arg2, A3 arg3, A4 arg4) {
@@ -227,15 +233,15 @@ public <A1, A2, A3, A4> WithStartWorkflowOperation(
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a five argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a five argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
-   * @param arg2 second request function parameter
-   * @param arg3 third request function parameter
-   * @param arg4 fourth request function parameter
-   * @param arg5 fifth request function parameter
+   * @param arg1 first workflow method parameter
+   * @param arg2 second workflow method parameter
+   * @param arg3 third workflow method parameter
+   * @param arg4 fourth workflow method parameter
+   * @param arg5 fifth workflow method parameter
    */
   public <A1, A2, A3, A4, A5> WithStartWorkflowOperation(
       Functions.Proc5<A1, A2, A3, A4, A5> startMethod,
@@ -249,16 +255,16 @@ public <A1, A2, A3, A4, A5> WithStartWorkflowOperation(
   }
 
   /**
-   * Returns a new {@link WithStartWorkflowOperation} for a six argument request.
+   * Creates a new {@link WithStartWorkflowOperation} for a six argument workflow method.
    *
    * @param startMethod method reference annotated with @WorkflowMethod of a proxy created through
    *     {@link WorkflowClient#newWorkflowStub(Class, WorkflowOptions)}.
-   * @param arg1 first request function parameter
-   * @param arg2 second request function parameter
-   * @param arg3 third request function parameter
-   * @param arg4 fourth request function parameter
-   * @param arg5 fifth request function parameter
-   * @param arg6 sixth request function parameter
+   * @param arg1 first workflow method parameter
+   * @param arg2 second workflow method parameter
+   * @param arg3 third workflow method parameter
+   * @param arg4 fourth workflow method parameter
+   * @param arg5 fifth workflow method parameter
+   * @param arg6 sixth workflow method parameter
    */
   public <A1, A2, A3, A4, A5, A6> WithStartWorkflowOperation(
       Functions.Proc6<A1, A2, A3, A4, A5, A6> startMethod,
@@ -272,18 +278,38 @@ public <A1, A2, A3, A4, A5, A6> WithStartWorkflowOperation(
     this.args = new Object[] {arg1, arg2, arg3, arg4, arg5, arg6};
   }
 
+  /**
+   * Creates a new {@link WithStartWorkflowOperation} from an untyped workflow stub.
+   *
+   * @param stub workflow stub to use
+   * @param resultClass class of the workflow return value
+   * @param args arguments to start the workflow
+   */
   public WithStartWorkflowOperation(
       WorkflowStub stub, Class<? extends R> resultClass, Object... args) {
     this.stub = stub;
     this.resultClass = resultClass;
     this.args = args;
   }
 
-  /** Returns the result of the update request. */
+  /**
+   * Obtains workflow result.
+   *
+   * @return the result of the workflow
+   */
   public R getResult() {
     return this.stub.getResult(this.resultClass);
   }
 
+  /**
+   * Mark the operation as having been invoked.
+   *
+   * @return false if the operation was already invoked
+   */
+  boolean markInvoked() {
+    return invoked.compareAndSet(false, true);
+  }
+
   @Nullable
   Functions.Proc getStartMethod() {
     return startMethod;
@@ -324,13 +350,4 @@ public String toString() {
   void setStub(WorkflowStub stub) {
     this.stub = stub;
   }
-
-  /**
-   * Mark the operation as having been invoked.
-   *
-   * @return false if the operation was already invoked
-   */
-  boolean markInvoked() {
-    return invoked.compareAndSet(false, true);
-  }
 }
diff --git a/temporal-sdk/src/main/java/io/temporal/client/WorkflowStub.java b/temporal-sdk/src/main/java/io/temporal/client/WorkflowStub.java
@@ -33,7 +33,6 @@
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
-import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
 /**
@@ -151,26 +150,30 @@ <R> WorkflowUpdateHandle<R> getUpdateHandle(
   WorkflowExecution start(Object... args);
 
   /**
-   * TODO: UwS
+   * TODO
    *
+   * @param updateOptions options that will be used to configure and start a new update request
+   * @param updateArgs update method arguments
+   * @param startOp workflow start operation
    * @param <R> type of the update workflow result
    * @return WorkflowUpdateHandle that can be used to get the result of the update
    */
   @Experimental
   <R> WorkflowUpdateHandle<R> startUpdateWithStart(
-      UpdateOptions<R> options, Object[] updateArgs, WithStartWorkflowOperation<?> startOp);
+      UpdateOptions<R> updateOptions, Object[] updateArgs, WithStartWorkflowOperation<?> startOp);
 
   /**
-   * TODO: UwS
+   * TODO
    *
+   * @param updateOptions options that will be used to configure and start a new update request
+   * @param updateArgs update method arguments
+   * @param startOp workflow start operation
    * @param <R> type of the update workflow result
    * @return update result
    */
   @Experimental
   <R> R executeUpdateWithStart(
-      @Nonnull UpdateOptions<R> updateOptions,
-      Object[] updateArgs,
-      @Nonnull WithStartWorkflowOperation<?> startOp);
+      UpdateOptions<R> updateOptions, Object[] updateArgs, WithStartWorkflowOperation<?> startOp);
 
   WorkflowExecution signalWithStart(String signalName, Object[] signalArgs, Object[] startArgs);
 

diff --git a/temporal-sdk/src/main/java/io/temporal/client/WorkflowStubImpl.java b/temporal-sdk/src/main/java/io/temporal/client/WorkflowStubImpl.java
@@ -132,9 +132,7 @@ public WorkflowExecution start(Object... args) {
 
   @Override
   public <R> WorkflowUpdateHandle<R> startUpdateWithStart(
-      @Nonnull UpdateOptions<R> updateOptions,
-      Object[] updateArgs,
-      @Nonnull WithStartWorkflowOperation<?> startOp) {
+      UpdateOptions<R> updateOptions, Object[] updateArgs, WithStartWorkflowOperation<?> startOp) {
     if (options == null) {
       throw new IllegalStateException(
           "Required parameter WorkflowOptions is missing in WorkflowStub");
@@ -190,9 +188,7 @@ public <R> WorkflowUpdateHandle<R> startUpdateWithStart(
 
   @Override
   public <R> R executeUpdateWithStart(
-      @Nonnull UpdateOptions<R> updateOptions,
-      Object[] updateArgs,
-      @Nonnull WithStartWorkflowOperation<?> startOp) {
+      UpdateOptions<R> updateOptions, Object[] updateArgs, WithStartWorkflowOperation<?> startOp) {
     return startUpdateWithStart(updateOptions, updateArgs, startOp).getResult();
   }