# AWS Flow Framework for Java Reference Reference **Topics** + [ # AWS Flow Framework for Java Annotations ](annotations.md) + [ # AWS Flow Framework for Java Exceptions ](errorhandling.exceptions.md) + [ # AWS Flow Framework for Java Packages ](awsflow.packages.md) # AWS Flow Framework for Java Annotations Annotations **Topics** + [ ## @Activities ](#annotations-activities) + [ ## @Activity ](#annotations-activity) + [ ## @ActivityRegistrationOptions ](#annotations-activityregistration) + [ ## @Asynchronous ](#annotations-asynchronous) + [ ## @Execute ](#annotations-execute) + [ ## @ExponentialRetry ](#annotations-exponentialretry) + [ ## @GetState ](#annotations-getstate) + [ ## @ManualActivityCompletion ](#annotations-manualactivitycompletion) + [ ## @Signal ](#annotations-signal) + [ ## @SkipRegistration ](#annotations-skipregistration) + [ ## @Wait and @NoWait ](#annotations-waitnowait) + [ ## @Workflow ](#annotations-workflow) + [ ## @WorkflowRegistrationOptions ](#annotations-workflowregistrationoptions) ## @Activities This annotation can be used on an interface to declare a set of activity types. Each method in an interface annotated with this annotation represents an activity type. An interface can't have both `@Workflow` and `@Activities` annotations- The following parameters can be specified on this annotation: `activityNamePrefix` Specifies the prefix of the name of the activity types declared in the interface. If set to an empty string (which is the default), the name of the interface followed by '.' is used as the prefix. `version` Specifies the default version of the activity types declared in the interface. The default value is `1.0`. `dataConverter` Specifies the type of the `DataConverter` to use for serializing/deserializing data when creating tasks of this activity type and its results. Set to `NullDataConverter` by default, which indicates that the `JsonDataConverter` should be used. ## @Activity This annotation can be used on methods within an interface annotated with `@Activities`. The following parameters can be specified on this annotation: `name` Specifies the name of the activity type. The default is an empty string, which indicates that the default prefix and the activity method name should be used to determine the name of the activity type (which is of the form \$1*prefix*\$1\$1*name*\$1). Note that when you specify a name in an `@Activity` annotation, the framework will not automatically prepend a prefix to it. You are free to use your own naming scheme. `version` Specifies the version of the activity type. This overrides the default version specified in the `@Activities` annotation on the containing interface. The default is an empty string. ## @ActivityRegistrationOptions Specifies the registration options of an activity type. This annotation can be used on an interface annotated with `@Activities` or the methods within. If specified in both places, then the annotation used on the method takes effect. The following parameters can be specified on this annotation: `defaultTasklist` Specifies the default task list to be registered with Amazon SWF for this activity type. This default can be overridden when calling the activity method on the generated client using the `ActivitySchedulingOptions` parameter. Set to `USE_WORKER_TASK_LIST` by default. This is a special value which indicates that the task list used by the worker, which is performing the registration, should be used. `defaultTaskScheduleToStartTimeoutSeconds` Specifies the defaultTaskScheduleToStartTimeout registered with Amazon SWF for this activity type. This is the maximum time a task of this activity type is allowed to wait before it is assigned to a worker. See the *Amazon Simple Workflow Service API Reference* for more details. `defaultTaskHeartbeatTimeoutSeconds` Specifies the `defaultTaskHeartbeatTimeout` registered with Amazon SWF for this activity type. Activity workers must provide heartbeat within this duration; otherwise, the task will be timed out. Set to -1 by default, which is a special value that indicates this timeout should be disabled. See the *Amazon Simple Workflow Service API Reference* for more details. `defaultTaskStartToCloseTimeoutSeconds` Specifies the defaultTaskStartToCloseTimeout registered with Amazon SWF for this activity type. This timeout determines the maximum time a worker can take to process an activity task of this type. See the *Amazon Simple Workflow Service API Reference* for more details. `defaultTaskScheduleToCloseTimeoutSeconds` Specifies the `defaultScheduleToCloseTimeout` registered with Amazon SWF for this activity type. This timeout determines the total duration that the task can stay in open state. Set to -1 by default, which is a special value that indicates this timeout should be disabled. See the *Amazon Simple Workflow Service API Reference* for more details. ## @Asynchronous When used on a method in the workflow coordination logic, indicates that the method should be executed asynchronously. A call to the method will return immediately, but the actual execution will happen asynchronously when all Promise<> parameters passed to the methods become ready. Methods annotated with @Asynchronous must have a return type of Promise<> or void. `daemon` Indicates if the task created for the asynchronous method should be a daemon task. `False` by default. ## @Execute When used on a method in an interface annotated with the `@Workflow` annotation, identifies the entry point of the workflow. **Important** Only one method in the interface can be decorated with `@Execute`. The following parameters can be specified on this annotation: `name` Specifies the name of the workflow type. If not set, the name defaults to \$1*prefix*\$1\$1*name*\$1, where \$1*prefix*\$1 is the name of the workflow interface followed by a '.' and \$1*name*\$1 is the name of the `@Execute`-decorated method in the workflow. `version` Specifies the version of the workflow type. ## @ExponentialRetry When used on an activity or asynchronous method, sets an exponential retry policy if the method throws an unhandled exception. A retry attempt is made after a back-off period, which is calculated by the power of the number of attempts. The following parameters can be specified on this annotation: `intialRetryIntervalSeconds` Specifies the duration to wait before the first retry attempt. This value should not be greater than `maximumRetryIntervalSeconds` and `retryExpirationSeconds`. `maximumRetryIntervalSeconds` Specifies the maximum duration between retry attempts. Once reached, the retry interval is capped to this value. Set to -1 by default, which means unlimited duration. `retryExpirationSeconds` Specifies the duration after which exponential retry will stop. Set to -1 by default, which means there is no expiration. `backoffCoefficient` Specifies the coefficient used to calculate the retry interval. See [Exponential Retry Strategy](features-retry.md#features-retry-exponential). `maximumAttempts` Specifies the number of attempts after which exponential retry will stop. Set to -1 by default, which means there is no limit on the number of retry attempts. `exceptionsToRetry` Specifies the list of exception types that should trigger a retry. Unhandled exception of these types will not propagate further and the method will be retried after the calculated retry interval. By default, the list contains `Throwable`. `excludeExceptions` Specifies the list of exception types that should not trigger a retry. Unhandled exceptions of this type will be allowed to propagate. The list is empty by default. ## @GetState When used on a method in an interface annotated with the `@Workflow` annotation, identifies that the method is used to retrieve the latest workflow execution state. There can be at most one method with this annotation in an interface with the `@Workflow` annotation. Methods with this annotation must not take any parameters and must have a return type other than `void`. ## @ManualActivityCompletion This annotation can be used on an activity method to indicate that the activity task should not be completed when the method returns. The activity task will not be automatically completed and would need to be completed manually directly using the Amazon SWF API. This is useful for use cases where the activity task is delegated to some external system that isn't automated or requires human intervention to be completed. ## @Signal When used on a method in an interface annotated with the `@Workflow` annotation, identifies a signal that can be received by executions of the workflow type declared by the interface. Use of this annotation is required to define a signal method. The following parameters can be specified on this annotation: `name` Specifies the name portion of the signal name. If not set, the name of the method is used. ## @SkipRegistration When used on an interface annotated with the `@Workflow` annotation, indicates that the workflow type should not be registered with Amazon SWF. One of `@WorkflowRegistrationOptions` and `@SkipRegistrationOptions` annotations must be used on an interface annotated with `@Workflow`, but not both. ## @Wait and @NoWait These annotations can be used on a parameter of type `Promise<>` to indicate whether the AWS Flow Framework for Java should wait for it to become ready before executing the method. By default, `Promise<>` parameters passed into `@Asynchronous` methods must become ready before method execution occurs. In certain scenarios, it is necessary to override this default behavior. `Promise<>` parameters passed into `@Asynchronous` methods and annotated with `@NoWait` are not waited for. Collections parameters (or subclasses of) that contain promises, such as `List>`, must be annotated with `@Wait` annotation. By default, the framework doesn't wait for the members of a collection. ## @Workflow This annotation is used on an interface to declare a *workflow* type. An interface decorated with this annotation should contain exactly one method that is decorated with the [@Execute](#annotations-execute) annotation to declare an entry point for your workflow. **Note** An interface can't have both `@Workflow` and `@Activities` annotations declared at once; they are mutually exclusive. The following parameters can be specified on this annotation: `dataConverter` Specifies which `DataConverter` to use when sending requests to, and receiving results from, workflow executions of this workflow type. The default is `NullDataConverter` which, in turn, falls back to `JsonDataConverter` to process all request and response data as JavaScript Object Notation (JSON). ### Example ``` import com.amazonaws.services.simpleworkflow.flow.annotations.Execute; import com.amazonaws.services.simpleworkflow.flow.annotations.Workflow; import com.amazonaws.services.simpleworkflow.flow.annotations.WorkflowRegistrationOptions; @Workflow @WorkflowRegistrationOptions(defaultExecutionStartToCloseTimeoutSeconds = 3600) public interface GreeterWorkflow { @Execute(version = "1.0") public void greet(); } ``` ## @WorkflowRegistrationOptions When used on an interface annotated with `@Workflow`, provides default settings used by Amazon SWF when registering the workflow type. **Note** Either `@WorkflowRegistrationOptions` or `@SkipRegistrationOptions` must be used on an interface annotated with `@Workflow`, but you can't specify both. The following parameters can be specified on this annotation: Description An optional text description of the workflow type. `defaultExecutionStartToCloseTimeoutSeconds` Specifies the `defaultExecutionStartToCloseTimeout` registered with Amazon SWF for the workflow type. This is the total time that a workflow execution of this type can take to complete. For more information about workflow timeouts, see [Amazon SWF Timeout Types](swf-timeout-types.md). `defaultTaskStartToCloseTimeoutSeconds` Specifies the `defaultTaskStartToCloseTimeout` registered with Amazon SWF for the workflow type. This specifies the time a single decision task for a workflow execution of this type can take to complete. If you don't specify `defaultTaskStartToCloseTimeout`, it will default to 30 seconds. For more information about workflow timeouts, see [Amazon SWF Timeout Types](swf-timeout-types.md). `defaultTaskList` The default task list used for decision tasks for executions of this workflow type. The default set here can be overridden by using `StartWorkflowOptions` when starting a workflow execution. If you don't specify `defaultTaskList`, it will be set to `USE_WORKER_TASK_LIST` by default. This indicates that the task list used by the worker that is performing the workflow registration should be used. `defaultChildPolicy` Specifies the policy to use for child workflows if an execution of this type is terminated. The default value is `ABANDON`. The possible values are: + `ABANDON` – Allow the child workflow executions to keep running + `TERMINATE` – Terminate child workflow executions + `REQUEST_CANCEL` – Request cancellation of the child workflow executions # AWS Flow Framework for Java Exceptions Exceptions The following exceptions are used by the AWS Flow Framework for Java. This section provides an overview of the exception. For more details, see the AWS SDK for Java documentation of the individual exceptions. **Topics** + [ ## ActivityFailureException ](#errorhandling.exceptions.ActivityFailureException) + [ ## ActivityTaskException ](#errorhandling.exceptions.ActivityTaskException) + [ ## ActivityTaskFailedException ](#errorhandling.exceptions.ActivityTaskFailedException) + [ ## ActivityTaskTimedOutException ](#errorhandling.exceptions.ActivityTaskTimedOutException) + [ ## ChildWorkflowException ](#errorhandling.exceptions.ChildWorkflowException) + [ ## ChildWorkflowFailedException ](#errorhandling.exceptions.ChildWorkflowFailedException) + [ ## ChildWorkflowTerminatedException ](#errorhandling.exceptions.ChildWorkflowTerminatedException) + [ ## ChildWorkflowTimedOutException ](#errorhandling.exceptions.ChildWorkflowTimedOutException) + [ ## DataConverterException ](#errorhandling.exceptions.DataConverterException) + [ ## DecisionException ](#errorhandling.exceptions.DecisionException) + [ ## ScheduleActivityTaskFailedException ](#errorhandling.exceptions.ScheduleActivityTaskFailedException) + [ ## SignalExternalWorkflowException ](#errorhandling.exceptions.SignalExternalWorkflowException) + [ ## StartChildWorkflowFailedException ](#errorhandling.exceptions.StartChildWorkflowFailedException) + [ ## StartTimerFailedException ](#errorhandling.exceptions.StartTimerFailedException) + [ ## TimerException ](#errorhandling.exceptions.TimerException) + [ ## WorkflowException ](#errorhandling.exceptions.WorkflowException) ## ActivityFailureException This exception is used by the framework internally to communicate activity failure. When an activity fails due to an unhandled exception, it is wrapped in `ActivityFailureException` and reported to Amazon SWF. You need to deal with this exception only if you use the activity worker extensibility points. Your application code will never need to deal with this exception. ## ActivityTaskException This is the base class for activity task failure exceptions: `ScheduleActivityTaskFailedException`, `ActivityTaskFailedException`, `ActivityTaskTimedoutException`. It contains the task Id and activity type of the failed task. You can catch this exception in your workflow implementation to deal with activity failures in a generic way. ## ActivityTaskFailedException Unhandled exceptions in activities are reported back to the workflow implementation by throwing an `ActivityTaskFailedException`. The original exception can be retrieved from the cause property of this exception. The exception also provides other information that is useful for debugging purposes, such as the unique activity identifier in the history. The framework is able to provide the remote exception by serializing the original exception from the activity worker. ## ActivityTaskTimedOutException This exception is thrown if an activity was timed out by Amazon SWF. This could happen if the activity task could not be assigned to the worker within the require time period or could not be completed by the worker in the required time. You can set these timeouts on the activity using the `@ActivityRegistrationOptions` annotation or using the `ActivitySchedulingOptions` parameter when calling the activity method. ## ChildWorkflowException Base class for exceptions used to report failure of child workflow execution. The exception contains the Ids of the child workflow execution as well as its workflow type. You can catch this exception to deal with child workflow execution failures in a generic way. ## ChildWorkflowFailedException Unhandled exceptions in child workflows are reported back to the parent workflow implementation by throwing a `ChildWorkflowFailedException`. The original exception can be retrieved from the `cause` property of this exception. The exception also provides other information that is useful for debugging purposes, such as the unique identifiers of the child execution. ## ChildWorkflowTerminatedException This exception is thrown in parent workflow execution to report the termination of a child workflow execution. You should catch this exception if you want to deal with the termination of the child workflow, for example, to perform cleanup or compensation. ## ChildWorkflowTimedOutException This exception is thrown in parent workflow execution to report that a child workflow execution was timed out and closed by Amazon SWF. You should catch this exception if you want to deal with the forced closure of the child workflow, for example, to perform cleanup or compensation. ## DataConverterException The framework uses the `DataConverter` component to marshal and unmarshal data that is sent over the wire. This exception is thrown if the `DataConverter` fails to marshal or unmarshal data. This could happen for various reasons, for example, due to a mismatch in the `DataConverter` components being used to marshal and unmarshal the data. ## DecisionException This is the base class for exceptions that represent failures to enact a decision by Amazon SWF. You can catch this exception to generically deal with such exceptions. ## ScheduleActivityTaskFailedException This exception is thrown if Amazon SWF fails to schedule an activity task. This could happen due to various reasons—for example, the activity was deprecated, or an Amazon SWF limit on your account has been reached. The `failureCause` property in the exception specifies the exact cause of failure to schedule the activity. ## SignalExternalWorkflowException This exception is thrown if Amazon SWF fails to process a request by the workflow execution to signal another workflow execution. This happens if the target workflow execution could not be found—that is, the workflow execution you specified doesn't exist or is in closed state. ## StartChildWorkflowFailedException This exception is thrown if Amazon SWF fails to start a child workflow execution. This could happen due to various reasons—for example, the type of child workflow specified was deprecated, or a Amazon SWF limit on your account has been reached. The `failureCause` property in the exception specifies the exact cause of failure to start the child workflow execution. ## StartTimerFailedException This exception is thrown if Amazon SWF fails to start a timer requested by the workflow execution. This could happen if the specified timer ID is already in use, or an Amazon SWF limit on your account has been reached. The `failureCause` property in the exception specifies the exact cause of failure. ## TimerException This is the base class for exceptions related to timers. ## WorkflowException This exception is used internally by the framework to report failures in workflow execution. You need to deal with this exception only if you are using a workflow worker extensibility point. # AWS Flow Framework for Java Packages Packages This section provides an overview of the packages included with the AWS Flow Framework for Java. For more information about each package, see the com.amazonaws.services.simpleworkflow.flow in the [AWS SDK for Java API Reference](https://docs.aws.amazon.com/sdk-for-java/latest/reference/). [com.amazonaws.services.simpleworkflow.flow](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/package-summary.html) Contains components that integrate with Amazon SWF. [com.amazonaws.services.simpleworkflow.flow.annotations](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/annotations/package-summary.html) Contains the annotations used by the AWS Flow Framework for Java programming model. [com.amazonaws.services.simpleworkflow.flow.aspectj](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/aspectj/package-summary.html) Contains AWS Flow Framework for Java components required for features such as [@Asynchronous](annotations.md#annotations-asynchronous) and [@ExponentialRetry](annotations.md#annotations-exponentialretry). [com.amazonaws.services.simpleworkflow.flow.common](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/common/package-summary.html) Contains common utilities such as framework-defined constants. [com.amazonaws.services.simpleworkflow.flow.core](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/core/package-summary.html) Contains core features such as `Task` and `Promise`. [com.amazonaws.services.simpleworkflow.flow.generic](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/generic/package-summary.html) Contains core components, such as generic clients, that other features build on. [com.amazonaws.services.simpleworkflow.flow.interceptors](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/interceptors/package-summary.html) Contains implementations of framework provided decorators including `RetryDecorator`. [com.amazonaws.services.simpleworkflow.flow.junit](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/junit/package-summary.html) Contains components that provide Junit integration. [com.amazonaws.services.simpleworkflow.flow.pojo](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/pojo/package-summary.html) Contains classes that implement activity and workflow definitions for the annotation-based programming model. [com.amazonaws.services.simpleworkflow.flow.spring](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/spring/package-summary.html) Contains components that provide Spring integration. [com.amazonaws.services.simpleworkflow.flow.test](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/test/package-summary.html) Contains helper classes, such as `TestWorkflowClock`, for unit testing workflow implementations. [com.amazonaws.services.simpleworkflow.flow.worker](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/worker/package-summary.html) Contains implementations of activity and workflow workers.