Updated documentation. (#147)

* Comments and moved MethodRetry to common

* Updated javadoc

* PR comments

Author: mfateev

README.md

@@ -29,7 +29,7 @@ Add *cadence-client* as a dependency to your *pom.xml*:
     <dependency>
       <groupId>com.uber</groupId>
       <artifactId>cadence-client</artifactId>
-      <version>0.2.0-SPANPSHOT</version>
+      <version>0.2.0-SNAPSHOT</version>
     </dependency>
 
 # Overview
@@ -246,8 +246,9 @@ It can also answer to synchronous queries and receive external events (also know
 A workflow must define an interface class. All of its methods must have one of the following annotations:
 - @WorkflowMethod indicates an entry point to a workflow. It contains parameters such as timeouts and a task list. Required
 parameters (like executionStartToCloseTimeoutSeconds) that are not specified through the annotation must be provided at runtime.
-- @Signal indicates a method that reacts to external signals. It must have a `void` return type.
-- @Query indicates a method that reacts to synchronous query requests.
+- @SignalMethod indicates a method that reacts to external signals. It must have a `void` return 
+type.
+- @QueryMethod indicates a method that reacts to synchronous query requests.
 You can have more than one method with the same annotation.
 ```java
 public interface FileProcessingWorkflow {
@@ -372,17 +373,18 @@ with different options.
 ### Calling Activities Asynchronously
 
 Sometimes workflows need to perform certain operations in parallel.
-The `Workflow.async` static method allows you to invoke any activity asynchronously. The call returns a `Promise` result immediately.
+The `Async` class static methods allow you to invoke any activity asynchronously. The calls return a `Promise` result immediately.
 `Promise` is similar to both Java `Future` and `CompletionStage`. The `Promise` `get` blocks until a result is available.
 It also exposes the `thenApply` and `handle` methods. See the `Promise` JavaDoc for technical details about differences with `Future`.
 
 To convert a synchronous call
 ```java
 String localName = activities.download(surceBucket, sourceFile);
 ```
-to asynchronous style, the method reference is passed to `Workflow.async` followed by activity arguments:
+to asynchronous style, the method reference is passed to `Async.function` or `Async.procedure` 
+followed by activity arguments:
 ```java
-Promise<String> localNamePromise = Workflow.async(activities::download, surceBucket, sourceFile);
+Promise<String> localNamePromise = Async.function(activities::download, surceBucket, sourceFile);
 ```
 Then to wait synchronously for the result:
 ```java
@@ -396,7 +398,7 @@ public void processFile(Arguments args) {
     try {
         // Download all files in parallel.
         for (String sourceFilename : args.getSourceFilenames()) {
-            Promise<String> localName = Workflow.async(activities::download, args.getSourceBucketName(), sourceFilename);
+            Promise<String> localName = Async.function(activities::download, args.getSourceBucketName(), sourceFilename);
             localNamePromises.add(localName);
         }
         // allOf converts a list of promises to a single promise that contains a list of each promise value.
@@ -410,7 +412,7 @@ public void processFile(Arguments args) {
         // Upload all results in parallel.
         List<Promise<Void>> uploadedList = new ArrayList<>();
         for (String processedName : processedNames) {
-            Promise<Void> uploaded = Workflow.async(activities::upload, args.getTargetBucketName(), args.getTargetFilename(), processedName);
+            Promise<Void> uploaded = Async.procedure(activities::upload, args.getTargetBucketName(), args.getTargetFilename(), processedName);
             uploadedList.add(uploaded);
         }
         // Wait for all uploads to complete.
@@ -439,7 +441,7 @@ Besides activities, a workflow can also orchestrate other workflows.
  the timeouts and task list if they differ from the ones defined in the @WorkflowMethod annotation or parent workflow.
 
  The first call to the child workflow stub must always be to a method annotated with @WorkflowMethod. Similarly to activities, a call
- can be synchronous or asynchronous using `Workflow.async`. The synchronous call blocks until a child workflow completes. The asynchronous call
+ can be made synchronous or asynchronous by using `Async#function` or `Async#procedure`. The synchronous call blocks until a child workflow completes. The asynchronous call
  returns a `Promise` that can be used to wait for the completion. After an async call returns the stub, it can be used to send signals to the child
  by calling methods annotated with `@SignalMethod`. Querying a child workflow by calling methods annotated with @QueryMethod
  from within workflow code is not supported. However, queries can be done from activities
@@ -470,11 +472,11 @@ public static class GreetingWorkflowImpl implements GreetingWorkflow {
 
         // Workflows are stateful, so a new stub must be created for each new child.
         GreetingChild child1 = Workflow.newChildWorkflowStub(GreetingChild.class);
-        Promise<String> greeting1 = Workflow.async(child1::composeGreeting, "Hello", name);
+        Promise<String> greeting1 = Async.function(child1::composeGreeting, "Hello", name);
 
         // Both children will run concurrently.
         GreetingChild child2 = Workflow.newChildWorkflowStub(GreetingChild.class);
-        Promise<String> greeting2 = Workflow.async(child2::composeGreeting, "Bye", name);
+        Promise<String> greeting2 = Async.function(child2::composeGreeting, "Bye", name);
 
         // Do something else here.
         ...
@@ -497,7 +499,7 @@ public static class GreetingWorkflowImpl implements GreetingWorkflow {
     @Override
     public String getGreeting(String name) {
         GreetingChild child = Workflow.newChildWorkflowStub(GreetingChild.class);
-        Promise<String> greeting = Workflow.async(child::composeGreeting, "Hello", name);
+        Promise<String> greeting = Async.function(child::composeGreeting, "Hello", name);
         child.updateName("Cadence");
         return greeting.get();
     }
@@ -518,7 +520,7 @@ This design puts the following constraints on the workflow implementation:
 Always do this in activities.
 - Don’t perform any IO or service calls as they are not usually deterministic. Use activities for this.
 - Only use `Workflow.currentTimeMillis()` to get the current time inside a workflow.
-- Do not use native Java `Thread` or any other multi-threaded classes like `ThreadPoolExecutor`. Use `Async.invoke`
+- Do not use native Java `Thread` or any other multi-threaded classes like `ThreadPoolExecutor`. Use `Async.function` or `Async.procedure`
 to execute code asynchronously.
 - Don't use any synchronization, locks, and other standard Java blocking concurrency-related classes besides those provided
 by the Workflow class. There is no need in explicit synchronization because multi-threaded code inside a workflow is

src/main/java/com/uber/cadence/activity/Activity.java

@@ -25,8 +25,176 @@
 import java.util.concurrent.CancellationException;
 
 /**
- * Use this method from within activity implementation to get information about activity task and
- * heartbeat.
+ * An activity is the implementation of a particular task in the business logic.
+ *
+ * <h2>Activity Interface</h2>
+ *
+ * <p>Activities are defined as methods of a plain Java interface. Each method defines a single
+ * activity type. A single workflow can use more than one activity interface and call more than one
+ * activity method from the same interface. The only requirement is that activity method arguments
+ * and return values are serializable to a byte array using the provided {@link
+ * com.uber.cadence.converter.DataConverter} implementation. The default implementation uses JSON
+ * serializer, but an alternative implementation can be easily configured.
+ *
+ * <p>Example of an interface that defines four activities:
+ *
+ * <pre><code>
+ * public interface FileProcessingActivities {
+ *
+ *     void upload(String bucketName, String localName, String targetName);
+ *
+ *     String download(String bucketName, String remoteName);
+ *
+ *     {@literal @}ActivityMethod(scheduleToCloseTimeoutSeconds = 2)
+ *     String processFile(String localName);
+ *
+ *     void deleteLocalFile(String fileName);
+ * }
+ *
+ * </code></pre>
+ *
+ * An optional {@literal @}{@link ActivityMethod} annotation can be used to specify activity options
+ * like timeouts or a task list. Required options that are not specified through the annotation must
+ * be specified at run time.
+ *
+ * <h2>Activity Implementation</h2>
+ *
+ * <p>Activity implementation is an implementation of an activity interface. A single instance of
+ * the activity's implementation is shared across multiple simultaneous activity invocations.
+ * Therefore, the activity implementation code must be <i>thread safe</i>.
+ *
+ * <p>The values passed to activities through invocation parameters or returned through a result
+ * value are recorded in the execution history. The entire execution history is transferred from the
+ * Cadence service to workflow workers when a workflow state needs to recover. A large execution
+ * history can thus adversely impact the performance of your workflow. Therefore, be mindful of the
+ * amount of data you transfer via activity invocation parameters or return values. Other than that,
+ * no additional limitations exist on activity implementations.
+ *
+ * <pre><code>
+ * public class FileProcessingActivitiesImpl implements FileProcessingActivities {
+ *
+ *     private final AmazonS3 s3Client;
+ *
+ *     private final String localDirectory;
+ *
+ *     void upload(String bucketName, String localName, String targetName) {
+ *         File f = new File(localName);
+ *         s3Client.putObject(bucket, remoteName, f);
+ *     }
+ *
+ *     String download(String bucketName, String remoteName, String localName) {
+ *         // Implementation omitted for brevity.
+ *         return downloadFileFromS3(bucketName, remoteName, localDirectory + localName);
+ *     }
+ *
+ *     String processFile(String localName) {
+ *         // Implementation omitted for brevity.
+ *         return compressFile(localName);
+ *     }
+ *
+ *     void deleteLocalFile(String fileName) {
+ *         File f = new File(localDirectory + fileName);
+ *         f.delete();
+ *     }
+ * }
+ * </code></pre>
+ *
+ * <h3>Accessing Activity Info</h3>
+ *
+ * <p>The {@link Activity} class provides static getters to access information about the workflow
+ * that invoked it. Note that this information is stored in a thread-local variable. Therefore,
+ * calls to Activity accessors succeed only in the thread that invoked the activity function.
+ *
+ * <pre><code>
+ * public class FileProcessingActivitiesImpl implements FileProcessingActivities {
+ *
+ *      {@literal @}Override
+ *      public String download(String bucketName, String remoteName, String localName) {
+ *         log.info("domain=" +  Activity.getDomain());
+ *         WorkflowExecution execution = Activity.getWorkflowExecution();
+ *         log.info("workflowId=" + execution.getWorkflowId());
+ *         log.info("runId=" + execution.getRunId());
+ *         ActivityTask activityTask = Activity.getTask();
+ *         log.info("activityId=" + activityTask.getActivityId());
+ *         log.info("activityTimeout=" + activityTask.getStartToCloseTimeoutSeconds());
+ *         return downloadFileFromS3(bucketName, remoteName, localDirectory + localName);
+ *      }
+ *      ...
+ *  }
+ * </code></pre>
+ *
+ * <h3>Asynchronous Activity Completion</h3>
+ *
+ * <p>Sometimes an activity lifecycle goes beyond a synchronous method invocation. For example, a
+ * request can be put in a queue and later a reply comes and is picked up by a different worker
+ * process. The whole request-reply interaction can be modeled as a single Cadence activity.
+ *
+ * <p>To indicate that an activity should not be completed upon its method return, call {@link
+ * Activity#doNotCompleteOnReturn()} from the original activity thread. Then later, when replies
+ * come, complete the activity using {@link com.uber.cadence.client.ActivityCompletionClient}. To
+ * correlate activity invocation with completion use either {@code TaskToken} or workflow and
+ * activity IDs.
+ *
+ * <pre><code>
+ * public class FileProcessingActivitiesImpl implements FileProcessingActivities {
+ *
+ *      public String download(String bucketName, String remoteName, String localName) {
+ *          byte[] taskToken = Activity.getTaskToken(); // Used to correlate reply
+ *          asyncDownloadFileFromS3(taskToken, bucketName, remoteName, localDirectory + localName);
+ *          Activity.doNotCompleteOnReturn();
+ *          return "ignored"; // Return value is ignored when doNotCompleteOnReturn was called.
+ *      }
+ *      ...
+ * }
+ * </code></pre>
+ *
+ * When the download is complete, the download service potentially calls back from a different
+ * process:
+ *
+ * <pre><code>
+ *     public <R> void completeActivity(byte[] taskToken, R result) {
+ *         completionClient.complete(taskToken, result);
+ *     }
+ *
+ *     public void failActivity(byte[] taskToken, Exception failure) {
+ *         completionClient.completeExceptionally(taskToken, failure);
+ *     }
+ * </code></pre>
+ *
+ * <h3>Activity Heartbeating</h3>
+ *
+ * <p>Some activities are long running. To react to their crashes quickly, use a heartbeat
+ * mechanism. Use the {@link Activity#heartbeat(Object)} function to let the Cadence service know
+ * that the activity is still alive. You can piggyback `details` on an activity heartbeat. If an
+ * activity times out, the last value of `details` is included in the ActivityTimeoutException
+ * delivered to a workflow. Then the workflow can pass the details to the next activity invocation.
+ * This acts as a periodic checkpointing mechanism of an activity's progress.
+ *
+ * <pre><code>
+ * public class FileProcessingActivitiesImpl implements FileProcessingActivities {
+ *
+ *      {@literal @}Override
+ *      public String download(String bucketName, String remoteName, String localName) {
+ *         InputStream inputStream = openInputStream(file);
+ *         try {
+ *             byte[] bytes = new byte[MAX_BUFFER_SIZE];
+ *             while ((read = inputStream.read(bytes)) != -1) {
+ *                 totalRead += read;
+ *                 f.write(bytes, 0, read);
+ *                 // Let the service know about the download progress.
+ *                 Activity.heartbeat(totalRead);
+ *             }
+ *         }finally{
+ *             inputStream.close();
+ *         }
+ *      }
+ *      ...
+ * }
+ * </code></pre>
+ *
+ * @see com.uber.cadence.worker.Worker
+ * @see com.uber.cadence.workflow.Workflow
+ * @see com.uber.cadence.client.WorkflowClient
  */
 public final class Activity {
 

src/main/java/com/uber/cadence/activity/ActivityOptions.java

@@ -19,6 +19,7 @@
 
 import static com.uber.cadence.internal.common.OptionsUtils.roundUpToSeconds;
 
+import com.uber.cadence.common.MethodRetry;
 import com.uber.cadence.common.RetryOptions;
 import java.time.Duration;
 

src/main/java/com/uber/cadence/activity/ActivityTask.java

@@ -17,27 +17,43 @@
 
 package com.uber.cadence.activity;
 
-import com.uber.cadence.ActivityType;
 import com.uber.cadence.WorkflowExecution;
+import java.time.Duration;
 
+/**
+ * The information about the activity task that the current activity is handling. Use {@link
+ * Activity#getTask()} to access.
+ */
 public interface ActivityTask {
-  byte[] getTaskToken();
 
-  byte[] getInput();
+  /**
+   * A correlation token that can be used to complete the activity asynchronously through {@link
+   * com.uber.cadence.client.ActivityCompletionClient#complete(byte[], Object)}.
+   */
+  byte[] getTaskToken();
 
+  /** ID and RunID of the workflow that scheduled the activity. */
   WorkflowExecution getWorkflowExecution();
 
+  /**
+   * ID of the activity. This ID can be used to complete the activity asynchronously through {@link
+   * com.uber.cadence.client.ActivityCompletionClient#complete(WorkflowExecution, String, Object)}.
+   */
   String getActivityId();
 
-  ActivityType getActivityType();
+  /** Type of the activity. */
+  String getActivityType();
 
+  /**
+   * Time when the activity was initially scheduled by the workflow.
+   *
+   * @return timestamp in milliseconds
+   */
   long getScheduledTimestamp();
 
-  int getScheduleToCloseTimeoutSeconds();
-
-  void setScheduleToCloseTimeoutSecondsIsSet(boolean value);
+  Duration getScheduleToCloseTimeout();
 
-  int getStartToCloseTimeoutSeconds();
+  Duration getStartToCloseTimeout();
 
-  int getHeartbeatTimeoutSeconds();
+  Duration getHeartbeatTimeout();
 }

src/main/java/com/uber/cadence/client/ActivityCompletionException.java

@@ -31,7 +31,7 @@ public class ActivityCompletionException extends RuntimeException {
 
   protected ActivityCompletionException(ActivityTask task) {
     execution = task.getWorkflowExecution();
-    activityType = task.getActivityType().getName();
+    activityType = task.getActivityType();
     activityId = task.getActivityId();
   }
 
@@ -41,14 +41,14 @@ protected ActivityCompletionException(ActivityTask task, Throwable cause) {
             ? "Execution="
                 + task.getWorkflowExecution()
                 + ", ActivityType="
-                + task.getActivityType().getName()
+                + task.getActivityType()
                 + ", ActivityID="
                 + task.getActivityId()
             : null,
         cause);
     if (task != null) {
       execution = task.getWorkflowExecution();
-      activityType = task.getActivityType().getName();
+      activityType = task.getActivityType();
       activityId = task.getActivityId();
     } else {
       execution = null;