HelloWorldWorkflow Application

Although the basic HelloWorld example is structured like a workflow, it differs from an Amazon SWF workflow in several key respects:

You could implement a distributed asynchronous workflow application from scratch, for example, by having your workflow worker interact with an activities worker directly through web services calls. However, you must then implement all the complicated code required to manage the asynchronous execution of multiple activities, handle the data flow, and so on. The AWS Flow Framework for Java and Amazon SWF take care of all those details, which allows you to focus on implementing the business logic.

HelloWorldWorkflow is a modified version of HelloWorld that runs as an Amazon SWF workflow. The following figure summarizes how the two applications work.

HelloWorld runs as a single process and the starter, workflow worker, and activities worker interact by using conventional method calls. With HelloWorldWorkflow, the starter, workflow worker, and activities worker are distributed components that interact through Amazon SWF by using HTTP requests. Amazon SWF manages the interaction by maintaining lists of workflow and activities tasks, which it dispatches to the respective components. This section describes how the framework works for HelloWorldWorkflow.

HelloWorldWorkflow is implemented by using the AWS Flow Framework for Java API, which handles the sometimes complicated details of interacting with Amazon SWF in the background and simplifies the development process considerably. You can use the same project that you did for HelloWorld, which is already configured for AWS Flow Framework for Java applications. However, to run the application, you must set up an Amazon SWF account, as follows:

To implement the HelloWorldWorkflow, create a copy of the helloWorld.HelloWorld package in your project directory and name it helloWorld.HelloWorldWorkflow. The following sections describe how to modify the original HelloWorld code to use the AWS Flow Framework for Java and run as an Amazon SWF workflow application.

HelloWorldWorkflow Activities Worker

HelloWorld implemented its activities worker as a single class. An AWS Flow Framework for Java activities worker has three basic components:

This section discusses the activity methods; the other two classes are discussed later.

HelloWorldWorkflow defines the activities interface in GreeterActivities, as follows:

import com.amazonaws.services.simpleworkflow.flow.annotations.Activities;
import com.amazonaws.services.simpleworkflow.flow.annotations.ActivityRegistrationOptions;

@ActivityRegistrationOptions(defaultTaskScheduleToStartTimeoutSeconds = 300,
                             defaultTaskStartToCloseTimeoutSeconds = 10)
@Activities(version="1.0")

public interface GreeterActivities {
   public String getName();
   public String getGreeting(String name);
   public void say(String what);
}

This interface wasn't strictly necessary for HelloWorld, but it is for an AWS Flow Framework for Java application. Notice that the interface definition itself hasn't changed. However, you must apply two AWS Flow Framework for Java annotations, @ActivityRegistrationOptions and @Activities, to the interface definition. The annotations provide configuration information and direct the AWS Flow Framework for Java annotation processor to use the interface definition to generate an activities client class, which is discussed later.

@ActivityRegistrationOptions has several named values that are used to configure the activities' behavior. HelloWorldWorkflow specifies two timeouts:

These timeouts ensure that the activity completes its task in a reasonable amount of time. If either timeout is exceeded, the framework generates an error and the workflow worker must decide how to handle the issue. For a discussion of how to handle such errors, see Error Handling.

@Activities has several values, but typically it just specifies the activities' version number, which allows you to keep track of different generations of activity implementations. If you change an activity interface after you have registered it with Amazon SWF, including changing the @ActivityRegistrationOptions values, you must use a new version number.

HelloWorldWorkflow implements the activity methods in GreeterActivitiesImpl, as follows:

public class GreeterActivitiesImpl implements GreeterActivities {
   @Override
   public String getName() {
      return "World";
   }
   @Override
   public String getGreeting(String name) {
      return "Hello " + name;
   }
   @Override
   public void say(String what) {
      System.out.println(what);
   }
}

Notice that the code is identical to the HelloWorld implementation. At its core, an AWS Flow Framework activity is just a method that executes some code and perhaps returns a result. The difference between a standard application and an Amazon SWF workflow application lies in how the workflow executes the activities, where the activities execute, and how the results are returned to the workflow worker.

