Setting up the AWS SDK for Java 2.x - AWS SDK for Java

You can now use the Amazon S3 Transfer Manager (Developer Preview) in the AWS SDK for Java 2.x for accelerated file transfers. Give it a try and let us know what you think!

Setting up the AWS SDK for Java 2.x

The AWS SDK for Java 2.x provides Java APIs for Amazon Web Services (AWS). Using the SDK, you can build Java applications that work with Amazon S3, Amazon EC2, DynamoDB, and more.

This section provides information about how to set up your development environment and projects to use the latest version (2.x) of the AWS SDK for Java.

Overview

To make requests to AWS using the AWS SDK for Java, you need the following:

  • An active AWS account

  • An AWS Identity and Access Management (IAM) user with:

    • A programmatic access key

    • Permissions to the AWS resources you’ll access using your application

  • A development environment with:

    • Your access key configured as credentials for AWS

    • Java 8 or later

    • A build automation tool

Create an account

If you do not have an AWS account, visit the Amazon Web Services signup page and follow the on-screen prompts to create and activate a new account.

For more detailed instructions, see How do I create and activate a new AWS account?.

After you activate your new AWS account, follow the instructions in Creating your first IAM admin user and group in the IAM User Guide. Use this account instead of the root account when accessing the AWS Management Console. For more information, see Security best practices in IAM] in the IAM User Guide.

Create an IAM user and programmatic access key

To use the AWS SDK for Java to access AWS services, you need an AWS account and AWS credentials. To increase the security of your AWS account, for access credentials, we recommend that you use an IAM user instead of your AWS account credentials.

Note

For an overview of IAM users and why they are important for the security of your account, see AWS security credentials in the Amazon Web Services General Reference.

For instructions on creating an access key for an existing IAM user, see Programmatic access in the IAM User Guide.

  1. Go to the IAM console (you may need to sign in to AWS first).

  2. Click Users in the sidebar to view your IAM users.

  3. If you don’t have any IAM users set up, click Create New Users to create one.

  4. Select the IAM user in the list that you’ll use to access AWS.

  5. Open the Security Credentials tab, and click Create Access Key. NOTE: You can have a maximum of two active access keys for any given IAM user. If your IAM user has two access keys already, then you’ll need to delete one of them before creating a new key.

  6. On the resulting dialog box, click the Download Credentials button to download the credential file to your computer, or click Show User Security Credentials to view the IAM user’s access key ID and secret access key (which you can copy and paste).

Important

There is no way to obtain the secret access key once you close the dialog box. You can, however, delete its associated access key ID and create a new one.

Set default credentials and Region

To make requests to AWS using the AWS SDK for Java, you must use cryptographically-signed credentials issued by AWS. With AWS SDKs and Tools like the AWS SDK for Java, you use a programmatic access key, consisting of an Access Key ID and and a Secret Access Key, as credentials. You should set your credentials as the default credentials for accessing AWS with your application.

If you already have an IAM account created, see Create an IAM user and programmatic access key for instructions on creating a programmatic access key.

You should also set a default AWS Region for accessing AWS with your application. Some operations require a Region to be set. For the best network performance, you can select a Region that is geographically near to you or your customers.

The most common way to set the default credentials and AWS Region is to use the shared config and credentials files. You can also set the default credentials and Region using environment variables, using Java system properties or, for your applications running on Amazon EC2, using ContainerCredentialsProvider or InstanceProfileCredentialsProvider.

Setting the default credentials

Select one of these options to set the default credentials:

  • Set credentials in the AWS credentials profile file on your local system, located at:

    • ~/.aws/credentials on Linux, macOS, or Unix

    • C:\Users\USERNAME\.aws\credentials on Windows

This file should contain lines in the following format:

[default] aws_access_key_id = your_access_key_id aws_secret_access_key = your_secret_access_key

Substitute your own AWS credentials values for the values your_access_key_id and your_secret_access_key.

  • Set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

To set these variables on Linux, macOS, or Unix, use export :

export AWS_ACCESS_KEY_ID=your_access_key_id export AWS_SECRET_ACCESS_KEY=your_secret_access_key

To set these variables on Windows, use set :

set AWS_ACCESS_KEY_ID=your_access_key_id set AWS_SECRET_ACCESS_KEY=your_secret_access_key
  • For an Amazon EC2 instance, specify an IAM role and then give your Amazon EC2 instance access to that role. See IAM Roles for Amazon EC2 in the Amazon EC2 User Guide for Linux Instances for a detailed discussion about how this works.

  • Set the aws.accessKeyId and aws.secretAccessKey Java system properties.

java app.jar -Daws.accessKeyId=\ "your_access_key_id" \ -Daws.secretAccessKey=\ "your_secret_access_key"

Setting the default Region

Select one of these options to set the default Region:

  • Set the AWS Region in the AWS config file on your local system, located at:

    • ~/.aws/config on Linux, macOS, or Unix

    • C:\Users\USERNAME\.aws\config on Windows

This file should contain lines in the following format:

[default] region = your_aws_region

Substitute your desired AWS Region (for example, "us-east-1") for your_aws_region.

  • Set the AWS_REGION environment variable.

On Linux, macOS, or Unix, use export :

export AWS_REGION=your_aws_region

On Windows, use set :

set AWS_REGION=your_aws_region

Where your_aws_region is the desired AWS Region name.

For additional information about setting credentials and Region, see The .aws/credentials and .aws/config files, AWS Region , and Using environment variables in the AWS SDKs and Tools Reference Guide.

Install Java and a build tool

Your development environment needs the following:

Next steps

Once you have your AWS account and development environment set up, create a Java project using your preferred build tool. Import the Maven bill of materials (BOM) for the AWS SDK for Java 2.x from Maven Central, software.amazon.awssdk. Then add dependendies for the services you’ll use in your application.

Example Maven pom.xml file:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <groupId>com.example.myapp</groupId> <artifactId>myapp</artifactId> <packaging>jar</packaging> <version>1.0-SNAPSHOT</version> <name>myapp</name> <dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>bom</artifactId> <version>2.15.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>3.8.1</version> <scope>test</scope> </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>dynamodb</artifactId> </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>iam</artifactId> </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>kinesis</artifactId> </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>s3</artifactId> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.8.1</version> <configuration> <source>8</source> <target>8</target> </configuration> </plugin> </plugins> </build> </project>

Example build.gradle file:

group 'com.example.myapp' version '1.0' apply plugin: 'java' sourceCompatibility = 1.8 repositories { mavenCentral() } dependencies { implementation platform('software.amazon.awssdk:bom:2.15.0') implementation 'software.amazon.awssdk:dynamodb' implementation 'software.amazon.awssdk:iam' implementation 'software.amazon.awssdk:kinesis' implementation 'software.amazon.awssdk:s3' testImplementation group: 'junit', name: 'junit', version: '4.11' }

For more information, see Setting up an Apache Maven project or Setting up a Gradle project.