io.temporal.activity

Class Activity

java.lang.Object

io.temporal.activity.Activity

public final class Activity
extends java.lang.Object

An activity is the implementation of a particular task in the business logic.

Activity Interface

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 DataConverter implementation. The default implementation uses JSON serializer, but an alternative implementation can be easily configured.

Example of an interface that defines four activities:

 public interface FileProcessingActivities {

     void upload(String bucketName, String localName, String targetName);

     String download(String bucketName, String remoteName);

      @ActivityMethod(scheduleToCloseTimeoutSeconds = 2)
     String processFile(String localName);

     void deleteLocalFile(String fileName);
 }

 

An optional @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.

Activity Implementation

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 thread safe.

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 Temporal 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.

 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();
     }
 }
 

Accessing Activity Info

The 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.

 public class FileProcessingActivitiesImpl implements FileProcessingActivities {

       @Override
      public String download(String bucketName, String remoteName, String localName) {
         log.info("namespace=" +  Activity.getNamespace());
         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);
      }
      ...
  }
 

Asynchronous Activity Completion

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 Temporal activity.

To indicate that an activity should not be completed upon its method return, call doNotCompleteOnReturn() from the original activity thread. Then later, when replies come, complete the activity using ActivityCompletionClient. To correlate activity invocation with completion use either TaskToken or workflow and activity IDs.

 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.
      }
      ...
 }
 

When the download is complete, the download service potentially calls back from a different process:

     public  void completeActivity(byte[] taskToken, R result) {
         completionClient.complete(taskToken, result);
     }

     public void failActivity(byte[] taskToken, Exception failure) {
         completionClient.completeExceptionally(taskToken, failure);
     }
 

Activity Heartbeating

Some activities are long running. To react to their crashes quickly, use a heartbeat mechanism. Use the heartbeat(Object) function to let the Temporal 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.

 public class FileProcessingActivitiesImpl implements FileProcessingActivities {

       @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();
         }
      }
      ...
 }
 

See Also:

Worker, Workflow, WorkflowClient

Method Summary

Modifier and Type	Method and Description
static void	doNotCompleteOnReturn() If this method is called during an activity execution then activity is not going to complete when its method returns.
static <V> java.util.Optional<V>	getHeartbeatDetails(java.lang.Class<V> detailsClass) Extracts heartbeat details from the last failed attempt.
static <V> java.util.Optional<V>	getHeartbeatDetails(java.lang.Class<V> detailsClass, java.lang.reflect.Type detailsType) Similar to getHeartbeatDetails(Class).
static java.lang.String	getNamespace()
static WorkflowServiceStubs	getService()
static ActivityTask	getTask()
static byte[]	getTaskToken()
static io.temporal.proto.execution.WorkflowExecution	getWorkflowExecution()
static <V> void	heartbeat(V details) Use to notify Temporal service that activity execution is alive.
static java.lang.RuntimeException	wrap(java.lang.Exception e) If there is a need to return a checked exception from an activity do not add the exception to a method signature but rethrow it using this method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

doNotCompleteOnReturn

public static void doNotCompleteOnReturn()

If this method is called during an activity execution then activity is not going to complete when its method returns. It is expected to be completed asynchronously using ActivityCompletionClient.

getTaskToken

public static byte[] getTaskToken()

Returns:

task token that is required to report task completion when manual activity completion is used.

getWorkflowExecution

public static io.temporal.proto.execution.WorkflowExecution getWorkflowExecution()

Returns:

workfow execution that requested the activity execution

getTask

public static ActivityTask getTask()

Returns:

task that caused activity execution

heartbeat

public static <V> void heartbeat(V details)
                          throws ActivityCompletionException

Use to notify Temporal service that activity execution is alive.

Parameters:

details - In case of activity timeout can be accessed through ActivityTimeoutException.getDetails(Class) method.

Throws:

ActivityCompletionException - Indicates that activity execution is expected to be interrupted. The reason for interruption is indicated by a type of subclass of the exception.

getHeartbeatDetails

public static <V> java.util.Optional<V> getHeartbeatDetails(java.lang.Class<V> detailsClass)

Extracts heartbeat details from the last failed attempt. This is used in combination with retry options. An activity could be scheduled with an optional RetryOptions on ActivityOptions. If an activity failed then the server would attempt to dispatch another activity task to retry according to the retry options. If there was heartbeat details reported by the activity from the failed attempt, the details would be delivered along with the activity task for the retry attempt. The activity could extract the details by getHeartbeatDetails(Class)() and resume from the progress.

Parameters:

detailsClass - type of the heartbeat details

getHeartbeatDetails

public static <V> java.util.Optional<V> getHeartbeatDetails(java.lang.Class<V> detailsClass,
                                                            java.lang.reflect.Type detailsType)

Similar to getHeartbeatDetails(Class). Use when details is of a generic type.

Parameters:

detailsClass - type of the heartbeat details

detailsType - type including generic information of the heartbeat details.

getService

public static WorkflowServiceStubs getService()

Returns:

an instance of the Simple Workflow Java client that is the same used by the invoked activity worker. It can be useful if activity wants to use WorkflowClient for some operations like sending signal to its parent workflow. @TODO getWorkflowClient method to hide the service.

getNamespace

public static java.lang.String getNamespace()

wrap

public static java.lang.RuntimeException wrap(java.lang.Exception e)

If there is a need to return a checked exception from an activity do not add the exception to a method signature but rethrow it using this method. The library code will unwrap it automatically when propagating exception to the caller. There is no need to wrap unchecked exceptions, but it is safe to call this method on them.

The reason for such design is that returning originally thrown exception from a remote call (which child workflow and activity invocations are ) would not allow adding context information about a failure, like activity and child workflow id. So stubs always throw a subclass of ActivityException from calls to an activity and subclass of ChildWorkflowException from calls to a child workflow. The original exception is attached as a cause to these wrapper exceptions. So as exceptions are always wrapped adding checked ones to method signature causes more pain than benefit.

Throws original exception if e is RuntimeException or Error. Never returns. But return type is not empty to be able to use it as:

 try {
     return someCall();
 } catch (Exception e) {
     throw CheckedExceptionWrapper.throwWrapped(e);
 }
 

If throwWrapped returned void it wouldn't be possible to write throw CheckedExceptionWrapper.throwWrapped and compiler would complain about missing return.

Returns:

never returns as always throws.