HelloWorldWorkflow Workflow Worker

An Amazon SWF workflow worker has three basic components.

This section discusses the workflow implementation and activities client; the WorkflowWorker class is discussed later.

HelloWorldWorkflow defines the workflow interface in GreeterWorkflow, as follows:

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

This interface also isn't strictly necessary for HelloWorld but is essential for an AWS Flow Framework for Java application. You must apply two AWS Flow Framework for Java annotations, @Workflow and @WorkflowRegistrationOptions, to the workflow interface definition. The annotations provide configuration information and also direct the AWS Flow Framework for Java annotation processor to generate a workflow client class based on the interface, as discussed later.

@Workflow has one optional parameter, dataConverter, which is often used with its default value, NullDataConverter, which indicates that JsonDataConverter should be used.

@WorkflowRegistrationOptions also has a number of optional parameters that can be used to configure the workflow worker. Here, we set defaultExecutionStartToCloseTimeoutSeconds—which specifies how long the workflow can run—to 3600 seconds (1 hour).

The GreeterWorkflow interface definition differs from HelloWorld in one important way, the @Execute annotation. Workflow interfaces specify the methods that can be called by applications such as the workflow starter and are limited to a handful of methods, each with a particular role. The framework doesn't specify a name or parameter list for workflow interface methods; you use a name and parameter list that is suitable for your workflow and apply an AWS Flow Framework for Java annotation to identify the method's role.

@Execute has two purposes:

For information about the other methods that can be included in a workflow interface, see Workflow and Activity Contracts.

HelloWorldWorkflow implements the workflow in GreeterWorkflowImpl, as follows:

import com.amazonaws.services.simpleworkflow.flow.core.Promise;

public class GreeterWorkflowImpl implements GreeterWorkflow {
   private GreeterActivitiesClient operations = new GreeterActivitiesClientImpl();

   public void greet() {
     Promise<String> name = operations.getName();
     Promise<String> greeting = operations.getGreeting(name);
     operations.say(greeting);
   }
}

The code is similar to HelloWorld, but with two important differences.

HelloWorld is a standard Java application that runs locally as a single process, so GreeterWorkflowImpl can implement the workflow topology by simply creating an instance of GreeterActivitiesImpl, calling the methods in order, and passing the return values from one activity to the next. With an Amazon SWF workflow, an activity's task is still performed by an activity method from GreeterActivitiesImpl. However, the method doesn't necessarily run in the same process as the workflow—it might not even run on the same system—and the workflow needs to execute the activity asynchronously. These requirements raise the following issues:

You can implement a variety of workflow topologies through the application's control flow by using familiar Java flow control combined with the activities client and the Promise<T>.

Activities Client

GreeterActivitiesClientImpl is basically a proxy for GreeterActivitiesImpl that allows a workflow implementation to execute the GreeterActivitiesImpl methods asynchronously.

The GreeterActivitiesClient and GreeterActivitiesClientImpl classes are generated automatically for you using the information provided in the annotations applied to your GreeterActivities class. You don't need to implement these yourself.

A workflow worker executes an activity by calling the corresponding client method. The method is asynchronous and immediately returns a Promise<T> object, where T is the activity's return type. The returned Promise<T> object is basically a placeholder for the value that the activity method will eventually return.

Promise<T> Type

The primary purpose of Promise<T> objects is to manage data flow between asynchronous components and control when they execute. It relieves your application of the need to explicitly manage synchronization or depend on mechanisms such as timers to ensure that asynchronous components don't execute prematurely. When you call an activities client method, it immediately returns but the framework defers executing the corresponding activity method until any input Promise<T> objects are ready and represent valid data.

From GreeterWorkflowImpl perspective, all three activities client methods return immediately. From the GreeterActivitiesImpl perspective, the framework doesn't call getGreeting until name completes, and doesn't call say until getGreeting completes.

