The AWS SDK for Java provides both synchronous and asynchronous APIs for its clients. Using the synchronous APIs in an asynchronous context, such as a Spray or Akka HTTP route, is problematic. Unfortunately, using the asynchronous APIs is problematic since they use Java futures rather than Scala futures. All of the non-streaming aws2scala APIs are fully asynchronous and return Scala futures, meaning you can compose them and use them with for comprehensions.

The following section contains an example of using a synchronous AWS API asynchronously.

The AWS APIs make extensive use of request and result objects, this is even the case when they are only wrapping just one argument/result object.^[1] aws2scala generally provides methods that take the essential arguments for a request and return the object of interest in the result.

For example, you can compare how creating a role asynchronously differs between using the AWS IAM client and using the aws2scala IAM client.

1. Execute the code asynchronously (we are using the synchronous AWS client)

2. Create an AWS request object

3. Execute the request withing a blocking context, getting the result object

4. Extract the mutable AWS Role bean from the result

5. Build an immutable aws2scala Role instance from the AWS result

1. This method automatically builds the request object and unpacks the result object, returning an immutable Role value

The AWS APIs make extensive use of JavaBeans-style classes. These are mutable objects that use Java-style getters and setters. In cases where one of these properties may be optional, it is a null value. Additionally, all collections are mutable Java collections.

aws2scala opts to take a more idiomatic Scala approach, it:

• Uses immutable Seq and Map objects for all arguments and return values,

• Represents compound data structures using case classes, ensuring immutability and allowing for pattern matching, and

• Uses an Option whenever a value is optional.

Many AWS APIs that perform listings will return paged results. Unfortunately, these paging APIs suffer from a couple of drawbacks:

1. Preparing a new request usually requires getting data from the previous result. This means that is difficult to process pages fully asynchronously.

2. They are inconsistent. Some use Result.getNextToken and Request.getNextToken, others use Result.getMarker and Request.setMarker, and still others use Result.getNextMarker and Request.setMarker.

You can compare how to manually perform the work using the AWS client versus using aws2scala. Note that in both versions, the future will not complete until all pages have been retrieved from AWS. If this is undesirable, i.e. you only want to request new pages as needed, use a streaming client.

1. Create the new request

2. Create an empty result

3. Create builder to accumulate results

4. Set the next pages marker if it is in the result

5. Get results in a blocking context

6. Convert the Java collection of JavaBeans to a (mutable) Scala collection of case class instances

7. Add to the accumulated result

8. Repeat until there are no further pages

9. Get the final (immutable) Scala collection of immutable Role instances

1. Can it get any easier than this?

In addition to the asynchronous APIs, all aws2scala functionality is available through streaming APIs that are built using Akka streams. For example, the following listing constructs and runs a flow that:

1. Gets the current IAM user,

2. Creates a role for that user’s account,

3. Attaches a policy to the new role, and

4. Emits the role that was created.

While the same result can be achieved using the asynchronous APIs and future composition, creating reusable graphs can make code easier to understand. Additionally, the various listing flows that process paged results will emit items as soon as they are retrieved. This allows for the construction of graphs that can process items in a listing as they are available without having to wait for the listing to complete.

1. Start with a single GetUserRequest to get the current user

2. Send it through the IAM userGetter flow, which emits a User instance

3. Now, transform the the user into a CreateRoleRequest

4. Send it through the IAM roleCreator flow, which emits a Role instance

5. Create a subflow that will attach the AmazonS3ReadOnlyAccess policy to the role.

6. Have the policy emit the role that was passed in (rolePolicyAttacher emits a role ARN)

7. Runs the entire flow, resulting in a future with the created role

You will need to add the following to your build.sbt:

1. Add the JCenter resolver to get the aws2scala dependency,

2. The aws2scala dependency itself, and

3. Any AWS SDK dependencies you may need.^[2]