Improve javadocs around interceptors (#1180)

Author: Spikhalskiy

temporal-sdk/src/main/java/io/temporal/common/interceptors/ActivityInboundCallsInterceptor.java

@@ -22,6 +22,14 @@
 import io.temporal.activity.ActivityExecutionContext;
 import io.temporal.common.Experimental;
 
+/**
+ * Intercepts inbound calls to the activity execution on the worker side.
+ *
+ * <p>Prefer extending {@link ActivityInboundCallsInterceptorBase} and overriding only the methods
+ * you need instead of implementing this interface directly. {@link
+ * ActivityInboundCallsInterceptorBase} provides correct default implementations to all the methods
+ * of this interface.
+ */
 @Experimental
 public interface ActivityInboundCallsInterceptor {
   final class ActivityInput {

temporal-sdk/src/main/java/io/temporal/common/interceptors/WorkerInterceptor.java

@@ -28,6 +28,15 @@
  */
 @Experimental
 public interface WorkerInterceptor {
+  /**
+   * Called when workflow class is instantiated. May create a {@link
+   * WorkflowInboundCallsInterceptor} instance. The instance must forward all the calls to {@code
+   * next} {@link WorkflowInboundCallsInterceptor}, but it may change the input parameters.
+   *
+   * @param next an existing interceptor instance to be proxied by the interceptor created inside
+   *     this method
+   * @return an interceptor that passes all the calls to {@code next}
+   */
   WorkflowInboundCallsInterceptor interceptWorkflow(WorkflowInboundCallsInterceptor next);
 
   ActivityInboundCallsInterceptor interceptActivity(ActivityInboundCallsInterceptor next);

temporal-sdk/src/main/java/io/temporal/common/interceptors/WorkflowClientCallsInterceptor.java

@@ -29,19 +29,26 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
+/**
+ * Intercepts calls to the {@link io.temporal.client.WorkflowClient} related to the lifecycle of a
+ * Workflow.
+ *
+ * <p>Prefer extending {@link WorkflowClientCallsInterceptorBase} and overriding only the methods
+ * you need instead of implementing this interface directly. {@link
+ * WorkflowClientCallsInterceptorBase} provides correct default implementations to all the methods
+ * of this interface.
+ */
 @Experimental
 public interface WorkflowClientCallsInterceptor {
   /**
-   * If you implement this method, {@link #signalWithStart} most likely needs * to be implemented
-   * too.
+   * If you implement this method, {@link #signalWithStart} most likely needs to be implemented too.
    *
    * @see #signalWithStart
    */
   WorkflowStartOutput start(WorkflowStartInput input);
 
   /**
-   * If you implement this method, {@link #signalWithStart} most likely needs * to be implemented
-   * too.
+   * If you implement this method, {@link #signalWithStart} most likely needs to be implemented too.
    *
    * @see #signalWithStart
    */
@@ -50,8 +57,7 @@ public interface WorkflowClientCallsInterceptor {
   WorkflowSignalWithStartOutput signalWithStart(WorkflowSignalWithStartInput input);
 
   /**
-   * If you implement this method, {@link #getResultAsync} most likely needs to * be implemented
-   * too.
+   * If you implement this method, {@link #getResultAsync} most likely needs to be implemented too.
    *
    * @see #getResultAsync
    */

temporal-sdk/src/main/java/io/temporal/common/interceptors/WorkflowInboundCallsInterceptor.java

@@ -24,8 +24,24 @@
 import javax.annotation.Nullable;
 
 /**
- * Intercepts calls to the workflow execution. Executes under workflow context. So all the
- * restrictions on the workflow code should be obeyed.
+ * Intercepts inbound calls to the workflow execution on the worker side.
+ *
+ * <p>An instance should be created in {@link
+ * WorkerInterceptor#interceptWorkflow(WorkflowInboundCallsInterceptor)}.
+ *
+ * <p>The calls to this interceptor are executed under workflow context, all the rules and
+ * restrictions on the workflow code apply. See {@link io.temporal.workflow}.
+ *
+ * <p>Prefer extending {@link WorkflowInboundCallsInterceptorBase} and overriding only the methods
+ * you need instead of implementing this interface directly. {@link
+ * WorkflowInboundCallsInterceptorBase} provides correct default implementations to all the methods
+ * of this interface.
+ *
+ * <p>The implementation must forward all the calls to {@code next}, but it may change the input
+ * parameters.
+ *
+ * @see WorkerInterceptor#interceptWorkflow(WorkflowInboundCallsInterceptor) for a definition of
+ *     "next" {@link WorkflowInboundCallsInterceptor}
  */
 @Experimental
 public interface WorkflowInboundCallsInterceptor {
@@ -115,9 +131,16 @@ public Object getResult() {
   }
 
   /**
-   * Called when workflow class is instantiated.
+   * Called when workflow class is instantiated. May create a {@link
+   * WorkflowOutboundCallsInterceptor} instance. The instance must forward all the calls to {@code
+   * outboundCalls}, but it may change the input parameters.
+   *
+   * <p>The instance should be passed into the {next.init(newWorkflowOutboundCallsInterceptor)}.
    *
-   * @param outboundCalls interceptor for calls that workflow makes to the SDK
+   * @param outboundCalls an existing interceptor instance to be proxied by the interceptor created
+   *     inside this method
+   * @see WorkerInterceptor#interceptWorkflow for the definition of "next" {@link
+   *     WorkflowInboundCallsInterceptor}
    */
   void init(WorkflowOutboundCallsInterceptor outboundCalls);
 

temporal-sdk/src/main/java/io/temporal/common/interceptors/WorkflowOutboundCallsInterceptor.java

@@ -36,13 +36,24 @@
 import javax.annotation.Nullable;
 
 /**
- * Can be used to intercept workflow code calls to the Temporal APIs. An instance should be created
- * through {@link WorkerInterceptor#interceptWorkflow(WorkflowInboundCallsInterceptor)}. An
- * interceptor instance must forward all the calls to the next interceptor passed to the
- * interceptExecuteWorkflow call.
+ * Can be used to intercept calls from to workflow code into the Temporal APIs.
  *
  * <p>The calls to the interceptor are executed in the context of a workflow and must follow the
  * same rules all the other workflow code follows.
+ *
+ * <p>Prefer extending {@link WorkflowOutboundCallsInterceptorBase} and overriding only the methods
+ * you need instead of implementing this interface directly. {@link
+ * WorkflowOutboundCallsInterceptorBase} provides correct default implementations to all the methods
+ * of this interface.
+ *
+ * <p>An instance may be created in {@link
+ * WorkflowInboundCallsInterceptor#init(WorkflowOutboundCallsInterceptor)} and set by passing it
+ * into {@code init} method of the {@code next} {@link WorkflowInboundCallsInterceptor} The
+ * implementation must forward all the calls to the outbound interceptor passed as a {@code
+ * outboundCalls} parameter to the {@code init} call.
+ *
+ * @see WorkerInterceptor#interceptWorkflow for the definition of "next" {@link
+ *     WorkflowInboundCallsInterceptor}.
  */
 @Experimental
 public interface WorkflowOutboundCallsInterceptor {
@@ -489,7 +500,7 @@ <R> R mutableSideEffect(
   void upsertSearchAttributes(Map<String, ?> searchAttributes);
 
   /**
-   * Intercepts creation of the workflow child thread.
+   * Intercepts creation of a workflow child thread.
    *
    * <p>Please note, that "workflow child thread" and "child workflow" are different and independent
    * concepts.