In Java, Activities are methods of a plain Java interface that are annotated with
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
The default implementation uses a JSON serializer, but an alternative implementation can be configured through
Example of an interface that defines four Activities for interacting with S3:
We recommend using a single value type argument for Activity methods. In this way, adding new arguments to the value type, as fields, is a backwards-compatible change.
An Activity is the 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.
getExecutionContext() method returns an
ActivityExecutionContext which provides static getters to access information about the Workflow that invoked it.
Note that the Activity context information is stored in a thread-local variable.
Therefore, calls to
getExecutionContext() succeed only within the thread that invoked the Activity function.
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
ActivityExecutionContext.doNotCompleteOnReturn() from the original Activity thread.
Then later, when replies come, complete the Activity using
To correlate Activity invocation with completion use either
TaskToken or Workflow and Activity IDs.
When the download is complete, the download service potentially calls back from a different process:
Some Activities are long running.
To react to a crash quickly, use the heartbeat mechanism.
Activity.getExecutionContext().heartbeat() lets 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 checkpoint mechanism for the progress of an Activity.
If there is a need to return a checked exception from an Activity, do not add the exception to a method signature but instead re-throw it using the
The library code will unwrap it automatically when propagating the 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 a design is that returning the originally thrown exception from a remote call (which child Workflow and Activity invocations are) does not allow adding context information regarding a failure, such as Activity and child Workflow Id.
So a stub always throws a subclass of
ActivityFailure from calls to an Activity and a subclass of
ChildWorkflowFailure 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
Error, it never returns.
But return type is not empty to be able to use it as:
wrap returned void it wouldn't be possible to write
throw Activity.wrap and compiler would complain about missing return.
To make the Activity visible to the Worker process hosting it, the Activity must be registered with the Worker.
This call creates an in-memory mapping inside the Worker process between the Activity object name and the actual implementation. If a Worker receives a request to start an Activity execution for an Activity type it does not know, it will fail that request.
To register multiple Activity objects with the Worker, each Activity object implementation name must be unique, and you must provide all Activity function names in the registration call like so: