Skip to content

Commit

Permalink
Merge pull request #1261 from scmacdon/master
Browse files Browse the repository at this point in the history 
Add WorkDoc Java Examples
  • Loading branch information
@Laren-AWS
Laren-AWS committed Jul 9, 2020
2 parents 4091fa3 + a3c413c commit f3c8d28
Show file tree
Hide file tree
Showing 58 changed files with 3,729 additions and 965 deletions.
112 changes: 56 additions & 56 deletions javav2/README.rst
View file
Expand Up @@ -9,120 +9,120 @@
limitations under the License.
###########################################
AWS SDK for Java 2.0 Documentation Examples
AWS SDK for Java 2.0 documentation examples
###########################################

These are examples for the `AWS SDK for Java public documentation <javasdk-docs_>`_.

Prerequisites
=============

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

* `Apache Maven <https://maven.apache.org/>`_ (>3.0)
* `AWS SDK for Java <https://aws.amazon.com/sdk-for-java/>`_ (downloaded and extracted somewhere on
your machine)
* AWS credentials, either configured in a local AWS credentials file or by setting the
* AWS credentials, either configured in a local AWS credentials file or set by using the
``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY`` environment variables.
* You should also set the *AWS region* within which the operations will be performed. If a region is
not set, the default region used will be ``us-east-1``.
* 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``.

For information about how to set AWS credentials and the region for use with the AWS SDK for Java,
see `Set up AWS Credentials and Region for Development
For information about how to set AWS credentials and the Region for use with the AWS SDK for Java,
see `Set up AWS credentials and Region for development
<http://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/setup-credentials.html>`_ in the *AWS
Java Developer Guide*.
SDK for Java Developer Guide*.

AWS Java code examples
======================

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

Use cases
---------

Under the **use_cases** folder, you will locate step by step development articles that use multiple AWS services. By following these articles, you will gain a deeper understanding on how to create Java based applications that use the AWS Java SDK. You will find these 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. These tutorials include:

+ **Creating your first AWS Java Web Application** - an article that discusses using Amazon DynamoDB, Amazon Simple Notification Service (Amazon SNS) and AWS Elastic Beanstalk.
+ **Creating a Secure Spring Application using AWS Services** - an article that discusses using Amazon Relational Database Service (RDS), Amazon Simple Email Service (SES), and AWS Elastic Beanstalk.
+ **Creating AWS Serverless workflows using the Java SDK** - an article that discusses using the AWS Java SDK and AWS Step Functions to create a workflow that invokes AWS services. Each workflow step is implemented by using a Lambda function.
+ **Creating your first AWS Java web application** - A tutorial that discusses using Amazon DynamoDB, Amazon Simple Notification Service (Amazon SNS), and AWS Elastic Beanstalk.
+ **Creating a secure Spring application using AWS services** - A tutorial that discusses using Amazon Relational Database Service (Amazon RDS), Amazon Simple Email Service (Amazon SES), and AWS Elastic Beanstalk.
+ **Creating AWS serverless workflows using the AWS SDK for Java** - A tutorial that discusses using the AWS SDK for Java and AWS Step Functions to create a workflow that invokes AWS services. Each workflow step is implemented by using an AWS Lambda function.
+ **Creating a sample AWS photo analyzer application using the AWS SDK for Java** - A tutorial that discusses using the AWS SDK for Java and various AWS services, such as the Amazon Rekognition service, to analyze images. The application can analyze many images and generate a report that breaks down each image into a series of labels.

AWS service examples
--------------------

The AWS service specific Java examples are located under the **example_code** folder. The examples are divided into directories by AWS service (``s3``, ``sqs``, and so on). Within
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, and a ``Makefile``
that wraps the Maven commands for those of you who also have ``make`` installed.





Build and run the service examples
==================================

Build the examples from a Java IDE
Build the examples from a Java IDE
----------------------------------

You can build the examples in a Java IDE such as IntelliJ. Create a Maven project and be sure to include the POM file you locate in a service directory in your project. This is the easiest way to start building and running the AWS Java examples. The POM file ensures you have access to the Java dependencies. To create an IntelliJ project.
You can build the examples in a Java IDE such as IntelliJ. Create a Maven project and be sure to include the POM file you locate in a service directory in your project. This is the easiest way to start building and running the AWS SDK for Java examples. The POM file ensures you have access to the Java dependencies.

1. In the IntelliJ IDE, choose **File**, **New**, **Project**.
2. In the **New Project** dialog box, choose **Maven**.
**To create an IntelliJ project**

1. In the IntelliJ IDE, choose **File**, **New**, **Project**.
2. In the **New Project** dialog box, choose **Maven**.
3. Choose **Next**.
4. In **GroupId**, enter **aws-project**.
5. In **ArtifactId**, enter **aws-project**.
4. In **GroupId**, enter **aws-project**.
5. In **ArtifactId**, enter **aws-project**.
6. Choose **Next**.
7. Choose **Finish**.
7. Choose **Finish**.

**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.
**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
Build the examples from the command line
-----------------------------------------

To build any of the service examples, open a command-line (terminal) window and change to the directory containing the examples
you want to build/run. Then type::
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 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.
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 simply type::


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

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

Once the examples have been built, you can run them to see them in action.
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
Expand All @@ -134,8 +134,8 @@ Run the service examples

**IMPORTANT**

