Setting up the AWS Flow Framework for Java - AWS Flow Framework for Java
Installing for MavenInstalling for Eclipse

Setting up the AWS Flow Framework for Java

The AWS Flow Framework for Java is included with the AWS SDK for Java. If you have not already set up the AWS SDK for Java, visit Getting Started in the AWS SDK for Java Developer Guide for information about installing and configuring the SDK itself.

This topic provides information about additional steps required to use the AWS Flow Framework for Java. Steps are provided for Eclipse and Maven.

Installing for Maven

Amazon provides Amazon SWF build tools in the Maven Central Repository to aid setup of AWS Flow Framework for Java in your Maven projects.

To set up the flow framework for Maven, add the following dependency to your project's pom.xml file:

<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>1.2.17</version>
</dependency>
<dependency>
  <groupId>com.amazonaws</groupId>
  <artifactId>aws-swf-build-tools</artifactId>
  <version>1.0</version>
</dependency>

The Amazon SWF build tools are open source—to view or download the code or to build the tools yourself, visit the repository at https://github.com/aws/aws-swf-build-tools.

Installing for Eclipse

If you use the Eclipse IDE, install the AWS Flow Framework for Java using the AWS Toolkit for Eclipse.

Installing the AWS Toolkit for Eclipse

Installing the Toolkit for Eclipse is the simplest way to get started with the AWS Flow Framework for Java. To install the Toolkit for Eclipse, see Setting Up the AWS Toolkit for Eclipse in the AWS Toolkit for Eclipse Getting Started Guide.

Important

Be sure to include both the AWS SDK for Java and AWS Simple Workflow Tools when selecting which packages to install in Eclipse's Available Software dialog box:

Install the AWS Toolkit for Eclipse including the SDK for Java and Amazon SWF Tools

If you installed all of the available packages (by choosing the AWS Toolkit for Eclipse top-level node, or choosing Select All), both of these packages were automatically selected and installed for you.

Creating an AWS Flow Framework for Java Project

Creating a properly configured AWS Flow Framework for Java project in Eclipse involves a number of steps:

  1. Create an AWS Java project.

  2. Enable annotation processing for your project.

  3. Enable and configure AspectJ.

Each of these steps will now be described in detail.

To create an AWS Java project

  1. Launch Eclipse.

  2. To select the Java perspective, choose Window, Open Perspective, Java.

  3. Choose File, New, AWS Java Project.

    Creating a new AWS Java project

  4. Use the AWS Java project wizard to create a new project.

    Note

    The first time you create an AWS Java project with Eclipse, the SDK for Java will be automatically downloaded and installed when the project wizard starts.

After creating your AWS Java project, enable annotation processing for the project. The AWS Flow Framework for Java includes an annotation processor that generates several key classes based on annotated source code.

