Skip to content

Latest commit

 

History

History
 
 

javav2

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
example_code
example_code
 
 
usecases
usecases
 
 
Dockerfile
Dockerfile
 
 
README.rst
README.rst
 
 

README.rst

AWS SDK for Java 2.0 documentation examples

These are examples for the AWS SDK for Java public documentation.

Prerequisites

To build and run these examples, you need the following:

  • Apache Maven (>3.0)

  • AWS SDK for Java (downloaded and extracted somewhere on your machine)

  • All Java Version 2 examples assume that you have setup your credentials in the credentials file in the .aws folder. For information about how to set AWS credentials and the AWS Region, see Set up AWS credentials and Region for development in the AWS SDK for Java Developer Guide. You should also set the AWS Region within which the operations will be performed. If a Region is not set, the default Region used is us-east-1.

    After you set your AWS credentails in the credentials file located in the .aws folder, you can create a service client like this.

    Region region = Region.US_WEST_2;

    S3Client s3 = S3Client.builder()

    .region(region) .build();

Note: For more information about setting your AWS credentials, see Supplying and retrieving AWS credentials.

AWS Java code examples

The javav2 folder in this repository contains examples of complete use cases, and AWS service-based code examples.

Use cases

In the use_cases folder, find step-by-step development tutorials that use multiple AWS services. By following these tutorials, you will gain a deeper understanding of how to create Java-based applications that use the AWS SDK for Java V2. Most of these AWS SDK for Java V2 tutorials use the Synchronous Java client.

If you are interested in using the Asynchronous Java client, see one of these tutorials:

The following tutorials use the synchronous Java client to build sample relational & non relational database applications:

The following tutorials use the synchronous Java client to build sample applications:

The following tutorials are AWS Lambda use cases:

AWS service examples

The AWS service-specific Java examples are located in the example_code folder. The examples are divided into directories by AWS service (s3, sqs, and so on). Within each, you'll find a pom.xml file used for building the examples with Maven.

Build and run the service examples

Build the examples using Apache Maven or Gradle

To run these examples, you can setup your development environment to use Apache Maven or Gradle to configure and build AWS SDK for Java projects. For more information, see "Get started with the AWS SDK for Java 2.x" located at https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html.

Note: Add the POM file you find in a service-specific folder to the POM file in the project. Then create a package that you find in the examples and you can start adding the Java classes to your project.

Build the examples from the command line

To build any of the service examples, open a command-prompt (terminal) window and change to the directory containing the examples you want to build or run. Then type:

mvn package

You can use the Apache Maven Shade Plugin to package your JAR file with the artifacts in an uber JAR, which consists of all dependencies required to run the project. Ensure that the POM file has the required plugin to build the JAR with the dependencies.

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-shade-plugin</artifactId>

<version>3.0.0</version>

<executions>

<execution>

<phase>package</phase>

<goals>

<goal>shade</goal>

</goals>

</execution>

</executions>

</plugin>

For example, if you execute this command from the s3 directory, you will find a JAR file named S3J2Project-1.0-SNAPSHOT.jar in the target folder.

Or, if you have make, you can begin the build process by typing:

make

Maven will download any dependencies (such as components of the AWS SDK for Java) that it needs for building.

Once the examples are built, you can run them to see them in action.

Note

If you are running on a platform with make, you can also use the provided Makefiles to build the examples, by running make in any directory with a Makefile present. You must still have Maven installed, however (the Makefile wraps Maven commands).

Run the service examples

IMPORTANT

The examples perform AWS operations for the account and AWS Region for which you've specified credentials, and you may incur AWS service charges by running them. See the AWS Pricing page for details about the charges you can expect for a given service and operation.

Some of these examples perform destructive operations on AWS resources, such as deleting an Amazon S3 bucket or an Amazon DynamoDB table. Be very careful when running an operation that may delete or modify AWS resources in your account. It's best to create separate test-only resources when experimenting with these examples.

Because you built the JAR file that contains the dependencies, you can run an example using the following command. For example, you can run an S3 Java V2 example using this command:

java -cp target/S3J2Project-1.0-SNAPSHOT.jar com.example.s3.ListObjects mybucket

For systems with Bash support

As an alternative to setting the CLASSPATH and specifying the full namespace of the class to run, we've included a bash script, run_example.sh, that you can use on Linux, Unix, or OS X (or on Windows by using Cygwin, MingW, or Bash on Ubuntu on Windows).

You can execute run_example.sh as shown:

./run_example.sh S3BucketOps

This runs the S3BucketOps example (assuming that you've built the examples first).

If the example requires arguments, pass the argument list in quotation marks:

./run_example.sh S3BucketOps "<arg1> <arg2> <arg3>"

Docker image (Beta)

This example code will soon be available in a container image hosted on [Amazon Elastic Container Registry (ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html). This image will be pre-loaded with all Java v2 examples with dependencies pre-resolved, allowing you to explore these examples in an isolated environment.

⚠️ As of January 2023, the [SDK for Java v2 image](https://gallery.ecr.aws/b4v4v1s0/javav2) is available on ECR Public but is still undergoing active development. Refer to [this GitHub issue](awsdocs#4128) for more information.