By using Promise<T> to pass data from one activity to the next, HelloWorldWorkflow not only ensures that activity methods don't attempt to use invalid data, it also controls when the activities execute and implicitly defines the workflow topology. Passing each activity's Promise<T> return value to the next activity requires the activities to execute in sequence, defining the linear topology discussed earlier. With AWS Flow Framework for Java, you don't need to use any special modeling code to define even complex topologies, just standard Java flow control and Promise<T>. For an example of how to implement a simple parallel topology, see HelloWorldWorkflowParallel Activities Worker.

Promise<T> allows a workflow implementation to use activities client methods and their return values much like synchronous methods. However, you must be careful about accessing a Promise<T> object's value. Unlike the Java Future<T> type, the framework handles synchronization for Promise<T>, not the application. If you call Promise<T>.get and the object isn't ready, get throws an exception. Notice that HelloWorldWorkflow never accesses a Promise<T> object directly; it simply passes the objects from one activity to the next. When an object becomes ready, the framework extracts the value and passes it to the activity method as a standard type.

Promise<T> objects should be accessed only by asynchronous code, where the framework guarantees that the object is ready and represents a valid value. HelloWorldWorkflow deals with this issue by passing Promise<T> objects only to activities client methods. You can access a Promise<T> object's value in your workflow implementation by passing the object to an asynchronous workflow method, which behaves much like an activity. For an example, see HelloWorldWorkflowAsync Application.

HelloWorldWorkflow Workflow and Activities Implementation

The workflow and activities implementations have associated worker classes, ActivityWorker and WorkflowWorker. They handle communication between Amazon SWF and the activities and workflow implementations by polling the appropriate Amazon SWF task list for tasks, executing the appropriate method for each task, and managing the data flow. For details, see AWS Flow Framework Basic Concepts: Application Structure

To associate the activity and workflow implementations with the corresponding worker objects, you implement one or more worker applications which:

If you want to run the workflow and activities as separate processes, you must implement separate workflow and activities worker hosts. For an example, see HelloWorldWorkflowDistributed Application. For simplicity, HelloWorldWorkflow implements a single worker host that runs activities and workflow workers in the same process, as follows:

import com.amazonaws.ClientConfiguration;
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflow;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflowClient;
import com.amazonaws.services.simpleworkflow.flow.ActivityWorker;
import com.amazonaws.services.simpleworkflow.flow.WorkflowWorker;

public class GreeterWorker  {
   public static void main(String[] args) throws Exception {
     ClientConfiguration config = new ClientConfiguration().withSocketTimeout(70*1000);

     String swfAccessId = System.getenv("AWS_ACCESS_KEY_ID");
     String swfSecretKey = System.getenv("AWS_SECRET_KEY");
     AWSCredentials awsCredentials = new BasicAWSCredentials(swfAccessId, swfSecretKey);

     AmazonSimpleWorkflow service = new AmazonSimpleWorkflowClient(awsCredentials, config);
     service.setEndpoint("https://swf.us-east-1.amazonaws.com");

     String domain = "helloWorldWalkthrough";
     String taskListToPoll = "HelloWorldList";

     ActivityWorker aw = new ActivityWorker(service, domain, taskListToPoll);
     aw.addActivitiesImplementation(new GreeterActivitiesImpl());
     aw.start();

     WorkflowWorker wfw = new WorkflowWorker(service, domain, taskListToPoll);
     wfw.addWorkflowImplementationType(GreeterWorkflowImpl.class);
     wfw.start();
   }
}

GreeterWorker has no HelloWorld counterpart, so you must add a Java class named GreeterWorker to the project and copy the example code to that file.

The first step is to create and configure an AmazonSimpleWorkflowClient object, which invokes the underlying Amazon SWF service methods. To do so, GreeterWorker:

For convenience, GreeterWorker defines two string constants.

GreeterWorker uses the string constants and the AmazonSimpleWorkflowClient object to create worker objects, which manage the interaction between the activities and worker implementations and Amazon SWF. In particular, the worker objects handle the task of polling the appropriate task list for tasks.