To enable annotation processing

  1. In Project Explorer, right-click your project and select Properties.

  2. In the Properties dialog box, navigate to Java Compiler > Annotation Processing.

  3. Check Enable project specific settings (which should also Enable annotation processing, but if it doesn't make sure that this option is also checked). Then choose OK.

    Enabling annotation processing in Eclipse
    Note

    You will need to rebuild your project after enabling annotation processing.

Enabling and Configuring AspectJ

Next, you should enable and configure AspectJ. Certain AWS Flow Framework for Java annotations such as @Asynchronous require AspectJ. You don't need to use AspectJ directly, but you must enable it with either load-time weaving or compile-time weaving.

Note

The recommended approach is to use load-time weaving.

Prerequisites

Before configuring AspectJ, you need the AspectJ version that matches your Java version:

  • If you are using Java 8, download the latest AspectJ 1.8.X release.

  • If you are using Java 7, download the latest AspectJ 1.7.X release.

  • If you are using Java 6, download the latest AspectJ 1.6.X release.

You can download either of these versions of AspectJ from the Eclipse download page.

After you have finished downloading AspectJ, execute the downloaded .jar file to install AspectJ. The AspectJ installation will ask you where you would like to install the binaries, and on the final screen, will provide recommended steps for completing the installation. Remember the location of the aspectjweaver.jar file; you'll need it to configure AspectJ in Eclipse.

Configuring AspectJ Load-Time Weaving

To configure AspectJ load-time weaving for your AWS Flow Framework for Java project, first designate the AspectJ JAR file as a Java agent, and then configure it by adding an aop.xml file to your project.

To add AspectJ as a Java agent

  1. To open the Preferences dialog box, choose Window, Preferences.

  2. Navigate to Java > Installed JREs.

  3. Select the appropriate JRE and choose Edit.

  4. In the Default VM arguments box, enter the path to the installed AspectJ binary. This will be a path such as /home/user/aspectj1.7/lib/aspectjweaver.jar, depending on your operating system and on the version of AspectJ you downloaded.

    On Linux, macOS, or Unix use:

    -javaagent:/your_path/aspectj/lib/aspectjweaver.jar

    On Windows, use a standard Windows-style path instead:

    -javaagent:C:\your_path\aspectj\lib\aspectjweaver.jar

    Enabling AspectJ load-time weaving in Eclipse

To configure AspectJ for AWS Flow Framework for Java, add an aop.xml file to the project.

To add an aop.xml file

  1. In your project's src directory, add a directory named META-INF.

  2. Add a file named aop.xml to META-INF with the following contents.

    <aspectj>
   <aspects>
      <aspect name="com.amazonaws.services.simpleworkflow.flow.aspectj.AsynchronousAspect"/>
      <aspect name="com.amazonaws.services.simpleworkflow.flow.aspectj.ExponentialRetryAspect"/>
   </aspects>
   <weaver options="-verbose">
     <include within="MySimpleWorkflow.*"/>
   </weaver>
</aspectj>

    The value of <include within=""/> depends on how you name your project's packages. The above example assumes that the project's packages followed the pattern MySimpleWorkflow.*. Use a value appropriate for your own project's packages.

AspectJ Compile-Time Weaving

To enable and configure AspectJ compile-time weaving, you must first install the AspectJ developer tools for Eclipse, which are available from http://www.eclipse.org/aspectj/downloads.php.

To install the AspectJ Developer Tools in Eclipse

  1. On the Help menu, choose Install New Software.

  2. In the Available Software dialog box, enter http://download.eclipse.org/tools/ajdt/version/dev/update, where version represents your Eclipse version number. For example, if you are using Eclipse 4.6, you would enter: http://download.eclipse.org/tools/ajdt/46/dev/update

    Important

    Be sure that the AspectJ version matches your Eclipse version, or installation of AspectJ will fail.

  3. Choose Add to add the location. Once the location is added, the AspectJ developer tools will be listed.

  4. Choose Select All to select all of the AspectJ developer tools, then choose Next to install them.

    Note

    You will need to restart Eclipse to complete the installation.

You must then configure your project.

To configure your project for AspectJ compile-time weaving

  1. In Project Explorer, right-click your project and select Configure > Convert to AspectJ Project.

    The AspectJ Runtime Library will be added to your project.

  2. Right-click your project again and then choose Properties.

  3. Choose AspectJ Build and then choose the Aspect Path tab.

  4. Choose Add External JARs and add the AWS SDK for Java JAR file to your project's Aspect Path.

    Note

    The AWS Toolkit for Eclipse installs the AWS SDK for Java JAR file in your workspace, in the .metadata/.plugins/com.amazonaws.eclipse.core/aws-java-sdk/AWS Version/lib directory, where you replace AWS Version with the installed AWS SDK version number. Otherwise, you can use the JAR file that is included with the regular AWS SDK installation, which is in the lib directory.

Working around issues with AspectJ and Eclipse

The AspectJ Eclipse plug-in has an issue that can prevent generated code from being compiled. The fastest way to force generated code to be recognized after you recompile it is to change the order of the source directory that contains the generated code on the Order and Export tab of the Java Build Path settings page (for example, you can set the default to apt/java).