The examples perform AWS operations for the account and region for which you've specified
credentials, and you may incur AWS service charges by running them. Please visit the `AWS Pricing
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.

Expand All @@ -144,26 +144,26 @@ Run the service examples
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 that contains the depedencies, you can run an example using the following command. For example, you can run a S3 Java V2 example using this command:
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
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
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 <https://www.cygwin.com/>`_, `MingW <http://www.mingw.org/>`_, or
`Bash on Ubuntu on Windows <https://msdn.microsoft.com/en-us/commandline/wsl/about>`_).

You can execute ``run_example.sh`` as shown::

./run_example.sh S3BucketOps

This will run the `S3BucketOps <example_code/s3/src/main/java/com/example/s3/S3BucketOps.java>`_
example (assuming that you've built the examples first!).
This runs the `S3BucketOps <example_code/s3/src/main/java/com/example/s3/S3BucketOps.java>`_
example (assuming that you've built the examples first).

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

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

Expand Down
38 changes: 19 additions & 19 deletions javav2/example_code/athena/Readme.md
View file
@@ -1,51 +1,51 @@
# Amazon Athena Java Readme
# Amazon Athena Java code examples

A README that discusses how to run and test the Java Amazon Athena code examples.
This README discusses how to run and test the Java code examples for Amazon Athena.

## Running the Amazon Athena Java files
## Running the Athena Java files

**IMPORTANT**

The Java examples perform AWS operations for the account and region for which you've specified credentials, and you may incur AWS service charges by running them. Visit the AWS Pricing page for details about the charges you can expect for a given service and operation. For details, see https://aws.amazon.com/pricing/.
The Java code 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](https://aws.amazon.com/pricing/) 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 a named query example. **Be very careful** when running an operation that deletes or modifies AWS resources in your account. It's best to create separate test-only resources when experimenting with these examples.

To run these examples, you'll need the AWS SDK for Java libraries in your **CLASSPATH**:
To run these examples, you'll need the AWS SDK for Java libraries in your **CLASSPATH**.

export CLASSPATH=target/sdk-examples-1.0.jar:/path/to/aws-java-sdk/<jar-file-name>.jar

Where **/path/to/aws-java-sdk/<jar-file-name>.jar** is the path to where you extracted or built the AWS Java SDK jar.
Here **/path/to/aws-java-sdk/<jar-file-name>.jar** is the path to where you extracted or built the AWS SDK for Java JAR file.

Once you set the **CLASSPATH**, you can run a particular example like this:
For systems with Bash support, once you set the **CLASSPATH**, you can run a particular example as follows.

java aws.example.athena.ListNamedQueryExample

For systems with bash support.

**Note**: These code examples depend upon values defined in the **ExampleConstants** Java file. Besure to set values that are applicable to your environment. For example, specify the database that you created by following https://docs.aws.amazon.com/athena/latest/ug/work-with-data.html.
**Note:** These code examples depend on values defined in the **ExampleConstants** Java file. Be sure to set values that are applicable to your environment. For example, specify the database that you created by following https://docs.aws.amazon.com/athena/latest/ug/work-with-data.html.

## Testing the Amazon Athena files
## Testing the Athena Java files

You can test the Amazon Athena Java code examples by running a test file named **AWSAthenaServiceIntegrationTest**. This file uses JUnit 5 to run the JUnit tests and is located in the **src/test/java** folder. For more information, see [https://junit.org/junit5/](https://junit.org/junit5/) .
You can test the Java code examples for Athena by running a test file named **AWSAthenaServiceIntegrationTest**. This file uses JUnit 5 to run the JUnit tests and is located in the **src/test/java** folder. For more information, see [https://junit.org/junit5/](https://junit.org/junit5/).

You can execute the JUnit tests from a Java IDE, such as IntelliJ, or from the command line by using Maven. As each test is executed, 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:
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.

Test 3 passed

**WARNING**: _Running these JUnit tests manipulate real Amazon resources and may incur charges on your account._
**WARNING**: _Running these JUnit tests manipulates real Amazon resources and may incur charges on your account._

### Properties file
Before running the Amazon Athena JUnit tests, you must define values in the **config.properties** file located in the **resources** folder. This file contains values that are required to execute the JUnit tests. For example, you define a named query to use in the tests. If you do not define all values, the JUnit tests fail.
Before running the Amazon Athena JUnit tests, you must define values in the **config.properties** file located in the **resources** folder. This file contains values that are required to run the JUnit tests. For example, you define a named query to use in the tests. If you do not define all values, the JUnit tests fail.

Define these values to successfully run the JUnit tests:
Define this value to successfully run the JUnit tests:

- **nameQuery** - a named query.
- **nameQuery** - A named query.

### Command line
To execute the JUnit tests from the command line, you can use the following command:
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, as shown here:

You will see output from the JUnit tests, as shown here.

[INFO] -------------------------------------------------------
[INFO] T E S T S
Expand All @@ -68,7 +68,7 @@ You will see output from the JUnit tests, as shown here:

### Unsuccessful tests

If you do not define the correct values in the properties file, your JUnit tests are not successful. You will see an error message such as below. You need to double check the values that you set in the properties file and run the tests again.
If you do not define the correct values in the properties file, your JUnit tests are not successful. You will see an error message such as the following. You need to double-check the values that you set in the properties file and run the tests again.

[INFO]
[INFO] --------------------------------------
Expand Down

0 comments on commit f3c8d28

Please sign in to comment.