GreeterWorker creates an ActivityWorker object and configures it to handle GreeterActivitiesImpl by adding a new class instance. GreeterWorker then calls the ActivityWorker object's start method, which directs the object to start polling the specified activities task list.

GreeterWorker creates a WorkflowWorker object and configures it to handle GreeterWorkflowImpl by adding the class file name, GreeterWorkflowImpl.class. It then calls the WorkflowWorker object's start method, which directs the object to start polling the specified workflow task list.

You can run GreeterWorker successfully at this point. It registers the workflow and activities with Amazon SWF and starts the worker objects polling their respective task lists. To verify this, run GreeterWorker and go to the Amazon SWF console and select helloWorldWalkthrough from the list of domains. If you choose Workflow Types in the Navigation pane, you should see GreeterWorkflow.greet:

If you choose Activity Types, the GreeterActivities methods are displayed:

However, if you choose Workflow Executions, you will not see any active executions. Although the workflow and activities workers are polling for tasks, we have not yet started a workflow execution.

HelloWorldWorkflow Starter

The final piece of the puzzle is to implement a workflow starter, which is an application that starts the workflow execution. The execution state is stored by Amazon SWF, so that you can view its history and execution status. HelloWorldWorkflow implements a workflow starter by modifying the GreeterMain class, as follows:

import com.amazonaws.ClientConfiguration;
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflow;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflowClient;

public class GreeterMain {

   public static void main(String[] args) throws Exception {
     ClientConfiguration config = new ClientConfiguration().withSocketTimeout(70*1000);

     String swfAccessId = System.getenv("AWS_ACCESS_KEY_ID");
     String swfSecretKey = System.getenv("AWS_SECRET_KEY");
     AWSCredentials awsCredentials = new BasicAWSCredentials(swfAccessId, swfSecretKey);

     AmazonSimpleWorkflow service = new AmazonSimpleWorkflowClient(awsCredentials, config);
     service.setEndpoint("https://swf.us-east-1.amazonaws.com");

     String domain = "helloWorldWalkthrough";

     GreeterWorkflowClientExternalFactory factory = new GreeterWorkflowClientExternalFactoryImpl(service, domain);
     GreeterWorkflowClientExternal greeter = factory.getClient("someID");
     greeter.greet();
   }
}

GreeterMain creates an AmazonSimpleWorkflowClient object by using the same code as GreeterWorker. It then creates a GreeterWorkflowClientExternal object, which acts as a proxy for the workflow in much the same way that the activities client created in GreeterWorkflowClientImpl acts as a proxy for the activity methods. Rather than create a workflow client object by using new, you must:

The client returned from the factory will only create workflows that are named with the string passed into the getClient method, (the client returned from the factory already has state in Amazon SWF). To run a workflow with a different id, you need to go back to the factory and create a new client with the different id specified.

The workflow client exposes a greet method that GreeterMain calls to begin the workflow, as greet() was the method specified with the @Execute annotation.

Shut down GreeterWorker for the moment if it is still running, and run GreeterMain. You should now see someID on the Amazon SWF console's list of active workflow executions:.

If you choose someID and choose the Events tab, the events are displayed:

The Events tab shows only two events:

The reason that the workflow is blocked at the first decision task is that the workflow is distributed across two applications, GreeterMain and GreeterWorker. GreeterMain started the workflow execution, but GreeterWorker isn't running, so the workers aren't polling the lists and executing tasks. You can run either application independently, but you need both for workflow execution to proceed beyond the first decision task. If you now run GreeterWorker, the workflow and activity workers will start polling and the various tasks will be completed rapidly. If you now check the Events tab, the first batch of events is displayed.

You can choose individual events to get more information. By the time you've finished looking, the workflow should have printed "Hello World!" to your console.

After the workflow completes, it no longer appears on the list of active executions. However, if you want to review it, choose the Closed execution status button and then choose List Executions. This displays all the completed workflow instances in the specified domain (helloWorldWalkthrough) that have not exceeded their retention time, which you specified when you created the domain.

Notice that each workflow instance has a unique Run ID value. You can use the same Execution ID for different workflow instances, but only for one active execution at a time.