Migrating to the AWS SDK for Java

Articles & Tutorials>SDKs>Migrating to the AWS SDK for Java
This article describes the differences between the AWS SDK for Java and previous Java libraries from Amazon Web Services.


Submitted By: Craig@AWS
AWS Products Used: Amazon EC2, Amazon RDS, Amazon S3, Amazon SQS, Amazon SimpleDB
Language(s): Java
Created On: March 21, 2010 5:39 PM GMT
Last Updated: February 24, 2015 8:06 PM GMT

About the AWS SDK for Java

The AWS SDK for Java is a single, downloadable package that includes the AWS Java library, code samples, and documentation. Previously, AWS offered a collection of individual Java libraries for many infrastructure services, but not Amazon S3. Now, you can get started in minutes with a single package that includes the AWS Java library, code samples, and documentation. Additionally, Eclipse Java IDE users can get started with the SDK using the AWS Toolkit for Eclipse.

Learn more about the AWS SDK for Java at http://aws.amazon.com/sdkforjava.

What's New in the AWS SDK for Java Library?

There are a number of differences between the previous Java libraries from AWS and the new AWS SDK for Java. In addition to grouping the libraries into a single package along with documentation and code samples, the AWS SDK for Java makes it easier to use multiple AWS products.

Here are some highlights of new features in the AWS SDK for Java library:

  • Support for Amazon S3 — We now provide an officially-supported Java API for working with Amazon S3.
  • Improved exception handling - The AWS Java SDK uses runtime (or unchecked) exceptions for catching service-level and client-level issues. See AWS SDK for Java Tips and Tricks for more information.
  • Easier access to data returned from operations — No more <OperationName>Response objects.
  • Documentation — More detailed and comprehensive JavaDocs.
  • Minor improvements to service interfaces — Minor changes include renaming RunningInstance to just Instance, and correcting unpluralized list properties.

We recommend switching to the new AWS SDK for Java, where you'll continue to get new feature updates and bug fixes.

Overview of API Changes

The following section lists the API differences between the previous Java libraries and the new AWS SDK for Java.

Changes for All Services

The changes that affect all services include:

  1. Methods that return lists are now pluralized.
    Was: List<Attribute> getAttribute()
    Now: List<Attribute> getAttributes())
  2. Constructors with parameters have changed.
    Was: new CreateDomainRequest(domain)
    Now: new CreateDomainRequest().withDomainName(domain))
  3. The old <OperationName>Response types which encapsulate <OperationName>Result objects have gone away, operations just return the <OperationName>Result directly now. This changes the type and removes the need to perform the isSet<OperationName>Result() check.
  4. The .setEndpoint() method has moved from ClientConfiguration to the client directly; more broadly this is because the purpose of ClientConfiguration has changed from storing client-specific settings to a set of configurations that apply across multiple clients.
  5. Dates are represented as java.util.Date objects, instead of strings.
  6. Operations whose parameters are all optional have an additional method form that doesn't require a request object.
  7. Exceptions are now runtime exceptions (see AWS SDK for Java Tips and Tricks for more information on handling exceptions).
  8. More specific exception subclasses are available to help developers detect specific error conditions (for example: NumberDomainBytesExceededException for Amazon SimpleDB).
  9. The client mock implementations have been removed. Instead, developers are encouraged to use more flexible and full featured mock libraries, such as:
  1. Java package names have changed so that the old client classes (for example: com.amazonaws.ec2) don't conflict with the new SDK classes (for example: com.amazonaws.services.ec2).
  2. toJSONFragment and toXMLFragment methods have been removed from Model objects. Developers who need this functionality are encouraged to use a more standard third-party Java serialization library.
  3. unset<Type> methods have been removed. If you need to empty out a list member in a request object, just pass in null to the setter or fluent setter.
  4. ObjectFactory classes have been removed to simplify using the libraries.
  5. AWS request IDs are available through all Exception objects and through request/response logs.
  6. Enums are available for common string values passed in service requests (for example: Amazon EC2's InstanceType enum lists the available EC2 instance types).

Service-Specific Changes

The additional changes of interest by service are:

Service Changes

Amazon EC2

  • RunningInstances was renamed to Instances.
  • Reservation.getRunningInstances() was renamed to Reservation.getInstances().
  • Attachment was renamed to VolumeAttachment.
  • AvailabilityZone.getZoneState() was renamed to AvailabilityZone.getState().
  • PasswordData class is removed; the data is now available directly from GetPasswordDataResult.
  • ConsoleOutput class is removed; the data is now available directly from GetConsoleOutputResult.
  • Volume.getStatus() was renamed to Volume.getState().

Amazon SimpleDB

  • Item and attribute name/value alternate encoding information is now accessible in the library.
  • SimpleDB BoxUsage is not available yet.

Amazon SQS

  • Message attributes are now represented as Map<String, String>.

Amazon Elastic MapReduce

  • Properties are now represented as a Map<String, String> in HadoopJarStepConfig, instead of a list of KeyValue objects.

Additional Resources

Some additional resources to help you build your application include:

©2017, Amazon Web Services, Inc. or its affiliates. All rights reserved.