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.md
README.md
 
 
run_tests.sh
run_tests.sh
 
 

README.md

AWS SDK for Java (v2) code examples

To build and run these AWS SDK for Java (v2) code examples, you need the following:

  • Apache Maven (>3.0)

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

  • All Java (v2) examples assume that you have set up 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 credentials 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 SDK for Java

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. Most of these AWS SDK for Java tutorials use synchronous Java clients.

If you are interested in using asynchronous Java service clients, see one of these tutorials:

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

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

The following tutorials are AWS Lambda use cases:

If you want to learn how to monitor the performance of an Amazon DynamoDB application in Amazon CloudWatch, see

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 <https://aws.amazon.com/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

Tests

You can test the Java code examples for a given AWS service by running a test file located in this GitHub repository. The test file uses JUnit 5 to run the JUnit tests. It's located in the src/test/java folder. For more information, see https://junit.org/junit5/.

You can run the JUnit tests from a Java IDE, such as IntelliJ, or from the command line by using Maven. As each test runs, you can view messages that inform you if the various tests succeed or fail. For example, the following message informs you that Test 3 passed.

To run the JUnit tests from the command line, you can use the following command.

	mvn test

You will see output from the JUnit tests, with an example shown here.

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running AmazonTranslateTest
Test 1 passed
Test 2 passed
...
Done!
[INFO] Results:
[INFO]
[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] --------------------------------------------
[INFO] BUILD SUCCESS
[INFO]--------------------------------------------
[INFO] Total time:  12.003 s
[INFO] Finished at: 2020-02-10T14:25:08-05:00
[INFO] --------------------------------------------

WARNING: Running these JUnit tests manipulates real Amazon resources and might incur charges on your account.

Properties file

Before running the JUnit tests, you must define required values in the config.properties file that's located in the resources folder. To learn what the values represent, you can refer to the Java code examples. For example, if you are running Amazon S3 tests, look in the various Amazon S3 code example Java files for an explanation of the values.

Docker image (Beta)

This example code will soon be available in a container image hosted on Amazon Elastic Container Registry (ECR). 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 is available on ECR Public but is still undergoing active development. Refer to this GitHub issue for more information.