Introduction to the AWS SDK for Java
The AWS SDK for Java provides a Java API for AWS infrastructure services. Using the SDK, you can build applications on top of Amazon Simple Storage Service (Amazon S3), Amazon Elastic Compute Cloud (Amazon EC2), Amazon SimpleDB, and more.
The AWS SDK for Java includes:
- AWS Java LibraryBuild Java applications on top of APIs to take the complexity out of coding directly against a web service interface. The library provides APIs that hide much of the lower-level plumbing, including authentication, request retries, and error handling.
- Code SamplesPractical examples for how to use the library to build applications.
- Eclipse supportUse the AWS Toolkit for Eclipse to add the AWS Java SDK to an existing project, or create a new Java project based on the AWS Java SDK.
For more information about the AWS SDK for Java, including a complete list of supported services, see http://aws.amazon.com/sdkforjava.
Signing up for Amazon Web Services
Before you can begin, you must sign up for each service you want to use.
To Sign up for a Service
- Go to the home page for the service. You can find a list of services on http://aws.amazon.com/products.
- Click the Sign Up button on the top right corner of the page. If you don't already have an AWS account, you are prompted to create one as part of the sign up process.
- Follow the on-screen instructions.
AWS sends you a confirmation e-mail after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to http://aws.amazon.com and clicking Your Account.
Getting your AWS Security Credentials
In order to use the AWS SDK for Java, you will need the AWS security credentials that we assigned you when you created your AWS account. Security credentials are used to authenticate requests to a service and identify yourself as the sender of a request. The security credentials used with the AWS SDK for Java are a pair of public/private keys:
- Access Key ID (for example: 022QF06E7MXBSAMPLE)
- Secret Access Key (for example: kWcrlUX5JEDGM/SAMPLE/aVmYvHNif5zB+d9+ct)
IMPORTANT: Your Secret Access Key is a secret, which only you and AWS should know. It is important to keep it confidential to protect your account. Store it securely in a safe place. Never include it in your requests to AWS, and never e-mail it to anyone. Do not share it outside your organization, even if an inquiry appears to come from AWS or Amazon.com. No one who legitimately represents Amazon will ever ask you for your Secret Access Key.
To View Your AWS Security Credentials
- To view your security credentials, go to the Security Credentials page at http://aws.amazon.com/security-credentials.
Getting the Tools You Need
The AWS SDK for Java requires J2SE Development Kit 5.0 or later. You can download the latest Java software from http://developers.sun.com/downloads/. The SDK also requires Apache Commons (Code, HTTP Client, and Logging), and Saxon HE third-party packages, which are included in the
third-party directory of the SDK.
If you use Eclipse, the AWS Toolkit for Eclipse provides support for the AWS SDK for Java as well as additional management features. For more information on installing the AWS Toolkit for Eclipse, see http://aws.amazon.com/eclipse/. We'll go through a few basic tasks for using the AWS SDK for Eclipse with the AWS SDK for Java later in this article.
Using the AWS SDK for Java
Download the AWS SDK for Java from the SDK web page at http://aws.amazon.com/sdkforjava. After downloading the SDK, extract the contents into a folder.
/samples folder includes a number of code samples:
- Console sample Demonstrates how to make a request to multiple services.
- Amazon S3 sample Demonstrates how to use the basic features for Amazon S3, such as putting and getting an object from Amazon S3.
- Amazon SimpleDB sample Demonstrates how to use the basic features for Amazon SimpleDB, including creating and deleting domains, and selecting data from a domain.
- Amazon SQS sample Demonstrates how to use the basic features of Amazon SQS, including adding and getting messages from a queue.
To run a sample
- Open the AwsCredentials.properties in the sample folder. For example, the Console sample file is located at
- Locate the following section and fill in your Access Key ID and Secret Access Key:
# Fill in your AWS Access Key ID and Secret Access Key # http://aws.amazon.com/security-credentials accessKey = secretKey =
- Save the file.
- Run the .java file for your sample, located in the same directory as the properties file. For example, run the
aws-java-sdk/samples/AwsConsoleApp/AwsConsoleApp.javafile for the Console sample. The sample prints information to the standard output, for example:
Welcome to the AWS Java SDK!
=========================================== You have access to 4 Availability Zones.
You have 0 Amazon EC2 instance(s) running.
You have 13 Amazon SimpleDB domain(s)containing a total of 62 items.
You have 23 Amazon S3 bucket(s), containing 44 objects with a total size of 154767691 bytes.
NOTE: Each sample also includes an Ant
build.xml file to run the sample. For more information on Ant, see http://ant.apache.org.
Using the AWS SDK for Java in Eclipse
If you use the AWS Toolkit for Eclipse, you can also start a new project in Eclipse based on the AWS SDK for Java or add the SDK to an existing Java project.
Install the AWS Toolkit for Eclipse
See http://aws.amazon.com/eclipse for information about downloading and installing the AWS Toolkit for Eclipse.
NOTE: After installing the AWS Toolkit for Eclipse, we recommend configuring the toolkit with your security credentials. You can do this anytime by selecting Preferences from the Window menu in Eclipse, and then selecting the AWS Toolkit section.
To start a New Project
- Open Eclipse.
- Create a new AWS Java project by pointing to File -> New -> Project. The New Project wizard opens.
- Expand the AWS category, then select AWS Java Project.
- Click Next. The project settings page is displayed.
- Enter a name in the Project Name box. The AWS SDK for Java Samples group displays the samples available in the SDK, as described above.
- Select the samples you want to include in your project by selecting each check box.
- Enter your AWS credentials. If you've already configured the AWS Toolkit for Eclipse with your credentials, this is automatically filled in.
- Click Finish. The project is created and added to the Project explorer.
To run the Project
- Select the sample .java file you want to run. For example, for the Amazon S3 sample, select
- Select Run from the Run menu.
To add the SDK to an existing project
- Right-click the project in the Project Explorer, then select Build Path -> Add Libraries....
- Select AWS Java SDK, then click Next and follow the remaining on-screen instructions.
Where Do I Go From Here?
Now that you have downloaded the AWS SDK for Java and run a sample (or two), you are ready to start building your own application. Although most applications built on Amazon Web Services are not as simple as the examples in this guide, the principles used in the example can be readily applied to more complex applications.
This section lists some additional resources that may be helpful as you develop your application.