Add deprecation notices

Author: Quinn-With-Two-Ns

temporal-sdk/src/main/java/io/temporal/client/WorkflowClient.java

@@ -147,19 +147,11 @@ static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOp
    * @param workflowInterface interface that given workflow implements.
    * @param workflowId Workflow id.
    * @return Stub that implements workflowInterface and can be used to signal or query it.
+   * @deprecated Use {@link #newWorkflowStub(Class, WorkflowTargetOptions)} instead.
    */
+  @Deprecated
   <T> T newWorkflowStub(Class<T> workflowInterface, String workflowId);
 
-  /**
-   * Creates workflow client stub for a known execution. Use it to send signals or queries to a
-   * running workflow. Do not call methods annotated with @WorkflowMethod.
-   *
-   * @param workflowInterface interface that given workflow implements.
-   * @param workflowTargetOptions options that specify target workflow execution.
-   * @return Stub that implements workflowInterface and can be used to signal or query it.
-   */
-  <T> T newWorkflowStub(Class<T> workflowInterface, WorkflowTargetOptions workflowTargetOptions);
-
   /**
    * Creates workflow client stub for a known execution. Use it to send signals, updates, or queries
    * to a running workflow. Do not call methods annotated with @WorkflowMethod.
@@ -168,9 +160,21 @@ static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOp
    * @param workflowId Workflow id.
    * @param runId Run id of the workflow execution.
    * @return Stub that implements workflowInterface and can be used to signal, update, or query it.
+   * @deprecated Use {@link #newWorkflowStub(Class, WorkflowTargetOptions)} instead.
    */
+  @Deprecated
   <T> T newWorkflowStub(Class<T> workflowInterface, String workflowId, Optional<String> runId);
 
+  /**
+   * Creates workflow client stub for a known execution. Use it to send signals or queries to a
+   * running workflow. Do not call methods annotated with @WorkflowMethod.
+   *
+   * @param workflowInterface interface that given workflow implements.
+   * @param workflowTargetOptions options that specify target workflow execution.
+   * @return Stub that implements workflowInterface and can be used to signal or query it.
+   */
+  <T> T newWorkflowStub(Class<T> workflowInterface, WorkflowTargetOptions workflowTargetOptions);
+
   /**
    * Creates workflow untyped client stub that can be used to start a single workflow execution. Use
    * it to send signals or queries to a running workflow. Do not call methods annotated
@@ -201,7 +205,9 @@ static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOp
    *     workflowId is assumed.
    * @param workflowType type of the workflow. Optional as it is used for error reporting only.
    * @return Stub that can be used to start workflow and later to signal or query it.
+   * @deprecated Use {@link #newUntypedWorkflowStub(Optional, WorkflowTargetOptions)} instead.
    */
+  @Deprecated
   WorkflowStub newUntypedWorkflowStub(
       String workflowId, Optional<String> runId, Optional<String> workflowType);
 
@@ -212,6 +218,7 @@ WorkflowStub newUntypedWorkflowStub(
    * @param execution workflow id and optional run id for execution
    * @param workflowType type of the workflow. Optional as it is used for error reporting only.
    * @return Stub that can be used to start workflow and later to signal or query it.
+   * @deprecated Use {@link #newUntypedWorkflowStub(Optional, WorkflowTargetOptions)} instead.
    */
   WorkflowStub newUntypedWorkflowStub(WorkflowExecution execution, Optional<String> workflowType);
 

temporal-sdk/src/main/java/io/temporal/client/WorkflowTargetOptions.java

@@ -1,7 +1,9 @@
 package io.temporal.client;
 
 import io.temporal.api.common.v1.WorkflowExecution;
+import java.util.Objects;
 
+/** Options for targeting a specific workflow execution. */
 public final class WorkflowTargetOptions {
   public static WorkflowTargetOptions.Builder newBuilder() {
     return new WorkflowTargetOptions.Builder();
@@ -56,21 +58,28 @@ private Builder(WorkflowTargetOptions options) {
       this.firstExecutionRunId = options.firstExecutionRunId;
     }
 
+    /** Sets the workflowId of the target workflow. */
     public Builder setWorkflowId(String workflowId) {
       this.workflowId = workflowId;
       return this;
     }
 
+    /** Sets the runId of a specific execution of a workflow. */
     public Builder setRunId(String runId) {
       this.runId = runId;
       return this;
     }
 
+    /**
+     * Sets the runId of the first execution of a workflow. This is useful for targeting workflows
+     * that have been continued as new.
+     */
     public Builder setFirstExecutionRunId(String firstExecutionRunId) {
       this.firstExecutionRunId = firstExecutionRunId;
       return this;
     }
 
+    /** Sets both workflowId and runId from a WorkflowExecution object. */
     public Builder setWorkflowExecution(WorkflowExecution execution) {
       this.workflowId = execution.getWorkflowId();
       this.runId = execution.getRunId();
@@ -81,4 +90,33 @@ public WorkflowTargetOptions build() {
       return new WorkflowTargetOptions(workflowId, runId, firstExecutionRunId);
     }
   }
+
+  @Override
+  public String toString() {
+    return "WorkflowTargetOptions{"
+        + "workflowId='"
+        + workflowId
+        + '\''
+        + ", runId='"
+        + runId
+        + '\''
+        + ", firstExecutionRunId='"
+        + firstExecutionRunId
+        + '\''
+        + '}';
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (o == null || getClass() != o.getClass()) return false;
+    WorkflowTargetOptions that = (WorkflowTargetOptions) o;
+    return Objects.equals(workflowId, that.workflowId)
+        && Objects.equals(runId, that.runId)
+        && Objects.equals(firstExecutionRunId, that.firstExecutionRunId);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(workflowId, runId, firstExecutionRunId);
+  }
 }