diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..39d4a99 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Guidelines for contributing + +Thank you for your interest in contributing to AWS documentation! We greatly value feedback and contributions from our community. + +Please read through this document before you submit any pull requests or issues. It will help us work together more effectively. + +## What to expect when you contribute + +When you submit a pull request, our team is notified and will respond as quickly as we can. We'll do our best to work with you to ensure that your pull request adheres to our style and standards. If we merge your pull request, we might make additional edits later for style or clarity. + +The AWS documentation source files on GitHub aren't published directly to the official documentation website. If we merge your pull request, we'll publish your changes to the documentation website as soon as we can, but they won't appear immediately or automatically. + +We look forward to receiving your pull requests for: + +* New content you'd like to contribute (such as new code samples or tutorials) +* Inaccuracies in the content +* Information gaps in the content that need more detail to be complete +* Typos or grammatical errors +* Suggested rewrites that improve clarity and reduce confusion + +**Note:** We all write differently, and you might not like how we've written or organized something currently. We want that feedback. But please be sure that your request for a rewrite is supported by the previous criteria. If it isn't, we might decline to merge it. + +## How to contribute + +To contribute, send us a pull request. For small changes, such as fixing a typo or adding a link, you can use the [GitHub Edit Button](https://blog.github.com/2011-04-26-forking-with-the-edit-button/). For larger changes: + +1. [Fork the repository](https://help.github.com/articles/fork-a-repo/). +2. In your fork, make your change in a branch that's based on this repo's **master** branch. +3. Commit the change to your fork, using a clear and descriptive commit message. +4. [Create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/), answering any questions in the pull request form. + +Before you send us a pull request, please be sure that: + +1. You're working from the latest source on the **master** branch. +2. You check [existing open](https://github.com/awsdocs/aws-java-developer-guide/pulls), and [recently closed](https://github.com/awsdocs/aws-java-developer-guide/pulls?q=is%3Apr+is%3Aclosed), pull requests to be sure that someone else hasn't already addressed the problem. +3. You [create an issue](https://github.com/awsdocs/aws-java-developer-guide/issues/new) before working on a contribution that will take a significant amount of your time. + +For contributions that will take a significant amount of time, [open a new issue](https://github.com/awsdocs/aws-java-developer-guide/issues/new) to pitch your idea before you get started. Explain the problem and describe the content you want to see added to the documentation. Let us know if you'll write it yourself or if you'd like us to help. We'll discuss your proposal with you and let you know whether we're likely to accept it. We don't want you to spend a lot of time on a contribution that might be outside the scope of the documentation or that's already in the works. + +## Finding contributions to work on + +If you'd like to contribute, but don't have a project in mind, look at the [open issues](https://github.com/awsdocs/aws-java-developer-guide/issues) in this repository for some ideas. Any issues with the [help wanted](https://github.com/awsdocs/aws-java-developer-guide/labels/help%20wanted) or [enhancement](https://github.com/awsdocs/aws-java-developer-guide/labels/enhancement) labels are a great place to start. + +In addition to written content, we really appreciate new examples and code samples for our documentation, such as examples for different platforms or environments, and code samples in additional languages. + +## Code of conduct + +This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). For more information, see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact [opensource-codeofconduct@amazon.com](mailto:opensource-codeofconduct@amazon.com) with any additional questions or comments. + +## Security issue notifications + +If you discover a potential security issue, please notify AWS Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public issue on GitHub. + +## Licensing + +See the [LICENSE](https://github.com/awsdocs/aws-java-developer-guide/blob/master/LICENSE) file for this project's licensing. We will ask you to confirm the licensing of your contribution. We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. diff --git a/doc_source/.gitignore b/doc_source/.gitignore index 5193fae..4423b35 100644 --- a/doc_source/.gitignore +++ b/doc_source/.gitignore @@ -1 +1,3 @@ example_code +.vscode +_build \ No newline at end of file diff --git a/doc_source/_includes.txt b/doc_source/_includes.txt index 9f44984..ce7ff73 100644 --- a/doc_source/_includes.txt +++ b/doc_source/_includes.txt @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -28,6 +28,7 @@ .. |ddbclient| replace:: :aws-java-class:`AmazonDynamoDB ` .. |ec2client| replace:: :aws-java-class:`AmazonEC2Client ` .. |iamclient| replace:: :aws-java-class:`AmazonIdentityManagementClient ` +.. |pinpointclient| replace:: :aws-java-class:`AmazonPinpointClient ` .. |s3client| replace:: :aws-java-class:`AmazonS3 ` .. |sqsclient| replace:: :aws-java-class:`AmazonSQS ` .. |xfermgr| replace:: :aws-java-class:`TransferManager ` diff --git a/doc_source/basics-async.rst b/doc_source/basics-async.rst index 3e60ebc..3c29ca5 100644 --- a/doc_source/basics-async.rst +++ b/doc_source/basics-async.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/basics.rst b/doc_source/basics.rst index 4808aed..83cf334 100644 --- a/doc_source/basics.rst +++ b/doc_source/basics.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/best-practices.rst b/doc_source/best-practices.rst index 0d63355..c33d46c 100644 --- a/doc_source/best-practices.rst +++ b/doc_source/best-practices.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/compliance-validation.rst b/doc_source/compliance-validation.rst new file mode 100644 index 0000000..f3ea15b --- /dev/null +++ b/doc_source/compliance-validation.rst @@ -0,0 +1,58 @@ +Compliance Validation for this AWS Product or Service +===================================================== + +This AWS product or service follows the `shared responsibility +model `__ +through the specific Amazon Web Services (AWS) services it supports. For +AWS service security information, see the `AWS service security +documentation +page `__ +and `AWS services that are in scope of AWS compliance efforts by +compliance +program `__. + +The security and compliance of AWS services is assessed by third-party +auditors as part of multiple AWS compliance programs. These include SOC, +PCI, FedRAMP, HIPAA, and others. AWS provides a frequently updated list +of AWS services in scope of specific compliance programs at `AWS +Services in Scope by Compliance +Program `__. + +Third-party audit reports are available for you to download using AWS +Artifact. For more information, see `Downloading Reports in AWS +Artifact `__. + +For more information about AWS compliance programs, see `AWS Compliance +Programs `__. + +Your compliance responsibility when using this AWS product or service to +access an AWS service is determined by the sensitivity of your data, +your organization’s compliance objectives, and applicable laws and +regulations. If your use of an AWS service is subject to compliance with +standards such as HIPAA, PCI, or FedRAMP, AWS provides resources to +help: + + + `Security and Compliance Quick Start Guides + `__ + – Deployment guides that discuss architectural considerations and provide steps for + deploying security-focused and compliance-focused baseline environments on AWS. + + + + `Architecting for HIPAA Security and Compliance Whitepaper + `__ + – A whitepaper that describes how companies can use AWS to create + HIPAA-compliant applications. + + + + `AWS Compliance Resources `__ + – A collection of workbooks and guides that might apply to your industry and + location. + + + + `AWS Config `__ – A service that assesses how well your + resource configurations comply with internal practices, industry guidelines, and regulations. + + + + `AWS Security Hub `__ – A comprehensive view of + your security state within AWS that helps you check your compliance with + security industry standards and best practices. diff --git a/doc_source/conf.py b/doc_source/conf.py index 3cebc1c..c8adbe8 100644 --- a/doc_source/conf.py +++ b/doc_source/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +# Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"). You may not # use this file except in compliance with the License. A copy of the License @@ -121,7 +121,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'bizstyle' +html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -404,3 +404,9 @@ 'blob/master/java/example_code/{svc}/src/main/java/aws/example/{svc}/'.format(svc=svc) + '%s', '') +for svc in [ + 'pinpoint' + ]: + extlinks['sdk-examples-java-%s' % svc] = (samples_url + + 'blob/master/java/example_code/{svc}/src/main/java/com/example/{svc}/'.format(svc=svc) + + '%s', '') diff --git a/doc_source/create-key-pair.rst b/doc_source/create-key-pair.rst index 72d9e05..3e65052 100644 --- a/doc_source/create-key-pair.rst +++ b/doc_source/create-key-pair.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/create-security-group.rst b/doc_source/create-security-group.rst index e9bfe47..38ffae3 100644 --- a/doc_source/create-security-group.rst +++ b/doc_source/create-security-group.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/creating-clients.rst b/doc_source/creating-clients.rst index 8df9392..d35a445 100644 --- a/doc_source/creating-clients.rst +++ b/doc_source/creating-clients.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -139,8 +139,10 @@ Client Lifecycle ================ Service clients in the SDK are thread-safe and, for best performance, you should treat them as -long-lived objects. Each client has its own connection pool resource that is shut down when the -client is garbage collected. To explicitly shut down a client, call the +long-lived objects. Each client has its own connection pool resource. +Explicitly shut down clients when they are no longer needed to avoid resource leaks. + +To explicitly shut down a client, call the :methodname:`shutdown` method. After calling :methodname:`shutdown`, all client resources are released and the client is unusable. @@ -151,4 +153,3 @@ released and the client is unusable. AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient(); ddb.shutdown(); // Client is now unusable - diff --git a/doc_source/credentials.rst b/doc_source/credentials.rst index 6ca53c4..2d017ea 100644 --- a/doc_source/credentials.rst +++ b/doc_source/credentials.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -48,6 +48,8 @@ class. The default credential provider chain looks for credentials in this order The |sdk-java| uses the :aws-java-class:`SystemPropertiesCredentialsProvider ` to load these credentials. +#. **Web Identity Token credentials** from the environment or container. + #. **The default credential profiles file** |ndash| typically located at :file:`~/.aws/credentials` (location can vary per platform), and shared by many of the AWS SDKs and by the AWS CLI. The |sdk-java| uses the :aws-java-class:`ProfileCredentialsProvider ` to load these credentials. @@ -59,17 +61,17 @@ class. The default credential provider chain looks for credentials in this order #. **Amazon ECS container credentials** |ndash| loaded from the |ECS| if the environment variable :envvar:`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is set. The |sdk-java| uses the :aws-java-class:`ContainerCredentialsProvider ` to load these - credentials. + credentials. You can specify the IP address for this value. + #. **Instance profile credentials** |ndash| used on EC2 instances, and delivered through the |EC2| metadata service. The |sdk-java| uses the :aws-java-class:`InstanceProfileCredentialsProvider - ` to load these credentials. + ` to load these credentials. You can specify the IP address for this value. .. note:: Instance profile credentials are used only if :envvar:`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is not set. See :aws-java-class:`EC2ContainerCredentialsProviderWrapper ` for more information. - Setting Credentials ------------------- diff --git a/doc_source/data-protection.rst b/doc_source/data-protection.rst new file mode 100644 index 0000000..185e987 --- /dev/null +++ b/doc_source/data-protection.rst @@ -0,0 +1,46 @@ +.. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +##################################### +Data Protection in |SERVICENAMETITLE| +##################################### + +.. meta:: + :description: Learn how the AWS shared responsibility model applies to data protection in this AWS product or service. + :keywords: + +.. include:: common/_security-includes.txt + +|SERVICENAMESENTENCECASE| conforms to the `shared responsibility model `_, +which includes regulations and guidelines for data protection. |AWSlong| (|AWS|) is responsible for protecting the global infrastructure +that runs all the |AWS| services. |AWS| maintains control over data hosted on this infrastructure, including the security configuration +controls for handling customer content and personal data. |AWS| customers and APN partners, acting either as data controllers or data +processors, are responsible for any personal data that they put in the |AWS| Cloud. + +For data protection purposes, we recommend that you protect |AWS| account credentials and set up individual user accounts with +|IAMlong| (|IAM|), so that each user is given only the permissions necessary to fulfill their job duties. We also recommend that +you secure your data in the following ways: + +* Use multi-factor authentication (MFA) with each account. +* Use SSL/TLS to communicate with |AWS| resources. To use a minimum TLS version of 1.2, see `Enforcing TLS 1.2 `_. +* Set up API and user activity logging with |CTlong|. +* Use |AWS| encryption solutions, along with all default security controls within |AWS| services. +* Use advanced managed security services such as |MCElong|, which assists in discovering and securing personal data that + is stored in |S3|. + +We strongly recommend that you never put sensitive identifying information, such as your customers' account numbers, into +free-form fields such as a **Name** field. This includes when you work with |SERVICENAME| or other |AWS| services +using the console, API, |CLI|, or |AWS| SDKs. Any data that you enter into |SERVICENAME| or other services might get picked up +for inclusion in diagnostic logs. When you provide a URL to an external server, don't include credentials information in the URL +to validate your request to that server. + +For more information about data protection, see the +`AWS Shared Responsibility Model and GDPR `_ +blog post on the *AWS Security Blog*. \ No newline at end of file diff --git a/doc_source/disaster-recovery-resiliency.rst b/doc_source/disaster-recovery-resiliency.rst new file mode 100644 index 0000000..e4abd93 --- /dev/null +++ b/doc_source/disaster-recovery-resiliency.rst @@ -0,0 +1,29 @@ +Resilience for this AWS Product or Service +========================================== + +The Amazon Web Services (AWS) global infrastructure is built around AWS +Regions and Availability Zones. + +AWS Regions provide multiple physically separated and isolated +Availability Zones, which are connected with low-latency, +high-throughput, and highly redundant networking. + +With Availability Zones, you can design and operate applications and +databases that automatically fail over between Availability Zones +without interruption. Availability Zones are more highly available, +fault tolerant, and scalable than traditional single or multiple data +center infrastructures. + +For more information about AWS Regions and Availability Zones, see `AWS +Global +Infrastructure `__. + +This AWS product or service follows the `shared responsibility +model `__ +through the specific Amazon Web Services (AWS) services it supports. For +AWS service security information, see the `AWS service security +documentation +page `__ +and `AWS services that are in scope of AWS compliance efforts by +compliance +program `__. diff --git a/doc_source/document-history.rst b/doc_source/document-history.rst index 02377a6..1b3c234 100644 --- a/doc_source/document-history.rst +++ b/doc_source/document-history.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -16,6 +16,9 @@ This topic describes important changes to the |sdk-java-dg| over the course of i **This documentation was built on:** |today| +Mar 22, 2018 + Removed managing Tomcat sessions in |DDB| example as that tool is no longer supported. + Nov 2, 2017 Added cryptography examples for |S3| encryption client, including new topics: :doc:`examples-crypto` and :doc:`examples-crypto-kms` and :doc:`examples-crypto-masterkey`. diff --git a/doc_source/examples-cloudwatch-create-alarms.rst b/doc_source/examples-cloudwatch-create-alarms.rst index 3b8dfac..5fe9241 100644 --- a/doc_source/examples-cloudwatch-create-alarms.rst +++ b/doc_source/examples-cloudwatch-create-alarms.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -96,6 +96,6 @@ More Information ================ * :cw-ug:`Creating Amazon CloudWatch Alarms ` in the |cw-ug| -* :cw-api:`PutMetricAlarm` in the |cw-api| -* :cw-api:`DescribeAlarms` in the |cw-api| -* :cw-api:`DeleteAlarms` in the |cw-api| +* :cw-api:`PutMetricAlarm ` in the |cw-api| +* :cw-api:`DescribeAlarms ` in the |cw-api| +* :cw-api:`DeleteAlarms ` in the |cw-api| diff --git a/doc_source/examples-cloudwatch-get-metrics.rst b/doc_source/examples-cloudwatch-get-metrics.rst index e5caac2..940681d 100644 --- a/doc_source/examples-cloudwatch-get-metrics.rst +++ b/doc_source/examples-cloudwatch-get-metrics.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -50,4 +50,4 @@ the original request object with the return value of the :classname:`ListMetrics More Information ================ -* :cw-api:`ListMetrics` in the |cw-api|. +* :cw-api:`ListMetrics ` in the |cw-api|. diff --git a/doc_source/examples-cloudwatch-publish-custom-metrics.rst b/doc_source/examples-cloudwatch-publish-custom-metrics.rst index 68a638a..cac7e04 100644 --- a/doc_source/examples-cloudwatch-publish-custom-metrics.rst +++ b/doc_source/examples-cloudwatch-publish-custom-metrics.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -52,4 +52,4 @@ More Information * :cw-ug:`Using Amazon CloudWatch Metrics ` in the |cw-ug|. * :cw-ug:`AWS Namespaces ` in the |cw-ug|. -* :cw-api:`PutMetricData` in the |cw-api|. +* :cw-api:`PutMetricData ` in the |cw-api|. diff --git a/doc_source/examples-cloudwatch-send-events.rst b/doc_source/examples-cloudwatch-send-events.rst index 3e2d9c2..15d43fa 100644 --- a/doc_source/examples-cloudwatch-send-events.rst +++ b/doc_source/examples-cloudwatch-send-events.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -99,6 +99,6 @@ More Information * :cwe-ug:`Schedule Expressions for Rules ` in the |cwe-ug| * :cwe-ug:`Event Types for CloudWatch Events ` in the |cwe-ug| * :cwe-ug:`Events and Event Patterns ` in the |cwe-ug| -* :cwe-api:`PutEvents` in the |cwe-api| -* :cwe-api:`PutTargets` in the |cwe-api| -* :cwe-api:`PutRule` in the |cwe-api| +* :cwe-api:`PutEvents ` in the |cwe-api| +* :cwe-api:`PutTargets ` in the |cwe-api| +* :cwe-api:`PutRule ` in the |cwe-api| diff --git a/doc_source/examples-cloudwatch-use-alarm-actions.rst b/doc_source/examples-cloudwatch-use-alarm-actions.rst index 7c28cab..a317a27 100644 --- a/doc_source/examples-cloudwatch-use-alarm-actions.rst +++ b/doc_source/examples-cloudwatch-use-alarm-actions.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -73,6 +73,6 @@ More Information * :cw-ug:`Create Alarms to Stop, Terminate, Reboot, or Recover an Instance ` in the |cw-ug| -* :cw-api:`PutMetricAlarm` in the |cw-api| -* :cw-api:`EnableAlarmActions` in the |cw-api| -* :cw-api:`DisableAlarmActions` in the |cw-api| +* :cw-api:`PutMetricAlarm ` in the |cw-api| +* :cw-api:`EnableAlarmActions ` in the |cw-api| +* :cw-api:`DisableAlarmActions ` in the |cw-api| diff --git a/doc_source/examples-cloudwatch.rst b/doc_source/examples-cloudwatch.rst index 95b0596..db3414f 100644 --- a/doc_source/examples-cloudwatch.rst +++ b/doc_source/examples-cloudwatch.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -14,7 +14,7 @@ .. meta:: :description: Programming Amazon Cloudwatch using the AWS SDK for Java - :keywords: AWS SDK for Java code examples, IAM + :keywords: AWS SDK for Java code examples, Cloudwatch This section provides examples of programming |cw|_ using the |sdk-java|_. @@ -33,4 +33,3 @@ For more information about |cw|, see the |cw-ug|_. examples-cloudwatch-create-alarms examples-cloudwatch-use-alarm-actions examples-cloudwatch-send-events - diff --git a/doc_source/examples-crypto-kms.rst b/doc_source/examples-crypto-kms.rst index 571819e..b0dc34d 100644 --- a/doc_source/examples-crypto-kms.rst +++ b/doc_source/examples-crypto-kms.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -9,7 +9,7 @@ limitations under the License. ################################################### -|S3| Client-Side Encryption with |KMS| Managed Keys +|S3| client-side encryption with |KMS| managed keys ################################################### .. meta:: @@ -17,7 +17,7 @@ :keywords: AWS SDK for Java code examples, cryptography, encryption The following examples use the -:aws-java-class:`AmazonS3EncryptionClientBuilder ` class +:aws-java-class:`AmazonS3EncryptionClientV2Builder ` class to create an |S3| client with client-side encryption enabled. Once configured, any objects you upload to |S3| using this client will be encrypted. Any objects you get from |S3| using this client are automatically @@ -28,65 +28,82 @@ decrypted. encryption with |KMS| managed keys. To learn how to use encryption with your own keys, see :doc:`examples-crypto-masterkey`. -You can choose from three encryption modes when enabling client-side |S3| encryption: encryption-only, -authenticated, and strict authenticated. +You can choose from two encryption modes when enabling client-side |S3| encryption: strict +authenticated or authenticated. The following sections show how to enable each type. To learn which algorithms each mode uses, see the :aws-java-class:`CryptoMode ` definition. -Required Imports +Required imports ================ Import the following classes for these examples. **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 16-31 - :language: java +.. code-block:: java -.. _encryption-only: + import com.amazonaws.ClientConfiguration; + import com.amazonaws.regions.Regions; + import com.amazonaws.services.kms.AWSKMS; + import com.amazonaws.services.kms.AWSKMSClientBuilder; + import com.amazonaws.services.kms.model.GenerateDataKeyRequest; + import com.amazonaws.services.kms.model.GenerateDataKeyResult; + import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder; + import com.amazonaws.services.s3.AmazonS3EncryptionV2; + import com.amazonaws.services.s3.model.CryptoConfigurationV2; + import com.amazonaws.services.s3.model.CryptoMode; + import com.amazonaws.services.s3.model.EncryptionMaterials; + import com.amazonaws.services.s3.model.KMSEncryptionMaterialsProvider; -Encryption-Only Mode -==================== +.. _strict-authenticated-encryption-kms: -Encryption-only is the default mode, if no :classname:`CryptoMode` is specified. -To use an |KMS| -managed key for encryption, pass the |KMS| key ID or alias to the -:aws-java-class:`KMSEncryptionMaterialsProvider` constructor. +Strict authenticated encryption +=============================== + +Strict authenticated encryption is the default mode if no :classname:`CryptoMode` is specified. + +To explicitly enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the +:methodName:`withCryptoConfiguration` method. + +.. note:: To use client-side authenticated encryption, you must include the latest + `Bouncy Castle jar `_ file + in the classpath of your application. **Code** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 237-243 - :dedent: 8 - :language: java +.. code-block:: java + + AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard() + .withRegion(Regions.US_WEST_2) + .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption))) + .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId)) + .build(); + + s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the AWS Console"); + System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3)); Call the :methodname:`putObject` method on the |S3| encryption client to upload objects. **Code** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 247 - :dedent: 8 - :language: java +.. code-block:: java + + s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the AWS Console"); You can retrieve the object using the same client. This example calls the :methodname:`getObjectAsString` method to retrieve the string that was stored. **Code** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 249 - :dedent: 8 - :language: java +.. code-block:: java -See the :sdk-examples-java-s3:`complete example ` on GitHub. + System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3)); -.. _authenticated-encryption: +.. _authenticated-encryption-kms: -Authenticated Encryption Mode +Authenticated encryption mode ============================= When you use :classname:`AuthenticatedEncryption` mode, an improved key wrapping algorithm is @@ -101,57 +118,16 @@ blog post. file in the classpath of your application. To enable this mode, specify the :classname:`AuthenticatedEncryption` value in the -:method:`withCryptoConfiguration` method. - - -**Code** - -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 257-263 - :dedent: 8 - :language: java - -The :classname:`AuthenticatedEncryption` mode can retrieve unencrypted objects and -objects encrypted with :classname:`EncryptionOnly` mode. The following example shows the -|S3| encryption client retrieving an unencrypted object. - -**Code** - -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 257-270 - :dedent: 8 - :language: java - -See the :sdk-examples-java-s3:`complete example ` on GitHub. - -.. _strict-authenticated-encryption: - -Strict Authenticated Encryption -=============================== - -To enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the -:method:`withCryptoConfiguration` method. - -.. note:: To use client-side authenticated encryption, you must include the latest - `Bouncy Castle jar `_ file - in the classpath of your application. - -**Code** - -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 278-284 - :dedent: 8 - :language: java +:methodName:`withCryptoConfiguration` method. -In :classname:`StrictAuthenticatedEncryption` mode, the |S3| client throws an -exception when retrieving an object that was not encrypted using an -authenticated mode. **Code** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 278-295 - :dedent: 8 - :language: java +.. code-block:: java -See the :sdk-examples-java-s3:`complete example ` on GitHub. + AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard() + .withRegion(Regions.US_WEST_2) + .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption))) + .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId)) + .build(); + \ No newline at end of file diff --git a/doc_source/examples-crypto-masterkey.rst b/doc_source/examples-crypto-masterkey.rst index 0b96960..5afbd50 100644 --- a/doc_source/examples-crypto-masterkey.rst +++ b/doc_source/examples-crypto-masterkey.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -9,7 +9,7 @@ limitations under the License. ################################################### -|S3| Client-Side Encryption with Client Master Keys +|S3| client-side encryption with client master keys ################################################### .. meta:: @@ -17,7 +17,7 @@ :keywords: AWS SDK for Java code examples The following examples use the -:aws-java-class:`AmazonS3EncryptionClientBuilder ` class +:aws-java-class:`AmazonS3EncryptionClientV2Builder ` class to create an |S3| client with client-side encryption enabled. Once enabled, any objects you upload to |S3| using this client will be encrypted. Any objects you get from |S3| using this client will automatically @@ -28,74 +28,57 @@ be decrypted. encryption with customer-managed client master keys. To learn how to use encryption with |KMS| managed keys, see :doc:`examples-crypto-kms`. -You can choose from three encryption modes when enabling client-side |S3| encryption: encryption-only, -authenticated, and strict authenticated. +You can choose from two encryption modes when enabling client-side |S3| encryption: strict +authenticated or authenticated. The following sections show how to enable each type. To learn which algorithms each mode uses, see the :aws-java-class:`CryptoMode ` definition. -Required Imports +Required imports ================ Import the following classes for these examples. **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 16-24,26-31 - :language: java +.. code-block:: java -.. _encryption-only: + import com.amazonaws.ClientConfiguration; + import com.amazonaws.regions.Regions; + import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder; + import com.amazonaws.services.s3.AmazonS3EncryptionV2; + import com.amazonaws.services.s3.model.CryptoConfigurationV2; + import com.amazonaws.services.s3.model.CryptoMode; + import com.amazonaws.services.s3.model.EncryptionMaterials; + import com.amazonaws.services.s3.model.StaticEncryptionMaterialsProvider; -Encryption-Only Mode -==================== - -Encryption-only is the default mode, if no :classname:`CryptoMode` is specified. To enable -encryption, you must pass a key to the :aws-java-class:`EncryptionMaterials` -constructor. The example below uses -the :class:`KeyGenerator` Java class generate a symmetric private key. - -**Code** - -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 198-204 - :dedent: 8 - :language: java +.. _strict-authenticated-encryption: -To use an asymmetric key or a key pair, simply pass the key pair to the same -:aws-java-class:`EncryptionMaterials` class. The example below uses the -:class:`KeyPairGenerator` class to generate a key pair. +Strict authenticated encryption +=============================== -**Code** +Strict authenticated encryption is the default mode if no :classname:`CryptoMode` is specified. -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 217-223 - :dedent: 8 - :language: java +To explicitly enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the +:methodName:`withCryptoConfiguration` method. -Call the :methodname:`putObject` method on the |S3| encryption client to upload objects. +.. note:: To use client-side authenticated encryption, you must include the latest + `Bouncy Castle jar `_ file + in the classpath of your application. **Code** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 227 - :dedent: 8 - :language: java - -You can retrieve the object using the same client. This example calls the -:methodname:`getObjectAsString` method to retrieve the string that was stored. - -**Code** +.. code-block:: java -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 229 - :dedent: 8 - :language: java + AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard() + .withRegion(Regions.US_WEST_2) + .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption))) + .withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) + .build(); -See the :sdk-examples-java-s3:`complete example ` on GitHub. + s3Encryption.putObject(bucket_name, ENCRYPTED_KEY2, "This is the 2nd content to encrypt"); -.. _authenticated-encryption: -Authenticated Encryption Mode +Authenticated encryption mode ============================= When you use :classname:`AuthenticatedEncryption` mode, an improved key wrapping algorithm is @@ -110,56 +93,18 @@ blog post. in the classpath of your application. To enable this mode, specify the :classname:`AuthenticatedEncryption` value in the -:method:`withCryptoConfiguration` method. - -**Code** - -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 67-72 - :dedent: 8 - :language: java - -The :classname:`AuthenticatedEncryption` mode can retrieve unencrypted objects and -objects encrypted with :classname:`EncryptionOnly` mode. The following example shows the -|S3| encryption client retrieving an unencrypted object. - -**Code** - -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 66-79 - :dedent: 8 - :language: java - -See the :sdk-examples-java-s3:`complete example ` on GitHub. - -.. _strict-authenticated-encryption: - -Strict Authenticated Encryption -=============================== - -To enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the -:method:`withCryptoConfiguration` method. - -.. note:: To use client-side authenticated encryption, you must include the latest - `Bouncy Castle jar `_ file - in the classpath of your application. +:methodName:`withCryptoConfiguration` method. **Code** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 132-137 - :dedent: 8 - :language: java +.. code-block:: java -In :classname:`StrictAuthenticatedEncryption` mode, the |S3| client throws an -exception when retrieving an object that was not encrypted using an -authenticated mode. - -**Code** + AmazonS3EncryptionV2 s3EncryptionClientV2 = AmazonS3EncryptionClientV2Builder.standard() + .withRegion(Regions.DEFAULT_REGION) + .withClientConfiguration(new ClientConfiguration()) + .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode(CryptoMode.AuthenticatedEncryption)) + .withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) + .build(); -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java - :lines: 131-149 - :dedent: 8 - :language: java + s3EncryptionClientV2.putObject(bucket_name, ENCRYPTED_KEY1, "This is the 1st content to encrypt"); -See the :sdk-examples-java-s3:`complete example ` on GitHub. diff --git a/doc_source/examples-crypto.rst b/doc_source/examples-crypto.rst index 54fed24..c37c681 100644 --- a/doc_source/examples-crypto.rst +++ b/doc_source/examples-crypto.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,9 +8,9 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -################################# -Using |S3| Client-Side Encryption -################################# +############################### +Use |S3| client-side encryption +############################### .. meta:: :description: How to use the cryptography configuration settings for the AWS SDK for Java @@ -20,12 +20,25 @@ Encrypting data using the |S3| encryption client is one way you can provide an additional layer of protection for sensitive information you store in |S3|. The examples in this section demonstrate how to create and configure the |S3| encryption client for your application. -If you are new to cryptography, -see the :KMS-dg:`Cryptography Basics ` in the |KMS-dg| for a basic overview of -cryptography terms and algorithms. + +If you are new to cryptography, see the :KMS-dg:`Cryptography Basics ` in the |KMS-dg| +for a basic overview of cryptography terms and algorithms. For information about cryptography +support across all AWS SDKs, see +:AWS-gr:`AWS SDK Support for Amazon S3 Client-Side Encryption ` in the +|AWS-gr|. .. include:: includes/examples-note.txt +If you are using version 1.11.836 or earlier of the AWS SDK for Java, see +:doc:`s3-encryption-migration` for information on migrating your applications to later versions. +If you cannot migrate, see +`this complete example `_ +on GitHub. + +Otherwise, if you are using version 1.11.837 or later of the AWS SDK for Java, explore the example +topics listed below to use |S3| client-side encryption. + + .. toctree:: :titlesonly: :maxdepth: 1 @@ -33,5 +46,4 @@ cryptography terms and algorithms. examples-crypto-masterkey examples-crypto-kms -For information about cryptography support across all AWS SDKs, see -:AWS-gr:`AWS SDK Support for Amazon S3 Client-Side Encryption ` in the |AWS-gr|. + diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst index 301f5e1..b360d0a 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -28,8 +28,8 @@ Retrieve (Get) an Item from a Table Call the |ddbclient|'s :methodname:`getItem` method and pass it a :aws-java-class:`GetItemRequest ` object with the table -name and primary key value of the item you want. It returns a `GetItemResult -` object. +name and primary key value of the item you want. It returns a +:aws-java-class:`GetItemResult ` object. You can use the returned :classname:`GetItemResult` object's :methodname:`getItem()` method to retrieve a :javase-ref:`Map ` of key (String) and value @@ -110,6 +110,32 @@ update. See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. +Use the DynamoDBMapper class +================================== + +The |sdk-java|_ provides a :aws-java-class:`DynamoDBMapper ` class, +allowing you to map your client-side classes to Amazon DynamoDB tables. To use the :aws-java-class:`DynamoDBMapper ` class, +you define the relationship between items in a DynamoDB table and their corresponding object instances in your code by using annotations (as shown in the following code example). +The :aws-java-class:`DynamoDBMapper ` class enables you to access your tables; perform various create, read, update, and delete (CRUD) operations; and execute queries. + +.. note:: The :aws-java-class:`DynamoDBMapper ` class does not allow you to create, update, or delete tables. + +**Imports** + +.. literalinclude:: dynamodb.java.dynamoDB_mapping.import.txt + :language: java + +**Code** + +The following Java code example shows you how to add content to the *Music* table by using the :aws-java-class:`DynamoDBMapper ` class. +After the content is added to the table, notice that an item is loaded by using the +*Partition* and *Sort* keys. Then the *Awards* item is updated. For information on creating the *Music* table, see :ddb-dg:`Create a Table ` in the |ddb-dg|. + +.. literalinclude:: dynamodb.java.dynamoDB_mapping.main.txt + :dedent: 1 + :language: java + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. More Info ========= diff --git a/doc_source/examples-dynamodb-tables.rst b/doc_source/examples-dynamodb-tables.rst index b79e987..faff57d 100644 --- a/doc_source/examples-dynamodb-tables.rst +++ b/doc_source/examples-dynamodb-tables.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -53,7 +53,8 @@ Create a Table Use the :aws-java-class:`DynamoDB client `'s :methodname:`createTable` method to create a new |DDB| table. You need to construct table attributes and a table schema, both of which are used to identify the primary key of your table. You -must also supply initial provisioned throughput values and a table name. +must also supply initial provisioned throughput values and a table name. Only define key table attributes +when creating your |DDB| table. .. note:: If a table with the name you chose already exists, an :aws-java-class:`AmazonServiceException` is thrown. @@ -71,7 +72,7 @@ must also supply initial provisioned throughput values and a table name. Create a Table with a Simple Primary Key ---------------------------------------- -This code creates a table with a simple primary key ("Name"). +This code creates a table with a simple primary key ("Name"). **Code** @@ -90,7 +91,7 @@ Create a Table with a Composite Primary Key Add another :aws-java-class:`AttributeDefinition ` and :aws-java-class:`KeySchemaElement ` to -:aws-java-class:`CreateTableRequest `. +:aws-java-class:`CreateTableRequest `. **Code** @@ -116,18 +117,18 @@ You can list the tables in a particular region by calling the :aws-java-class:`D **Imports** .. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/ListTables.java - :lines: 15-18 + :lines: 15-19 :language: java **Code** .. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/ListTables.java - :lines: 33-63 + :lines: 33-67 :dedent: 8 :language: java By default, up to 100 tables are returned per call |mdash| use -:methodname:`getLastEvaluatedTableName` on the returned :aws-java-class:`ListTablesResult <>` object +:methodname:`getLastEvaluatedTableName` on the returned :aws-java-class:`ListTablesResult ` object to get the last table that was evaluated. You can use this value to start the listing after the last returned value of the previous listing. diff --git a/doc_source/examples-dynamodb.rst b/doc_source/examples-dynamodb.rst index 0bb24dd..1ede57b 100644 --- a/doc_source/examples-dynamodb.rst +++ b/doc_source/examples-dynamodb.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -26,5 +26,3 @@ This section provides examples of programming |ddb|_ using the |sdk-java|_. examples-dynamodb-tables examples-dynamodb-items - java-dg-tomcat-session-manager - diff --git a/doc_source/examples-ec2-elastic-ip.rst b/doc_source/examples-ec2-elastic-ip.rst index 74d4693..b13cade 100644 --- a/doc_source/examples-ec2-elastic-ip.rst +++ b/doc_source/examples-ec2-elastic-ip.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-ec2-instances.rst b/doc_source/examples-ec2-instances.rst index 5179312..88e681f 100644 --- a/doc_source/examples-ec2-instances.rst +++ b/doc_source/examples-ec2-instances.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -205,6 +205,5 @@ More Information * :ec2-api:`StartInstances` in the |ec2-api| * :ec2-api:`StopInstances` in the |ec2-api| * :ec2-api:`RebootInstances` in the |ec2-api| -* :ec2-api:`DescribeInstances` in the |ec2-api| * :ec2-api:`MonitorInstances` in the |ec2-api| * :ec2-api:`UnmonitorInstances` in the |ec2-api| diff --git a/doc_source/examples-ec2-key-pairs.rst b/doc_source/examples-ec2-key-pairs.rst index 80681d9..4461cff 100644 --- a/doc_source/examples-ec2-key-pairs.rst +++ b/doc_source/examples-ec2-key-pairs.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -45,8 +45,8 @@ Describing Key Pairs ==================== To list your key pairs or to get information about them, call the |ec2client|'s -:methodname:`describeKeyPairs` method. It returns a :aws-java-class:`DescribeKeyPairsRequest -` that you can use to access the list of key pairs by +:methodname:`describeKeyPairs` method. It returns a :aws-java-class:`DescribeKeyPairsResult +` that you can use to access the list of key pairs by calling its :methodname:`getKeyPairs` method, which returns a list of :aws-java-class:`KeyPairInfo ` objects. diff --git a/doc_source/examples-ec2-regions-zones.rst b/doc_source/examples-ec2-regions-zones.rst index edcbfac..568ae5e 100644 --- a/doc_source/examples-ec2-regions-zones.rst +++ b/doc_source/examples-ec2-regions-zones.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,9 +8,9 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -#################################### -Using Regions and Availability Zones -#################################### +################################## +Use regions and availability zones +################################## .. meta:: :description: How to list EC2 regions and availability zones using the AWS SDK for Java. @@ -18,58 +18,88 @@ Using Regions and Availability Zones zones, describe availability zones -Describing Regions -================== +Describe regions +================ -To list the regions available to your account, call the |ec2client|'s :methodname:`describeRegions` +To list the Regions available to your account, call the |ec2client|'s :methodname:`describeRegions` method. It returns a :aws-java-class:`DescribeRegionsResult `. Call the returned object's :methodname:`getRegions` method to get a list of :aws-java-class:`Region ` objects that represent -each region. +each Region. **Imports** -.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java - :lines: 16-19 +.. literalinclude:: ec2.java1.describe_region_and_zones.import.txt :language: java **Code** -.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java - :lines: 30-40 +.. literalinclude:: ec2.java1.describe_region_and_zones.regions.txt :dedent: 8 :language: java See the :sdk-examples-java-ec2:`complete example `. -Describing Availability Zones -============================= +Describe availability zones +=========================== -To list each availability zone available to your account, call the |ec2client|'s +To list each Availability Zone available to your account, call the |ec2client|'s :methodname:`describeAvailabilityZones` method. It returns a :aws-java-class:`DescribeAvailabilityZonesResult `. Call its :methodname:`getAvailabilityZones` method to get a list of :aws-java-class:`AvailabilityZone ` -objects that represent each availability zone. +objects that represent each Availability Zone. **Imports** -.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java - :lines: 16-19 +.. literalinclude:: ec2.java1.describe_region_and_zones.import.txt :language: java **Code** -.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java - :lines: 42-53 +.. literalinclude:: ec2.java1.describe_region_and_zones.zones.txt :dedent: 8 :language: java See the :sdk-examples-java-ec2:`complete example `. +Describe accounts +================= + +To describe your account, call the |ec2client|'s :methodname:`describeAccountAttributes` +method. This method returns a +:aws-java-class:`DescribeAccountAttributesResult ` +object. +Invoke this objects :methodname:`getAccountAttributes` method to get a list of +:aws-java-class:`AccountAttribute ` objects. You can iterate +through the list to retrieve an +:aws-java-class:`AccountAttribute ` object. + +You can get your account's attribute values by invoking the +:aws-java-class:`AccountAttribute ` object's +:methodname:`getAttributeValues` method. This method returns a list of +:aws-java-class:`AccountAttributeValue ` objects. You can +iterate through this second list to display the value of attributes (see the following code +example). + +**Imports** + +.. literalinclude:: ec2.java1.describe_account.import.txt + :language: java + +**Code** + +.. literalinclude:: ec2.java1.describe_account.main.txt + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example ` on GitHub. + + + -More Information +More information ================ * :ec2-ug:`Regions and Availability Zones ` in the |ec2-ug| diff --git a/doc_source/examples-ec2-security-groups.rst b/doc_source/examples-ec2-security-groups.rst index f39735f..7900120 100644 --- a/doc_source/examples-ec2-security-groups.rst +++ b/doc_source/examples-ec2-security-groups.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-iam-access-keys.rst b/doc_source/examples-iam-access-keys.rst index 2d0a085..fd904e2 100644 --- a/doc_source/examples-iam-access-keys.rst +++ b/doc_source/examples-iam-access-keys.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-iam-account-aliases.rst b/doc_source/examples-iam-account-aliases.rst index f83f041..d94f774 100644 --- a/doc_source/examples-iam-account-aliases.rst +++ b/doc_source/examples-iam-account-aliases.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-iam-policies.rst b/doc_source/examples-iam-policies.rst index 7d0684d..b2ab3b2 100644 --- a/doc_source/examples-iam-policies.rst +++ b/doc_source/examples-iam-policies.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-iam-server-certificates.rst b/doc_source/examples-iam-server-certificates.rst index 4c4cd98..93f3be4 100644 --- a/doc_source/examples-iam-server-certificates.rst +++ b/doc_source/examples-iam-server-certificates.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-iam-users.rst b/doc_source/examples-iam-users.rst index ca38475..e12eee4 100644 --- a/doc_source/examples-iam-users.rst +++ b/doc_source/examples-iam-users.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-iam.rst b/doc_source/examples-iam.rst index a393205..46500e3 100644 --- a/doc_source/examples-iam.rst +++ b/doc_source/examples-iam.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -16,7 +16,7 @@ :description: Programming AWS Identity and Access Management using the AWS SDK for Java :keywords: AWS SDK for Java code examples, IAM -This section provides examples of programming |iam|_ using the |sdk-java|_. +This section provides examples of programming |iam|_ by using the |sdk-java|_. .. include:: common/desc-iam.txt diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst new file mode 100644 index 0000000..e524d4d --- /dev/null +++ b/doc_source/examples-lambda.rst @@ -0,0 +1,110 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +################################################# +Invoking, Listing, and Deleting Lambda Functions +################################################# + +.. meta:: + :description: How to invoke, list, and delete a Lambda function by using the AWS SDK for Java 2.x. + :keywords: Amazon Lambda, AWS SDK for Java 2.x, Lambda code examples, + deleteFunction, invoke, listFunctions + + +This section provides examples of programming with the Lambda service client by using the AWS SDK for Java. To learn how to +create a Lambda function, see `How to Create AWS Lambda functions `_. + +.. contents:: + :local: + :depth: 1 + +.. _invoke-function: +Invoke a Lambda function +======================== + +You can invoke a Lambda function by creating an :aws-java-class:`AWSLambda ` +object and invoking its :methodname:`invoke` method. Create an :aws-java-class:`InvokeRequest ` +object to specify additional information such as the function name and the payload to pass to the Lambda function. Function names +appear as *arn:aws:lambda:us-west-2:555556330391:function:HelloFunction*. You can retrieve the value by looking at the function in the AWS Console. + +To pass payload data to a function, invoke the :aws-java-class:`InvokeRequest ` +object's :methodname:`withPayload` method and specify a String in JSON format, as shown in the following code example. + +**Imports** + +.. literalinclude:: lambda.java1.invoke.import.txt + :language: java + +**Code** + +The following code example demonstrates how to invoke a Lambda function. + +.. literalinclude:: lambda.java1.invoke.main.txt + :language: java + +See the complete example on `Github +`_. + + +.. _list-function: + +List Lambda functions +===================== + +Build an :aws-java-class:`AWSLambda ` +object and invoke its :methodname:`listFunctions` method. +This method returns a :aws-java-class:`ListFunctionsResult ` object. +You can invoke this object's :methodname:`getFunctions` method to return a list of :aws-java-class:`FunctionConfiguration ` objects. +You can iterate through the list to retrieve information about the functions. For example, the following Java code example shows how to get each function name. + + +**Imports** + +.. literalinclude:: lambda.java1.list.import.txt + :language: java + +**Code** + +The following Java code example demonstrates how to retrieve a list of Lambda function names. + +.. literalinclude:: lambda.java1.list.main.txt + :language: java + +See the complete example on `Github +`_. + + +.. _delete-function: + +Delete a Lambda function +======================== + +Build an :aws-java-class:`AWSLambda ` +object and invoke its :methodname:`deleteFunction` method. +Create a :aws-java-class:`DeleteFunctionRequest ` +object and pass it to the :methodname:`deleteFunction` method. This object contains information such as the name of the function to delete. +Function names appear as *arn:aws:lambda:us-west-2:555556330391:function:HelloFunction*. You can retrieve the value by looking at the function in the AWS Console. + +**Imports** + +.. literalinclude:: lambda.java1.delete.import.txt + :language: java + +**Code** + +The following Java code demonstrates how to delete a Lambda function. + +.. literalinclude:: lambda.java1.delete.main.txt + :language: java + +See the complete example on `Github +`_. + + diff --git a/doc_source/examples-pinpoint-create-app.rst b/doc_source/examples-pinpoint-create-app.rst new file mode 100644 index 0000000..727f7c8 --- /dev/null +++ b/doc_source/examples-pinpoint-create-app.rst @@ -0,0 +1,72 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +####################################### +Creating and Deleting Apps in |PINlong| +####################################### + +.. meta:: + :description: How to create or delete an app in Amazon pinpoint. + :keywords: AWS for Java SDK code examples, amazon pinpoint + +An app is an |PINlong| project in which you define the audience for a distinct +application, and you engage this audience with tailored messages. The examples on +this page demonstrate how to create a new app or delete an existing one. + +Create an App +============= + +Create a new app in |PINlong| by providing an app name to the :aws-java-class:`CreateAppRequest +` object, and then passing that object to the +|pinpointclient|'s :methodname:`createApp` method. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateApp.java + :lines: 17-21 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateApp.java + :lines: 44-49 + :dedent: 2 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + + +Delete an App +============= + +To delete an app, call the |pinpointclient|'s :methodname:`deleteApp` request with a +:aws-java-class:`DeleteAppRequest ` object that's +set with the app name to delete. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/DeleteApp.java + :lines: 18-19 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/DeleteApp.java + :lines: 42-45 + :dedent: 2 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + +More Information +================ + +* :pin-api:`Apps ` in the |PIN-api| +* :pin-api:`App ` in the |PIN-api| diff --git a/doc_source/examples-pinpoint-create-campaign.rst b/doc_source/examples-pinpoint-create-campaign.rst new file mode 100644 index 0000000..c7548b4 --- /dev/null +++ b/doc_source/examples-pinpoint-create-campaign.rst @@ -0,0 +1,68 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################### +Creating Campaigns in |PINlong| +############################### + +.. meta:: + :description: How to create a campaign in Amazon pinpoint. + :keywords: AWS for Java SDK code examples, amazon pinpoint campaign + +You can use campaigns to help increase engagement between your app and your users. +You can create a campaign to reach out to a particular segment of your users with tailored +messages or special promotions. This example demonstrates how to create a new +standard campaign that sends a custom push notification to a specified segment. + +Create a Campaign +================= + +Before creating a new campaign, you must define a :aws-java-class:`Schedule +` and a :aws-java-class:`Message +` and set these values in a +:aws-java-class:`WriteCampaignRequest ` object. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateCampaign.java + :lines: 18-27 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateCampaign.java + :lines: 53-69 + :dedent: 8 + :language: java + +Then create a new campaign in |PINlong| by providing the :aws-java-class:`WriteCampaignRequest +` with the campaign configuration to a +:aws-java-class:`CreateCampaignRequest` object. Finally, pass the CreateCampaignRequest object to the +|pinpointclient|'s :methodname:`createCampaign` method. + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateCampaign.java + :lines: 71-74 + :dedent: 8 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + +More Information +================ + +* :pin-ug:`Amazon Pinpoint Campaigns ` in the |pin-ug| +* :pin-dg:`Creating Campaigns ` in the |pin-dg| +* :pin-api:`Campaigns ` in the |pin-api| +* :pin-api:`Campaign ` in the |pin-api| +* :pin-api:`Campaign Activities ` in the |pin-api| +* :pin-api:`Campaign Versions ` in the |pin-api| +* :pin-api:`Campaign Version ` in the |pin-api| diff --git a/doc_source/examples-pinpoint-create-endpoint.rst b/doc_source/examples-pinpoint-create-endpoint.rst new file mode 100644 index 0000000..5193644 --- /dev/null +++ b/doc_source/examples-pinpoint-create-endpoint.rst @@ -0,0 +1,62 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################### +Creating Endpoints in |PINlong| +############################### + +.. meta:: + :description: How to update an app endpoint in Amazon pinpoint. + :keywords: AWS for Java SDK code examples, amazon pinpoint endpoint + +An endpoint uniquely identifies a user device to which you can send +push notifications with |PINlong|. If your app is enabled with |PINlong| +support, your app automatically registers an endpoint with |PINlong| +when a new user opens your app. The following example demonstrates how to +add a new endpoint programmatically. + +Create an Endpoint +================== + +Create a new endpoint in |PINlong| by providing the endpoint data in an +:aws-java-class:`EndpointRequest ` object. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateEndpoint.java + :lines: 18-28 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateEndpoint.java + :lines: 92-136 + :dedent: 8 + :language: java + +Then create an :aws-java-class:`UpdateEndpointRequest ` +object with that EndpointRequest object. Finally, pass the UpdateEndpointRequest object to the +|pinpointclient|'s :methodname:`updateEndpoint` method. + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateEndpoint.java + :lines: 73-79 + :dedent: 8 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + + +More Information +================ + +* :pin-dg:`Adding Endpoint ` in the |pin-dg| +* :pin-api:`Endpoint ` in the |pin-api| diff --git a/doc_source/examples-pinpoint-create-segment.rst b/doc_source/examples-pinpoint-create-segment.rst new file mode 100644 index 0000000..90f3175 --- /dev/null +++ b/doc_source/examples-pinpoint-create-segment.rst @@ -0,0 +1,64 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################## +Creating Segments in |PINlong| +############################## + +.. meta:: + :description: How to update an app segment in Amazon pinpoint. + :keywords: AWS for Java SDK code examples, amazon pinpoint segment + +A user segment represents a subset of your users that's based on shared characteristics, such as +how recently a user opened your app or which device they use. The following example demonstrates +how to define a segment of users. + +Create a Segment +================ + +Create a new segment in |PINlong| by defining dimensions of the segment in a +:aws-java-class:`SegmentDimensions ` object. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateSegment.java + :lines: 18-30 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateSegment.java + :lines: 50, 58-74 + :dedent: 8 + :language: java + +Next set the :aws-java-class:`SegmentDimensions ` +object in a :aws-java-class:`WriteSegmentRequest +`, which in turn is used to create a +:aws-java-class:`CreateSegmentRequest ` object. +Then pass the CreateSegmentRequest object to the +|pinpointclient|'s :methodname:`createSegment` method. + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateSegment.java + :lines: 76-82 + :dedent: 8 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + +More Information +================ + +* :pin-ug:`Amazon Pinpoint Segments ` in the |pin-ug| +* :pin-dg:`Creating Segments ` in the |pin-dg| +* :pin-api:`Segments ` in the |pin-api| +* :pin-api:`Segment ` in the |pin-api| diff --git a/doc_source/examples-pinpoint-update-channel.rst b/doc_source/examples-pinpoint-update-channel.rst new file mode 100644 index 0000000..c27a545 --- /dev/null +++ b/doc_source/examples-pinpoint-update-channel.rst @@ -0,0 +1,60 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################## +Updating Channels in |PINlong| +############################## + +.. meta:: + :description: How to update an app channel in Amazon pinpoint. + :keywords: AWS for Java SDK code examples, amazon pinpoint channel + +A channel defines the types of platforms to which you can deliver messages. +This example shows how to use the APNs channel to send a message. + +Update a Channel +================ + +Enable a channel in |PINlong| by providing an app ID and a request object of the channel type +you want to update. This example updates the APNs channel, which requires the +:aws-java-class:`APNSChannelRequest ` object. +Set these in the :aws-java-class:`UpdateApnsChannelRequest ` +and pass that object to the +|pinpointclient|'s :methodname:`updateApnsChannel` method. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/UpdateChannel.java + :lines: 18-25 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/UpdateChannel.java + :lines: 66-72 + :dedent: 2 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + + +More Information +================ + +* :pin-ug:`Amazon Pinpoint Channels ` in the |pin-ug| +* :pin-api:`ADM Channel ` in the |pin-api| +* :pin-api:`APNs Channel ` in the |pin-api| +* :pin-api:`APNs Sandbox Channel ` in the |pin-api| +* :pin-api:`APNs VoIP Channel ` in the |pin-api| +* :pin-api:`APNs VoIP Sandbox Channel ` in the |pin-api| +* :pin-api:`Baidu Channel ` in the |pin-api| +* :pin-api:`Email Channel ` in the |pin-api| +* :pin-api:`GCM Channel ` in the |pin-api| +* :pin-api:`SMS Channel ` in the |pin-api| diff --git a/doc_source/examples-pinpoint.rst b/doc_source/examples-pinpoint.rst new file mode 100644 index 0000000..a377c49 --- /dev/null +++ b/doc_source/examples-pinpoint.rst @@ -0,0 +1,31 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +####################################### +|PINlong| Examples Using the |sdk-java| +####################################### + +.. meta:: + :description: Programming Amazon Pinpoint using the AWS SDK for Java + :keywords: AWS SDK for Java code examples + +This section provides examples of programming |PINLong|_ using the |sdk-java|_. + +.. include:: includes/complete-examples-note.txt + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + examples-pinpoint-create-app + examples-pinpoint-create-endpoint + examples-pinpoint-create-segment + examples-pinpoint-create-campaign + examples-pinpoint-update-channel diff --git a/doc_source/examples-s3-access-permissions.rst b/doc_source/examples-s3-access-permissions.rst index 64d39e2..892996d 100644 --- a/doc_source/examples-s3-access-permissions.rst +++ b/doc_source/examples-s3-access-permissions.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-s3-bucket-policies.rst b/doc_source/examples-s3-bucket-policies.rst index 25b788c..f8b8e0c 100644 --- a/doc_source/examples-s3-bucket-policies.rst +++ b/doc_source/examples-s3-bucket-policies.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -41,7 +41,7 @@ You can set the bucket policy for a particular S3 bucket by: .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetBucketPolicy.java :dedent: 8 - :lines: 81-88 + :lines: 81-86 :language: java diff --git a/doc_source/examples-s3-buckets.rst b/doc_source/examples-s3-buckets.rst index d2a1c3a..91afff7 100644 --- a/doc_source/examples-s3-buckets.rst +++ b/doc_source/examples-s3-buckets.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -42,19 +42,18 @@ exception if the bucket already exists. **Imports** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/CreateBucket.java - :lines: 15-19 + :lines: 16-22 :language: java **Code** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/CreateBucket.java - :lines: 42-54 + :lines: 46-56 :dedent: 8 :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. - .. _list-buckets: List Buckets @@ -66,19 +65,18 @@ Use the |s3client| client's :methodname:`listBucket` method. If successful, a li **Imports** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/ListBuckets.java - :lines: 15-19 + :lines: 16-21 :language: java **Code** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/ListBuckets.java - :lines: 30-36 + :lines: 32-36 :dedent: 8 :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. - .. _delete-bucket: Delete a Bucket @@ -104,14 +102,14 @@ delete each one. **Imports** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java - :lines: 15-17, 19-20, 23 + :lines: 16-22 :language: java **Code** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java - :lines: 51, 53-70, 94-97 - :dedent: 8 + :lines: 50-66 + :dedent: 12 :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. @@ -130,19 +128,18 @@ objects, and then :methodname:`deleteVersion` to delete each one. **Imports** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java - :lines: 15-23 + :lines: 16-22 :language: java **Code** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java - :lines: 51, 53-90, 94-97 - :dedent: 8 + :lines: 68-86 + :dedent: 12 :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. - Delete an Empty Bucket ---------------------- @@ -152,14 +149,14 @@ bucket itself by using the |s3client| client's :methodname:`deleteBucket` method **Imports** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java - :lines: 15-17 + :lines: 16-22 :language: java **Code** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java - :lines: 51, 53, 93-97 - :dedent: 8 + :lines: 88-89 + :dedent: 12 :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. diff --git a/doc_source/examples-s3-objects.rst b/doc_source/examples-s3-objects.rst index 4a398ef..2cff970 100644 --- a/doc_source/examples-s3-objects.rst +++ b/doc_source/examples-s3-objects.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -39,13 +39,13 @@ name, and file to upload. *The bucket must exist, or an error will result*. **Imports** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/PutObject.java - :lines: 15-17 + :lines: 15-18 :language: java **Code** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/PutObject.java - :lines: 46-52 + :lines: 46-53 :dedent: 8 :language: java @@ -121,7 +121,7 @@ Copy, Move, or Rename Objects You can copy an object from one bucket to another by using the |s3client| client's :methodname:`copyObject` method. It takes the name of the bucket to copy from, the object to copy, -and the destination bucket and name. +and the destination bucket name. **Imports** @@ -132,7 +132,7 @@ and the destination bucket and name. **Code** .. literalinclude:: example_code/s3/src/main/java/aws/example/s3/CopyObject.java - :lines: 46-52 + :lines: 48-64 :dedent: 8 :language: java diff --git a/doc_source/examples-s3-transfermanager.rst b/doc_source/examples-s3-transfermanager.rst index 850baf3..a3e62e7 100644 --- a/doc_source/examples-s3-transfermanager.rst +++ b/doc_source/examples-s3-transfermanager.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -45,22 +45,20 @@ Upload Files and Directories Upload a Single File -------------------- -Call the |xfermgr| :methodname:`upload` method, providing an |S3| +Call |xfermgr|'s :methodname:`upload` method, providing an |S3| bucket name, a key (object) name, and a standard Java :javase-ref:`File ` object that represents the file to upload. **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java - :lines: 16-18, 20 +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.import.txt :language: java **Code** .. uploadFile() method in the example code... -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java - :lines: 93-97, 99, 101-105 +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.single.txt :dedent: 8 :language: java @@ -90,16 +88,14 @@ providing the following: **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java - :lines: 16-17, 19-21 +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.import.txt :language: java **Code** .. uploadFileList() method in the example code... -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java - :lines: 60-69, 71, 73-77 +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.list_of_files.txt :dedent: 8 :language: java @@ -123,16 +119,14 @@ recursively (*true* or *false*). **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java - :lines: 16-20 +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.import.txt :language: java **Code** .. uploadDir() method in the example code... -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java - :lines: 38-42, 44, 46-50 +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.directory.txt :dedent: 8 :language: java @@ -167,16 +161,14 @@ Use the |xfermgr|'s :methodname:`download` method, providing the **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrDownload.java - :lines: 16-18, 20 +.. literalinclude:: s3.java1.s3_xfer_mgr_download.import.txt :language: java **Code** .. downloadFile() method in the example code... -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrDownload.java - :lines: 57-61, 63, 65-69 +.. literalinclude:: s3.java1.s3_xfer_mgr_download.single.txt :dedent: 8 :language: java @@ -198,16 +190,14 @@ into on your local system. If the named directory doesn't exist yet, it will be **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrDownload.java - :lines: 16-17, 19-20 +.. literalinclude:: s3.java1.s3_xfer_mgr_download.import.txt :language: java **Code** .. downloadFile() method in the example code... -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrDownload.java - :lines: 36-40, 42, 44-48 +.. literalinclude:: s3.java1.s3_xfer_mgr_download.directory.txt :dedent: 8 :language: java @@ -225,16 +215,14 @@ To copy an object from one S3 bucket to another, use the |xfermgr| :methodname:` **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrCopy.java - :lines: 16-18 +.. literalinclude:: s3.java1.s3_xfer_mgr_copy.import.txt :language: java **Code** .. copyObjectSimple() method in the example code... -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrCopy.java - :lines: 35-38, 40, 42-46 +.. literalinclude:: s3.java1.s3_xfer_mgr_copy.copy_object.txt :dedent: 8 :language: java @@ -253,8 +241,7 @@ occurs. .. the waitForCompletion() function in XferMgrProgress.java -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java - :lines: 34-45 +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.wait_for_transfer.txt :dedent: 8 :language: java @@ -317,16 +304,14 @@ prints its final state. **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java - :lines: 22 +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.import.txt :language: java **Code** .. the showTransferProgress() function in XferMgrProgress.java -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java - :lines: 56-61, 64-67, 70 +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.poll.txt :dedent: 8 :language: java @@ -350,16 +335,14 @@ object. You can use the object to get the total bytes of the operation by callin **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java - :lines: 16-18, 23, 25 +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.import.txt :language: java **Code** .. the uploadFileWithListener() function in XferMgrProgress.java -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java - :lines: 146-149, 152-154, 157-159, 162-168 +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.progress_listener.txt :dedent: 8 :language: java @@ -379,16 +362,14 @@ subtransfer. **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java - :lines: 23-24, 26-27 +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.import.txt :language: java **Code** .. the showMultiUploadProgress() function in XferMgrProgress.java -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java - :lines: 82-83 +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.substranferes.txt :dedent: 8 :language: java diff --git a/doc_source/examples-s3-website-configuration.rst b/doc_source/examples-s3-website-configuration.rst index da8e3f7..2b31a3c 100644 --- a/doc_source/examples-s3-website-configuration.rst +++ b/doc_source/examples-s3-website-configuration.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -33,15 +33,13 @@ Setting an index document is *required*; all other parameters are optional. **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetWebsiteConfiguration.java - :lines: 15-18 +.. literalinclude:: s3.java1.s3_set_website_config.import.txt :language: java **Code** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetWebsiteConfiguration.java +.. literalinclude:: s3.java1.s3_set_website_config.main.txt :dedent: 8 - :lines: 31-50 :language: java .. note:: Setting a website configuration does not modify the access permissions for your bucket. @@ -65,15 +63,13 @@ bucket, then :code-java:`null` will be returned. **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/GetWebsiteConfiguration.java - :lines: 15-18 +.. literalinclude:: s3.java1.s3_get_website_config.import.txt :language: java **Code** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/GetWebsiteConfiguration.java +.. literalinclude:: s3.java1.s3_get_website_config.main.txt :dedent: 8 - :lines: 30-46 :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. @@ -88,15 +84,13 @@ configuration from. **Imports** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteWebsiteConfiguration.java - :lines: 15-17 +.. literalinclude:: s3.java1.s3_delete_website_config.import.txt :language: java **Code** -.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteWebsiteConfiguration.java +.. literalinclude:: s3.java1.s3_delete_website_config.main.txt :dedent: 8 - :lines: 29-36 :language: java See the :sdk-examples-java-s3:`complete example ` on GitHub. diff --git a/doc_source/examples-s3.rst b/doc_source/examples-s3.rst index e019f0a..1569a2e 100644 --- a/doc_source/examples-s3.rst +++ b/doc_source/examples-s3.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-sqs-dead-letter-queues.rst b/doc_source/examples-sqs-dead-letter-queues.rst index 56258a5..702dde3 100644 --- a/doc_source/examples-sqs-dead-letter-queues.rst +++ b/doc_source/examples-sqs-dead-letter-queues.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-sqs-long-polling.rst b/doc_source/examples-sqs-long-polling.rst index ef95f91..f3b6dfe 100644 --- a/doc_source/examples-sqs-long-polling.rst +++ b/doc_source/examples-sqs-long-polling.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-sqs-message-queues.rst b/doc_source/examples-sqs-message-queues.rst index 74622ac..f426f18 100644 --- a/doc_source/examples-sqs-message-queues.rst +++ b/doc_source/examples-sqs-message-queues.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-sqs-messages.rst b/doc_source/examples-sqs-messages.rst index 630bef8..d4427c9 100644 --- a/doc_source/examples-sqs-messages.rst +++ b/doc_source/examples-sqs-messages.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -45,6 +45,7 @@ Add a single message to an |SQS| queue by calling the |sqsclient| client's :dedent: 8 :language: java +See the :sdk-examples-java-sqs:`complete example ` on GitHub. .. _sqs-messages-send-multiple: diff --git a/doc_source/examples-sqs-visibility-timeout.rst b/doc_source/examples-sqs-visibility-timeout.rst index c843f82..12f70ce 100644 --- a/doc_source/examples-sqs-visibility-timeout.rst +++ b/doc_source/examples-sqs-visibility-timeout.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/examples-sqs.rst b/doc_source/examples-sqs.rst index b1a36c5..780e0d3 100644 --- a/doc_source/examples-sqs.rst +++ b/doc_source/examples-sqs.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/generating-sdk-metrics.rst b/doc_source/generating-sdk-metrics.rst old mode 100644 new mode 100755 index 7291c92..3c25c58 --- a/doc_source/generating-sdk-metrics.rst +++ b/doc_source/generating-sdk-metrics.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,6 +8,10 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. +.. |CSMlong| replace:: AWS SDK Metrics for Enterprise Support +.. |CSM| replace:: SDK Metrics + + ################################### Enabling Metrics for the |sdk-java| ################################### @@ -18,10 +22,15 @@ The |sdk-java| can generate metrics for visualization and monitoring with |cw|_ * the performance of your JVMs when used with AWS * runtime environment details such as heap memory, number of threads, and opened file descriptors -How to Enable SDK Metric Generation -=================================== +.. note:: The |CSMlong| is another option for gathering metrics about your application. + |CSM| is an |AWS| service that publishes data to |CWlong| and enables you to share metric data with AWS Support + for easier troubleshooting. See :doc:`sdk-metrics` to learn how to enable the |CSM| + service for your application. + +How to Enable |sdk-java| Metric Generation +========================================== -SDK metrics are *disabled by default*. To enable it for your local development environment, include +|sdk-java| metrics are *disabled by default*. To enable it for your local development environment, include a system property that points to your AWS security credential file when starting up the JVM. For example:: @@ -83,3 +92,6 @@ More Information * Learn about working with |cw| using the |sdk-java| in :doc:`examples-cloudwatch`. +* Learn more about performance tuning in + :blog:`Tuning the AWS SDK for Java to Improve Resiliency ` + blog post. diff --git a/doc_source/getting-started.rst b/doc_source/getting-started.rst old mode 100644 new mode 100755 index 0ebc0f9..738611c --- a/doc_source/getting-started.rst +++ b/doc_source/getting-started.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -23,4 +23,4 @@ This section provides information about how to install, set up, and use the |sdk setup-credentials setup-project-maven setup-project-gradle - + sdk-metrics diff --git a/doc_source/how-to-ec2.rst b/doc_source/how-to-ec2.rst index 003969c..01b4ee4 100644 --- a/doc_source/how-to-ec2.rst +++ b/doc_source/how-to-ec2.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/includes/complete-examples-note.txt b/doc_source/includes/complete-examples-note.txt index 8e285b1..fbc491a 100644 --- a/doc_source/includes/complete-examples-note.txt +++ b/doc_source/includes/complete-examples-note.txt @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/includes/examples-note.txt b/doc_source/includes/examples-note.txt index 0f103f9..3f12239 100644 --- a/doc_source/includes/examples-note.txt +++ b/doc_source/includes/examples-note.txt @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/includes/transfermanager-complete-get-status-note.txt b/doc_source/includes/transfermanager-complete-get-status-note.txt index aaabba0..45986d5 100644 --- a/doc_source/includes/transfermanager-complete-get-status-note.txt +++ b/doc_source/includes/transfermanager-complete-get-status-note.txt @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/includes/transfermanager-multifileupload-notes.txt b/doc_source/includes/transfermanager-multifileupload-notes.txt index 61665a5..0816464 100644 --- a/doc_source/includes/transfermanager-multifileupload-notes.txt +++ b/doc_source/includes/transfermanager-multifileupload-notes.txt @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/index.rst b/doc_source/index.rst index c61b046..59814c8 100644 --- a/doc_source/index.rst +++ b/doc_source/index.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -13,7 +13,7 @@ ########## .. meta:: - :description: Developer Guide for the AWS SDK for Java + :description: Describes the various features of the SDK and how to use them. :keywords: java, sdk, aws .. toctree:: @@ -24,6 +24,7 @@ getting-started basics Code Examples + Security document-history .. include:: about-aws.txt diff --git a/doc_source/infrastructure-security.rst b/doc_source/infrastructure-security.rst new file mode 100644 index 0000000..10e994e --- /dev/null +++ b/doc_source/infrastructure-security.rst @@ -0,0 +1,12 @@ +Infrastructure Security for this AWS Product or Service +======================================================= + +This AWS product or service follows the `shared responsibility +model `__ +through the specific Amazon Web Services (AWS) services it supports. For +AWS service security information, see the `AWS service security +documentation +page `__ +and `AWS services that are in scope of AWS compliance efforts by +compliance +program `__. diff --git a/doc_source/java-dg-access-control.rst b/doc_source/java-dg-access-control.rst index 7cc94fc..f07454c 100644 --- a/doc_source/java-dg-access-control.rst +++ b/doc_source/java-dg-access-control.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/java-dg-exceptions.rst b/doc_source/java-dg-exceptions.rst index 531c2ad..1e27af6 100644 --- a/doc_source/java-dg-exceptions.rst +++ b/doc_source/java-dg-exceptions.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/java-dg-jvm-ttl.rst b/doc_source/java-dg-jvm-ttl.rst index 66d01bd..273436a 100644 --- a/doc_source/java-dg-jvm-ttl.rst +++ b/doc_source/java-dg-jvm-ttl.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/java-dg-logging.rst b/doc_source/java-dg-logging.rst index 87075d9..67784b7 100644 --- a/doc_source/java-dg-logging.rst +++ b/doc_source/java-dg-logging.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -62,7 +62,8 @@ Setting the Classpath Both the Log4j JAR and the log4j.properties file must be located on your classpath. If you're using `Apache Ant `_, set the classpath in the :code:`path` element in your -Ant file. The following example shows a path element from the Ant file for the |S3| example included +Ant file. The following example shows a path element from the Ant file for the +|S3| `example `_ included with the SDK. .. code-block:: xml @@ -179,3 +180,36 @@ application. log4j.logger.org.apache.http.wire=DEBUG +.. _sdk-latency-logging: + +Latency Metrics Logging +======================= + +If you are troubleshooting and want to see metrics such as which process is taking the most time +or whether server or client side has the greater latency, the latency logger can be helpful. +Set the :code:`com.amazonaws.latency` logger to DEBUG to enable this logger. + +.. note:: + + This logger is only available if SDK metrics is enabled. + To learn more about the SDK metrics package, see :doc:`generating-sdk-metrics`. + +.. code-block:: properties + + log4j.rootLogger=WARN, A1 + log4j.appender.A1=org.apache.log4j.ConsoleAppender + log4j.appender.A1.layout=org.apache.log4j.PatternLayout + log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n + log4j.logger.com.amazonaws.latency=DEBUG + +Here is an example of the log output. + +.. code-block:: none + + com.amazonaws.latency - ServiceName=[Amazon S3], StatusCode=[200], + ServiceEndpoint=[https://list-objects-integ-test-test.s3.amazonaws.com], + RequestType=[ListObjectsV2Request], AWSRequestID=[REQUESTID], HttpClientPoolPendingCount=0, + RetryCapacityConsumed=0, HttpClientPoolAvailableCount=0, RequestCount=1, + HttpClientPoolLeasedCount=0, ResponseProcessingTime=[52.154], ClientExecuteTime=[487.041], + HttpClientSendRequestTime=[192.931], HttpRequestTime=[431.652], RequestSigningTime=[0.357], + CredentialsRequestTime=[0.011, 0.001], HttpClientReceiveResponseTime=[146.272] diff --git a/doc_source/java-dg-region-selection.rst b/doc_source/java-dg-region-selection.rst index 6e6d053..e6a1ae0 100644 --- a/doc_source/java-dg-region-selection.rst +++ b/doc_source/java-dg-region-selection.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -79,14 +79,19 @@ Choosing a Specific Endpoint ============================ Each AWS client can be configured to use a *specific endpoint* within a region by calling the -:methodname:`setEndpoint` method. +:methodname:`withEndpointConfiguration` method when creating the client. -For example, to configure the |EC2| client to use the |euwest1-name|, use the following code. +For example, to configure the |S3| client to use the |euwest1-name|, use the following code. :: - AmazonEC2 ec2 = new AmazonEC2(myCredentials); - ec2.setEndpoint("https://ec2.eu-west-1.amazonaws.com"); + AmazonS3 s3 = AmazonS3ClientBuilder.standard() + .withEndpointConfiguration(new EndpointConfiguration( + "https://s3.eu-west-1.amazonaws.com", + "eu-west-1")) + .withCredentials(CREDENTIALS_PROVIDER) + .build(); + See |regions-and-endpoints|_ for the current list of regions and their corresponding endpoints for all AWS services. diff --git a/doc_source/java-dg-roles.rst b/doc_source/java-dg-roles.rst index e2380b3..82f1fec 100644 --- a/doc_source/java-dg-roles.rst +++ b/doc_source/java-dg-roles.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -29,16 +29,20 @@ The default provider chain and EC2 instance profiles If your application creates an AWS client using the default constructor, then the client will search for credentials using the :emphasis:`default credentials provider chain`, in the following order: -1. In system environment variables: :code:`AWS_ACCESS_KEY_ID` and :code:`AWS_SECRET_ACCESS_KEY`. +1. In the Java system properties: :code:`aws.accessKeyId` and :code:`aws.secretKey`. -2. In the Java system properties: :code:`aws.accessKeyId` and :code:`aws.secretKey`. +2. In system environment variables: :code:`AWS_ACCESS_KEY_ID` and :code:`AWS_SECRET_ACCESS_KEY`. 3. In the default credentials file (the location of this file varies by platform). -4. In the :emphasis:`instance profile credentials`, which exist within the instance metadata +4. Credentials delivered through the Amazon EC2 container service if the :code:`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` environment variable is set and security manager has permission to access the variable. + +5. In the :emphasis:`instance profile credentials`, which exist within the instance metadata associated with the IAM role for the EC2 instance. -The final step in the default provider chain is available only when running your application on an +6. Web Identity Token credentials from the environment or container. + +The :emphasis:`instance profile credentials` step in the default provider chain is available only when running your application on an |EC2| instance, but provides the greatest ease of use and best security when working with |EC2| instances. You can also pass an :aws-java-class:`InstanceProfileCredentialsProvider ` instance directly to the client constructor to get diff --git a/doc_source/java-dg-samples.rst b/doc_source/java-dg-samples.rst index b061253..343550d 100644 --- a/doc_source/java-dg-samples.rst +++ b/doc_source/java-dg-samples.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -9,7 +9,7 @@ limitations under the License. ####################### -|sdk-java| Code Samples +Code Samples included with the SDK ####################### The |sdk-java| comes packaged with code samples that demonstrate many of the features of diff --git a/doc_source/java-dg-tomcat-session-manager.rst b/doc_source/java-dg-tomcat-session-manager.rst deleted file mode 100644 index 1c73d0d..0000000 --- a/doc_source/java-dg-tomcat-session-manager.rst +++ /dev/null @@ -1,203 +0,0 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. - - This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 - International License (the "License"). You may not use this file except in compliance with the - License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. - - This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, - either express or implied. See the License for the specific language governing permissions and - limitations under the License. - -######################################## -Managing Tomcat Session State with |DDB| -######################################## - -.. meta:: - :description: How to configure Tomcat session states in DynamoDB. - :keywords: AWS for Java SDK code examples, Tomcat sessions states - - -Tomcat applications often store session-state data in memory. However, this approach doesn't scale -well because once the application grows beyond a single web server, the session state must be shared -among servers. A common solution is to set up a dedicated session-state server with MySQL. However, this -approach also has drawbacks: you must administer another server, the session-state server is a -single pointer of failure, and the MySQL server itself can cause performance problems. - -|DDB|, which is a NoSQL database store from AWS, avoids these drawbacks by providing -an effective solution for sharing session state across web servers. - -.. _java-dg-tomcat-sess-download: - -Download the Session Manager -============================ - -You can download the session manager from the `aws/aws-dynamodb-session-tomcat -`_ project on GitHub. This project also hosts -the session manager source code, so you can contribute to the project by sending us pull requests -or opening issues. - - -.. _java-dg-tomcat-sess-config-provider: - -Configure the Session-State Provider -==================================== - -To use the |DDB| session-state provider, you must do the following: - -1. Configure the Tomcat server to use the provider. -2. Set the security credentials of the provider so that it can access AWS. - -.. _java-dg-tomcat-sess-config-for-ddb: - -Configure a Tomcat Server to Use |DDB| as the Session-State Server ------------------------------------------------------------------- - -Copy :file:`AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar` to the :code:`lib` directory of your -Tomcat installation. :file:`AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar` is a complete, -standalone JAR that contains all the code and dependencies to run the |DDB| Tomcat Session Manager. - -Edit your server's :file:`context.xml` file to specify -:emphasis:`com.amazonaws.services.dynamodb.sessionmanager.DynamoDBSessionManager` as your session -manager. - -.. code-block:: java - - - - WEB-INF/web.xml - - - - -.. _java-dg-tomcat-sess-config-creds: - -Configure Your AWS Security Credentials ---------------------------------------- - -You can specify AWS security credentials for the session manager in multiple ways. They are -loaded in the following order of precedence: - -1. The :code:`AwsAccessKey` and :code:`AwsSecretKey` attributes of the :code:`Manager` element - explicitly provide credentials. - -2. The :code:`AwsCredentialsFile` attribute on the :code:`Manager` element specifies a properties - file from which to load credentials. - -If you don't specify credentials through the :code:`Manager` element, -:code:`DefaultAWSCredentialsProviderChain` continues searching for credentials in the following -order: - -1. Environment variables |ndash| :code:`AWS_ACCESS_KEY_ID` and :code:`AWS_SECRET_ACCESS_KEY` - -2. Java system properties |ndash| :code:`aws.accessKeyId` and :code:`aws.secretKey` - -3. Instance profile credentials delivered through the |EC2| instance metadata service (IMDS) - - -.. _java-dg-tomcat-sess-config-elb: - -Configure with |EB| -------------------- - -If you're using the session manager in |EB|, ensure your project has an -:file:`.ebextensions` directory at the top level of your output artifact structure. Put the following -files in :file:`.ebextensions` directory: - -* The :file:`AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar` file - -* A :file:`context.xml` file, described previously, to configure the session manager - -* A configuration file that copies the JAR into Tomcat's :file:`lib` directory and applies the overridden - :file:`context.xml` file. - -For more information about customizing |EB| environments, see -:eb-dg:`AWS Elastic Beanstalk Environment Configuration ` in the |EB-dg|. - -If you deploy to |EB| with the |tke|, you can have the toolkit set up the session manager -for you; use -the :guilabel:`New AWS Java Web Project` wizard and choose |DDB| for session management. The |tke| -configures the required files and puts them in the :file:`.ebextensions` directory in the -:file:`WebContent` directory of your project. If you have problems finding this directory, be sure -you aren't hiding files that begin with a period. - - -.. _java-dg-tomcat-sess-manage-with-ddb: - -Manage Tomcat Session State with |DDB| -====================================== - -If the Tomcat server is running on an |EC2| instance that is configured to use |IAM| roles for EC2 -instances, you don't need to specify any credentials in the :file:`context.xml` file. In this case, -the |sdk-java| uses |IAM| roles credentials obtained through the instance metadata service (IMDS). - -When your application starts, it looks for a |DDB| table named, by default, -:guilabel:`Tomcat_SessionState`. The table should have a string hash key named "sessionId" -(case-sensitive), no range key, and the desired values for :code:`ReadCapacityUnits` and -:code:`WriteCapacityUnits`. - -We recommend that you create this table before running your application for the first time. If you don't -create -the table, however, the extension creates it during initialization. See the :file:`context.xml` -options in the next section for a list of attributes that configure how the session-state table is -created when it doesn't exist. - -.. tip:: For information about working with |DDB| tables and provisioned throughput, see the - |DDB-dg|_. - -After the application is configured and the table is created, you can use sessions with any other -session provider. - - -.. _java-dg-tomcat-sess-option: - -Options Specified in context.xml -================================ - -You can use the following configuration attributes in the :code:`Manager` element of -your -:file:`context.xml` file: - -* :emphasis:`AwsAccessKey` |ndash| Access key ID to use. - -* :emphasis:`AwsSecretKey` |ndash| Secret key to use. -* :emphasis:`AwsCredentialsFile` |ndash| A properties file containing :code:`accessKey` and - :code:`secretKey` properties with your AWS security credentials. -* :emphasis:`Table` |ndash| Optional string attribute. The name of the table used to store session - data. The default is :guilabel:`Tomcat_SessionState`. -* :emphasis:`RegionId` |ndash| Optional string attribute. The AWS Region in which to use |DDB|. - For a list of available AWS Regions, see :aws-gr:`Regions and Endpoints ` in the |AWS-gr|. -* :emphasis:`Endpoint` |ndash| Optional string attribute that, if present, overrides any - value set for the :code:`Region` option. This attribute specifies the regional endpoint of the |DDB| - service to use. For a list of available AWS Regions, see :aws-gr:`Regions and Endpoints ` in |AWS-gr|. -* :emphasis:`ReadCapacityUnits` |ndash| Optional int attribute. The read capacity units to use if - the session manager creates the table. The default is 10. -* :emphasis:`WriteCapacityUnits` |ndash| Optional int attribute. The write capacity units to use - if the session manager creates the table. The default is 5. -* :emphasis:`CreateIfNotExist` |ndash| Optional Boolean attribute. The :code:`CreateIfNotExist` - attribute controls whether the session manager autocreates the table if it doesn't exist. The - default is true. If this flag is set to false and the table doesn't exist, an exception is - thrown during Tomcat startup. - - -.. _java-dg-tomcat-sess-troubleshooting: - -Troubleshooting -=============== - -If you encounter issues with the session manager, the first place to look is in -:file:`catalina.out`. If you have access to the Tomcat installation, you can go directly to this log -file and look for any error messages from the session manager. If you're using |EB|, you can view -the environment logs with the |console| or the |tke|. - - -.. _java-dg-tomcat-limits: - -Limitations -=========== - -The session manager doesn't support session locking. Therefore, applications that use many -concurrent AJAX calls to manipulate session data may not be appropriate for use with the session -manager, due to race conditions on session data writes and saves back to the data store. - - diff --git a/doc_source/examples-dynamodb-query-scan.rst b/doc_source/lambda-examples.rst similarity index 50% rename from doc_source/examples-dynamodb-query-scan.rst rename to doc_source/lambda-examples.rst index 4fc4edd..2687321 100644 --- a/doc_source/examples-dynamodb-query-scan.rst +++ b/doc_source/lambda-examples.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,17 +8,21 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -############################## -Querying and Scanning in |DDB| -############################## +########################################## +Lambda Examples Using the |sdk-java| +########################################## -In addition to using primary keys to access items, |DDB| also provides two operations for searching -your data: *Query* and *Scan*. +.. meta:: + :description: Programming Amazon Lambda using the AWS SDK for Java. + :keywords: AWS SDK for Java code examples -.. TODO +This section provides examples of programming Lambda using the |sdk-java|. -More Info -========= +.. include:: includes/complete-examples-note.txt -* :ddb-dg:`Guidelines for Query and Scan ` in the |ddb-dg| -* :ddb-dg:`Query and Scan Operations in DynamoDB ` in the |ddb-dg| +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Service Operations + diff --git a/doc_source/prog-services-ec2.rst b/doc_source/prog-services-ec2.rst index d3c9e38..8a2f7a9 100644 --- a/doc_source/prog-services-ec2.rst +++ b/doc_source/prog-services-ec2.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/prog-services-sts.rst b/doc_source/prog-services-sts.rst index 8423751..f82ecb5 100644 --- a/doc_source/prog-services-sts.rst +++ b/doc_source/prog-services-sts.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -66,25 +66,12 @@ Retrieve temporary security credentials from |STS| .. code-block:: java - AWSSecurityTokenServiceClient sts_client = new AWSSecurityTokenServiceClient(); + AWSSecurityTokenService sts_client = new AWSSecurityTokenServiceClientBuilder().standard().withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration("sts-endpoint.amazonaws.com", "signing-region")).build() - When creating the client with no arguments, the default credential provider chain is used to + When creating the client with no arguments (:code:`AWSSecurityTokenService sts_client = new AWSSecurityTokenServiceClientBuilder().standard().build();`), the default credential provider chain is used to retrieve credentials. You can provide a specific credential provider if you want. For more information, see Providing AWS Credentials in the AWS SDK for Java. - #. :emphasis:`Optional`; requires that you have activated the region) Set the endpoint for the - STS client: - - .. code-block:: java - - sts_client.setEndpoint("sts-endpoint.amazonaws.com"); - - where :emphasis:`sts-endpoint` represents the STS endpoint for your region. - - .. important:: Do not use the :methodname:`setRegion` method to set a regional endpoint - |mdash| for backwards compatibility, that method continues to use the single global - endpoint of sts.amazonaws.com. - #. Create a :aws-java-class:`GetSessionTokenRequest ` object, and optionally set the duration in seconds for which the temporary credentials are valid: diff --git a/doc_source/prog-services-swf-list-domains.rst b/doc_source/prog-services-swf-list-domains.rst index a7af948..65f2f4b 100644 --- a/doc_source/prog-services-swf-list-domains.rst +++ b/doc_source/prog-services-swf-list-domains.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/prog-services-swf-register-domain.rst b/doc_source/prog-services-swf-register-domain.rst index 16eacf6..9e7f157 100644 --- a/doc_source/prog-services-swf-register-domain.rst +++ b/doc_source/prog-services-swf-register-domain.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/prog-services-swf.rst b/doc_source/prog-services-swf.rst index ee7c760..04e4dc6 100644 --- a/doc_source/prog-services-swf.rst +++ b/doc_source/prog-services-swf.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/prog-services.rst b/doc_source/prog-services.rst index a448d1f..995b1b3 100644 --- a/doc_source/prog-services.rst +++ b/doc_source/prog-services.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,7 +12,21 @@ |sdk-java| Code Examples ######################## -This section provides tutorials and examples of using the |sdk-java| to program AWS services. +This section provides tutorials and examples of using the |sdk-java| v1 to program AWS services. + +Find the source code for these examples and others in the AWS documentation `code examples repository on GitHub `_. + +To propose a new code example for the AWS documentation team to consider producing, create a new request. +The team is looking to produce code examples that cover broader scenarios and use cases, +versus simple code snippets that cover only individual API calls. For instructions, +see the "Proposing new code examples" section in the `Readme on GitHub `_. + +AWS SDK for Java 2.x +===================== +In 2018, AWS released |sdk-java| v2. For more AWS examples, see the `AWS SDK for Java 2.x Developer Guide`_. + +.. _`aws sdk for java 2.x developer guide`: http://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/welcome.html + .. tip:: See :ref:`additional-resources` for more examples and additional resources available for |sdk-java| developers! @@ -21,12 +35,13 @@ This section provides tutorials and examples of using the |sdk-java| to program :maxdepth: 1 :titlesonly: - SDK Code Samples Amazon CloudWatch Examples Amazon DynamoDB Examples Amazon EC2 Examples AWS Identity and Access Management (IAM) Examples + Amazon Lambda Examples + Amazon Pinpoint Examples Amazon S3 Examples Amazon SQS Examples - prog-services-sts Amazon SWF Examples + Code Samples included with the SDK diff --git a/doc_source/run-instance.rst b/doc_source/run-instance.rst index 0482bbf..2938e60 100644 --- a/doc_source/run-instance.rst +++ b/doc_source/run-instance.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -28,15 +28,16 @@ your EC2 instances are running, you can connect to them. RunInstancesRequest runInstancesRequest = new RunInstancesRequest(); - runInstancesRequest.withImageId("ami-4b814f22") - .withInstanceType("m1.small") + runInstancesRequest.withImageId("ami-a9d09ed1") + .withInstanceType(InstanceType.T1Micro) .withMinCount(1) .withMaxCount(1) .withKeyName("my-key-pair") .withSecurityGroups("my-security-group"); :aws-java-ref:`withImageId ` - The ID of the AMI. For a list of public AMIs provided by Amazon, see Amazon Machine Images. + The ID of the AMI. To learn how to find public AMIs provided by Amazon or + create your own, see :ec2-ug:`Amazon Machine Image (AMI) `. :aws-java-ref:`withInstanceType ` An instance type that is compatible with the specified AMI. For more information, see @@ -72,4 +73,3 @@ your EC2 instances are running, you can connect to them. After your instance is running, you can connect to it using your key pair. For more information, see :ec2-ug:`Connect to Your Linux Instance `. in the |EC2-ug|. - diff --git a/doc_source/s3-encryption-migration.rst b/doc_source/s3-encryption-migration.rst new file mode 100644 index 0000000..0b09cac --- /dev/null +++ b/doc_source/s3-encryption-migration.rst @@ -0,0 +1,277 @@ +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +################################ +|S3| Encryption Client Migration +################################ + +.. meta:: + :description: How to migrate your applications from v1 to v2 of the AWS S3 client-side encryption + service client + :keywords: AWS for Java SDK, migrate, migration, CSE, encryption, key, KMS, S3, + AmazonS3EncryptionClientV2, AmazonS3EncryptionClient + + +This topic shows you how to migrate your applications from Version 1 (V1) of the |S3long| (|S3|) +encryption client to Version 2 (V2) and ensure application availability throughout the migration +process. + +.. _s3-cse-prereq: + +Prerequisites +============= + +|S3| client-side encryption requires the following: + +* Java 8 or later installed in your application environment. The |sdk-java| works with the + `Oracle Java SE Development Kit `_ + and with distributions of Open Java Development Kit (OpenJDK) such as + `Amazon Corretto `_, + `Red Hat OpenJDK `_, + and `AdoptOpenJDK `_. + +* The `Bouncy Castle Crypto package `_. You can + place the Bouncy Castle .jar file on the classpath of your application environment, or add a + dependency on the artifactId :code:`bcprov-ext-jdk15on` (with the groupId of + :code:`org.bouncycastle`) to your Maven :file:`pom.xml` file. + +.. _s3-cse-overview: + +Migration Overview +================== + +This migration happens in two phases: + +1. **Update existing clients to read new formats.** Update your application to use version 1.11.837 + or later of the AWS SDK for Java and redeploy the application. This enables the |S3| client-side + encryption service clients in your application to decrypt objects created by V2 service clients. + If your application uses multiple AWS SDKs, you must update each SDK separately. + +2. **Migrate encryption and decryption clients to V2.** Once all of your V1 encryption clients can + read V2 encryption formats, update the |S3| client-side encryption and decryption clients in your + application code to use their V2 equivalents. + +.. _s3-cse-update-project: + +Update Existing Clients to Read New Formats +=========================================== + +The V2 encryption client uses encryption algorithms that older versions of the AWS SDK for Java do +not support. + +The first step in the migration is to update your V1 encryption clients to use version 1.11.837 or +later of the |sdk-java|. (We recommend that you update to the latest release version, which you can +find in the +`Java API Reference version 1.x `_.) To do +so, update the dependency in your project configuration. After your project configuration is +updated, rebuild your project and redeploy it. + +Once you have completed these steps, your application’s V1 encryption clients will be able to read +objects written by V2 encryption clients. + +Update the Dependency in Your Project Configuration +--------------------------------------------------- + +Modify your project configuration file (for example, pom.xml or build.gradle) to use version +1.11.837 or later of the AWS SDK for Java. Then, rebuild your project and redeploy it. + +Completing this step before deploying new application code helps to ensure that encryption +and decryption operations remain consistent across your fleet during the migration process. + +Example Using Maven +~~~~~~~~~~~~~~~~~~~ + +Snippet from a pom.xml file: + +.. code-block:: xml + + + + + com.amazonaws + aws-java-sdk-bom + 1.11.837 + pom + import + + + + +Example Using Gradle +~~~~~~~~~~~~~~~~~~~~ + +Snippet from a build.gradle file: + +.. code-block:: json + + dependencies { + implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.837') + implementation 'com.amazonaws:aws-java-sdk-s3' + } + +.. _s3-cse-update-code: + +Migrate Encryption and Decryption Clients to V2 +=============================================== + +Once your project has been updated with the latest SDK version, you can modify your application code +to use the V2 client. To do so, first update your code to use the new service client builder. Then +provide encryption materials using a method on the builder that has been renamed, and configure your +service client further as needed. + +These code snippets demonstrate how to use client-side encryption with the AWS SDK for Java, and +provide comparisons between the V1 and V2 encryption clients. + +**V1** + +.. code-block:: java + + // minimal configuration in V1; default CryptoMode.EncryptionOnly. + EncryptionMaterialsProvider encryptionMaterialsProvider = ... + AmazonS3Encryption encryptionClient = AmazonS3EncryptionClient.encryptionBuilder() + .withEncryptionMaterials(encryptionMaterialsProvider) + .build(); + +**V2** + +.. code-block:: java + + // minimal configuration in V2; default CryptoMode.StrictAuthenticatedEncryption. + EncryptionMaterialsProvider encryptionMaterialsProvider = ... + AmazonS3EncryptionV2 encryptionClient = AmazonS3EncryptionClientV2.encryptionBuilder() + .withEncryptionMaterialsProvider(encryptionMaterialsProvider) + .withCryptoConfiguration(new CryptoConfigurationV2() + // The following setting allows the client to read V1 encrypted objects + .withCryptoMode(CryptoMode.AuthenticatedEncryption) + ) + .build(); + +The above example sets the :code:`cryptoMode` to :code:`AuthenticatedEncryption`. This is a setting +that allows a V2 encryption client to read objects that have been written by a V1 encryption +client. If your client does not need the capability to read objects written by a V1 client, then we +recommend using the default setting of :code:`StrictAuthenticatedEncryption` instead. + +Construct a V2 Encryption Client +-------------------------------- + +The V2 encryption client can be constructed by calling +*AmazonS3EncryptionClientV2.encryptionBuilder().* + +You can replace all of your existing V1 encryption clients with V2 encryption clients. A V2 +encryption client will always be able to read any object that has been written by a V1 encryption +client as long as you permit it to do so by configuring the V2 encryption client to use the +:code:`AuthenticatedEncryption` :code:`cryptoMode`. + +Creating a new V2 encryption client is very similar to how you create a V1 encryption client. +However, there are a few differences: + +* You will use a :code:`CryptoConfigurationV2` object to configure the client instead of a + :code:`CryptoConfiguration` object. This parameter is required. +* The default :code:`cryptoMode` setting for the V2 encryption client is + :code:`StrictAuthenticatedEncryption`. For the V1 encryption client it is :code:`EncryptionOnly`. +* The method *withEncryptionMaterials()* on the encryption client builder has been renamed to + *withEncryptionMaterialsProvider()*. This is merely a cosmetic change that more accurately + reflects the argument type. You must use the new method when you configure your service client. + +.. note:: When decrypting with AES-GCM, read the entire object to the end before you start using the + decrypted data. This is to verify that the object has not been modified since it was encrypted. + + +Use Encryption Materials Providers +---------------------------------- + +You can continue to use the same encryption materials providers and encryption materials objects +you are already using with the V1 encryption client. These classes are responsible for providing the +keys the encryption client uses to secure your data. They can be used interchangeably with both the +V2 and the V1 encryption client. + +Configure the V2 Encryption Client +---------------------------------- + +The V2 encryption client is configured with a :code:`CryptoConfigurationV2` object. This object can be +constructed by calling its default constructor and then modifying its properties as required from +the defaults. + +The default values for :code:`CryptoConfigurationV2` are: + +* :code:`cryptoMode` = :code:`CryptoMode.StrictAuthenticatedEncryption` +* :code:`storageMode` = :code:`CryptoStorageMode.ObjectMetadata` +* :code:`secureRandom` = instance of :code:`SecureRandom` +* :code:`rangeGetMode` = :code:`CryptoRangeGetMode.DISABLED` +* :code:`unsafeUndecryptableObjectPassthrough` = :code:`false` + +Note that `EncryptionOnly` is not a supported :code:`cryptoMode` in the V2 encryption client. The V2 +encryption client will always encrypt content using authenticated encryption, and protects content +encrypting keys (CEKs) using V2 :code:`KeyWrap` objects. + +The following example demonstrates how to specify the crypto configuration in V1, and how to +instantiate a *CryptoConfigurationV2* object to pass to the V2 encryption client builder. + +**V1** + +.. code-block:: java + + CryptoConfiguration cryptoConfiguration = new CryptoConfiguration() + .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption); + +**V2** + +.. code-block:: java + + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption); + +.. _additional-examples: + +Additional Examples +=================== + +The following examples demonstrate how to address specific use cases related to a migration from V1 +to V2. + +Configure a Service Client to Read Objects Created by the V1 Encryption Client +------------------------------------------------------------------------------ + +To read objects that were previously written using a V1 encryption client, set the +:code:`cryptoMode` to :code:`AuthenticatedEncryption`. The following code snippet demonstrates how +to construct a configuration object with this setting. + +.. code-block:: java + + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withCryptoMode(CryptoMode.AuthenticatedEncryption); + +Configure a Service Client to Get Byte Ranges of Objects +-------------------------------------------------------- + +To be able to :code:`get` a range of bytes from an encrypted S3 object, enable the new configuration +setting :code:`rangeGetMode`. This setting is disabled on the V2 encryption client by default. Note +that even when enabled, a ranged :code:`get` only works on objects that have been encrypted using +algorithms supported by the :code:`cryptoMode` setting of the client. For more information, see +:aws-java-class:`CryptoRangeGetMode ` in the AWS SDK for Java +API Reference. + +If you plan to use the |S3| TransferManager to perform multipart downloads of encrypted |S3| objects +using the V2 encryption client, then you must first enable the :code:`rangeGetMode` setting on the +V2 encryption client. + +The following code snippet demonstrates how to configure the V2 client for performing a ranged +:code:`get`. + +.. code-block:: java + + // Allows range gets using AES/CTR, for V2 encrypted objects only + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withRangeGetMode(CryptoRangeGetMode.ALL); + + // Allows range gets using AES/CTR and AES/CBC, for V1 and V2 objects + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withCryptoMode(CryptoMode.AuthenticatedEncryption) + .withRangeGetMode(CryptoRangeGetMode.ALL); diff --git a/doc_source/sdk-metrics.rst b/doc_source/sdk-metrics.rst new file mode 100755 index 0000000..ef87fca --- /dev/null +++ b/doc_source/sdk-metrics.rst @@ -0,0 +1,352 @@ +.. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +.. |language| replace:: Java +.. |sdk| replace:: |sdk-java| + +#################### +Enabling |SDKMlong| +#################### + +|SDKMlong| (|SDKM|\) enables Enterprise customers to collect metrics from |AWS| SDKs on their hosts and clients shared with +|AWS| Enterprise Support. |SDKM| provides information that helps speed up detection and diagnosis of issues occurring in connections +to AWS services for AWS Enterprise Support customers. + +As telemetry is collected on each host, it is relayed via UDP to 127.0.0.1 (aka localhost), where the |CW| agent aggregates the data and sends it +to the |SDKM| service. Therefore, to receive metrics, the |CW| agent is required to be added to your instance. + +The following steps to set up |SDKM| pertain to an |EC2| instance running Amazon Linux for a client application that is using the |sdk|. +|SDKM| is also available for your production environments if you enable it while configuring the |sdk|. + +To utilize |SDKM|, run the latest version of the |CW| agent. Learn how to +:CW-dg:`Configure the CloudWatch Agent for SDK Metrics` in the |CW-dg|. + +To set up |SDKM| with the |sdk|, follow these instructions: + +#. Create an application with an |sdk| client to use an AWS service. +#. Host your project on an |EC2| instance or in your local environment. +#. Install and use the latest 1.x version of the |sdk|. +#. Install and configure an |CW| agent on an EC2 instance or in your local environment. +#. Authorize |SDKM| to collect and send metrics. +#. :ref:`csm-enable-agent`. + +For more information, see the following: + +* :ref:`csm-update-agent` +* :ref:`csm-disable-agent` + + +.. _csm-enable-agent: + +Enable |SDKM| for the |sdk| +=========================== + +By default, |SDKM| is turned off, and the port is set to 31000. The following are the default parameters. + +.. code-block:: ini + + //default values + [ + 'enabled' => false, + 'port' => 31000, + ] + +Enabling |SDKM| is independent of configuring your credentials to use an AWS service. + +You can enable |SDKM| using one of 4 options. + +* :ref:`csm-enable-agent-environ` +* :ref:`csm-enable-agent-code` +* :ref:`csm-enable-agent-java-prop` +* :ref:`csm-enable-agent-shared-config` + +.. _csm-enable-agent-environ: + +Option 1: Set Environment Variables +----------------------------------- + +If :code:`AWS_CSM_ENABLED` is not set, the SDK first checks the profile specified in +the environment variable under :code:`AWS_PROFILE` to determine if |SDKM| is enabled. +By default this is set to ``false``. + +To turn on |SDKM|, add the following to your environmental variables. + +.. code-block:: ini + + export AWS_CSM_ENABLED=true + +:ref:`Other configuration settings` are available. + +Note: Enabling |SDKM| does not configure your credentials to use an AWS service. + +.. _csm-enable-agent-code: + +Option 2: Set |SDKM| in Code +---------------------------- + +The |language| implementation allows you to set |SDKM| configurations within code when building +a service client. +The values set in code override any configurations set in the other options described below. + +.. code-block:: java + + CsmConfiguration csmConfig = new CsmConfiguration(true, MY_PORT, MY_CLIENT_ID); + AmazonDynamoDB dynamodb = AmazonDynamoDBClientBuilder.standard() + .withClientSideMonitoringConfigurationProvider(new StaticCsmConfigurationProvider(csmConfig)) + .build(); + +.. _csm-enable-agent-java-prop: + +Option 3: Set Java System Property +---------------------------------- + +If no |SDKM| configuration is found in the environment variables, +the SDK looks at certain Java system properties. + +To turn on |SDKM|, pass the following system property flag when you execute your application. + +.. code-block:: ini + + -Dcom.amazonaws.sdk.csm.enabled="true" + +You can also set the value programmatically using the Properties object. + +.. code-block:: java + + Properties props = System.getProperties(); + props.setProperty("com.amazonaws.sdk.csm.enabled", "true"); + +:ref:`Other configuration settings` are available. + +Note: Enabling |SDKM| does not configure your credentials to use an AWS service. + +.. _csm-enable-agent-shared-config: + +Option 4: AWS Shared Config File +-------------------------------- + +If no |SDKM| configuration is found in the environment variables or the Java system properties, +the SDK looks for your default AWS profile field. If :code:`AWS_DEFAULT_PROFILE` is set to +something other than default, update that profile. +To enable |SDKM|, add :code:`csm_enabled` to the shared config file located at :file:`~/.aws/config`. + +.. code-block:: ini + + [default] + csm_enabled = true + + [profile aws_csm] + csm_enabled = true + +:ref:`Other configuration settings` are available. + +Note: Enabling |SDKM| is independent from configuring your credentials to use an AWS service. You can use a different profile to authenticate. + +.. _csm-update-agent: + +Update a |CW| Agent +=================== + +To make changes to the port, you need to set the values and then restart any AWS jobs that are currently active. + +Option 1: Set Environment Variables +----------------------------------- + +Most services use +the default port. But if your service requires a unique port ID, add `AWS_CSM_PORT=[port_number]`, to the host's environment variables. + +.. code-block:: shell + + export AWS_CSM_ENABLED=true + export AWS_CSM_PORT=1234 + +Option 2: Set Java System Property +----------------------------------- + +Most services use the default port. +But if your service requires a unique port ID, specify the `-Dcom.amazonaws.sdk.csm.port=[port_number]` +system properties flag when executing your application. + +.. code-block:: ini + + com.amazonaws.sdk.csm.enabled=true + com.amazonaws.sdk.csm.port=1234 + +Option 3: AWS Shared Config File +----------------------------------- + +Most services use the default port. But if your service requires a +unique port ID, add `csm_port = [port_number]` to `~/.aws/config`. + +.. code-block:: ini + + [default] + csm_enabled = false + csm_port = 1234 + + [profile aws_csm] + csm_enabled = false + csm_port = 1234 + +Restart |SDKM| +-------------- + +To restart a job, run the following commands. + +.. code-block:: shell + + amazon-cloudwatch-agent-ctl –a stop; + amazon-cloudwatch-agent-ctl –a start; + + +.. _csm-disable-agent: + +Disable |SDKM| +============== + +To turn off |SDKM|, set `csm_enabled` to `false` in your environment variables, or in your AWS Shared config file located at :file:`~/.aws/config`. +Then restart your |CW| agent so that the changes can take effect. + +**Environment Variables** + +.. code-block:: shell + + export AWS_CSM_ENABLED=false + + +**AWS Shared Config File** + +Remove `csm_enabled` from the profiles in your AWS Shared config file located at :file:`~/.aws/config`. + +.. note:: Environment variables override the AWS Shared config file. If |SDKM| is enabled in the environment variables, the |SDKM| remain enabled. + +.. code-block:: ini + + [default] + csm_enabled = false + + [profile aws_csm] + csm_enabled = false + +To disable |SDKM|, use the following command to stop |CW| agent. + +.. code-block:: shell + + sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a stop && + echo "Done" + +If you are using other |CW| features, restart the |CW| agent with the following command. + +.. code-block:: shell + + amazon-cloudwatch-agent-ctl –a start; + + +Restart |SDKM| +-------------- + +To restart a |SDKM|, run the following commands. + +.. code-block:: shell + + amazon-cloudwatch-agent-ctl –a stop; + amazon-cloudwatch-agent-ctl –a start; + + +Definitions for |SDKM| +====================== + +You can use the following descriptions of |SDKM| to interpret your results. In general, these metrics are available for review +with your Technical Account Manager during regular business reviews. AWS Support resources and your Technical Account Manager +should have access to SDK Metrics data to help you resolve cases, but if you discover data that is confusing or unexpected, but +doesn’t seem to be negatively impacting your applications’ performance, it is best to review that data during scheduled +business reviews. + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - CallCount + + * - Definition + - Total number of successful or failed API calls from your code to AWS services + + * - How to use it + - Use it as a baseline to correlate with other metrics like errors or throttling. + + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - ClientErrorCount + + * - Definition + - Number of API calls that fail with client errors (4xx HTTP response codes). *Examples: Throttling, Access denied, S3 bucket does not exist, and Invalid parameter value.* + + * - How to use it + - Except in certain cases related to throttling (ex. when throttling occurs due to a limit that needs to be increased) this metric can indicate something in your application that needs to be fixed. + + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - ConnectionErrorCount + + * - Definition + - Number of API calls that fail because of errors connecting to the service. These can be caused by network issues between the customer application and AWS services including load balancers, DNS failures, transit providers. In some cases, AWS issues may result in this error. + + * - How to use it + - Use this metric to determine whether issues are specific to your application or are caused by your infrastructure and/or network. High ConnectionErrorCount could also indicate short timeout values for API calls. + + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - ThrottleCount + + * - Definition + - Number of API calls that fail due to throttling by AWS services. + + * - How to use it + - Use this metric to assess if your application has reached throttle limits, as well as to determine the cause of retries and application latency. Consider distributing calls over a window instead of batching your calls. + + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - ServerErrorCount + + * - Definition + - Number of API calls that fail due to server errors (5xx HTTP response codes) from AWS Services. These are typically caused by AWS services. + + * - How to use it + - Determine cause of SDK retries or latency. This metric will not always indicate that AWS services are at fault, as some AWS teams classify latency as an HTTP 503 response. + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - EndToEndLatency + + * - Definition + - Total time for your application to make a call using the AWS SDK, inclusive of retries. In other words, regardless of whether it is successful after several attempts, or as soon as a call fails due to an unretriable error. + + * - How to use it + - Determine how AWS API calls contribute to your application’s overall latency. Higher than expected latency may be caused by issues with network, firewall, or other configuration settings, or by latency that occurs as a result of SDK retries. diff --git a/doc_source/section-client-configuration.rst b/doc_source/section-client-configuration.rst index 69a9665..70fc1e8 100644 --- a/doc_source/section-client-configuration.rst +++ b/doc_source/section-client-configuration.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,9 +8,9 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -############################### -Client Networking Configuration -############################### +###################### +Client Configuration +###################### .. meta:: :description: How to change proxy configuration, HTTP transport configuration, and TCP socket @@ -43,17 +43,10 @@ You can configure several HTTP transport options by using the :aws-java-class:`C object. New options are occasionally added; to see the full list of options you can retrieve or set, see the |sdk-java-ref|. -Each of the configurable values has a default value defined by a constant. For a list of the -constant values for :classname:`ClientConfiguration`, see :sdk-java-ref:`Constant Field Values -` in the |sdk-java-ref|. - - -Local Address -------------- - -To set the local address that the HTTP client will bind to, use -:aws-java-ref:`ClientConfiguration.setLocalAddress -`. +.. note:: + Each of the configurable values has a default value defined by a constant. For a list of the + constant values for :classname:`ClientConfiguration`, see :sdk-java-ref:`Constant Field Values + ` in the |sdk-java-ref|. Maximum Connections @@ -63,12 +56,10 @@ You can set the maximum allowed number of open HTTP connections by using the :aws-java-ref:`ClientConfiguration.setMaxConnections ` method. - -Proxy Options -------------- - -If you use a proxy with your HTTP connections, you might need to set certain options related to HTTP -proxies. +.. important:: + Set the maximum connections to the number of concurrent transactions to avoid + connection contentions and poor performance. For the default maximum connections value, + see :sdk-java-ref:`Constant Field Values ` in the |sdk-java-ref|. Timeouts and Error Handling @@ -79,7 +70,7 @@ You can set options related to timeouts and handling errors with HTTP connection * :strong:`Connection Timeout` The connection timeout is the amount of time (in milliseconds) that the HTTP connection will wait - to establish a connection before giving up. The default is 50,000 ms. + to establish a connection before giving up. The default is 10,000 ms. To set this value yourself, use the :aws-java-ref:`ClientConfiguration.setConnectionTimeout ` method. @@ -99,7 +90,17 @@ You can set options related to timeouts and handling errors with HTTP connection The default maximum retry count for retriable errors is 3. You can set a different value by using the :aws-java-ref:`ClientConfiguration.setMaxErrorRetry - ` method. + ` method. + + +Local Address +------------- + +To set the local address that the HTTP client will bind to, use +:aws-java-ref:`ClientConfiguration.setLocalAddress +`. + + TCP Socket Buffer Size Hints @@ -118,7 +119,7 @@ Large buffer sizes (e.g., 2 MB) allow the operating system to buffer more data i requiring the remote server to acknowledge receipt of that information, and so can be particularly useful when the network has high latency. -This is only a *hint*, and the operating system might not to honor it. When using this option, users +This is only a *hint*, and the operating system might not honor it. When using this option, users should always check the operating system's configured limits and defaults. Most operating systems have a maximum TCP buffer size limit configured, and won't let you go beyond that limit unless you explicitly raise the maximum TCP buffer size limit. @@ -126,5 +127,4 @@ explicitly raise the maximum TCP buffer size limit. Many resources are available to help with configuring TCP buffer sizes and operating system-specific TCP settings, including the following: -* `TCP Tuning and Network Troubleshooting `_ * `Host Tuning `_ diff --git a/doc_source/security-iam.rst b/doc_source/security-iam.rst new file mode 100644 index 0000000..65b77e6 --- /dev/null +++ b/doc_source/security-iam.rst @@ -0,0 +1,33 @@ +Identity and Access Management for this AWS Product or Service +============================================================== + +AWS Identity and Access Management (IAM) is an Amazon Web Services (AWS) +service that helps an administrator securely control access to AWS +resources. IAM administrators control who can be *authenticated* (signed +in) and *authorized* (have permissions) to use resources in AWS +services. IAM is an AWS service that you can use with no additional +charge. + +To use this AWS product or service to access AWS, you need an AWS +account and AWS credentials. To increase the security of your AWS +account, we recommend that you use an *IAM user* to provide access +credentials instead of using your AWS account credentials. + +For details about working with IAM, see `AWS Identity and Access +Management `__. + +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 `__. + +This AWS product or service follows the `shared responsibility +model `__ +through the specific Amazon Web Services (AWS) services it supports. For +AWS service security information, see the `AWS service security +documentation +page `__ +and `AWS services that are in scope of AWS compliance efforts by +compliance +program `__. diff --git a/doc_source/security-java-tls.rst b/doc_source/security-java-tls.rst new file mode 100644 index 0000000..68d9899 --- /dev/null +++ b/doc_source/security-java-tls.rst @@ -0,0 +1,63 @@ +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +##################################### +AWS SDK for Java support for TLS 1.2 +##################################### + +.. meta:: + :description: Applies to Java SSL implementation (default SSL implementation in the SDK). Learn how the AWS shared responsibility model applies to data protection in this AWS product or service. + :keywords: + +The following information applies only to Java SSL implementation (the default SSL implementation in the AWS SDK for Java). If you're using a different SSL implementation, +see your specific SSL implementation to learn how to enforce TLS versions. + +TLS support in Java +=================== +TLS 1.2 is supported starting in Java 7. + +How to check the TLS version +============================ +To check what TLS version is supported in your Java virtual machine (JVM), you can use the following code. + +.. code-block:: java + + System*.out.println(*Arrays*.toString(*SSLContext*.getDefault().getSupportedSSLParameters().getProtocols())); + +To see the SSL handshake in action and what version of TLS is used, you can use the system property **javax.net.debug**. + +.. code-block:: java + + java app.jar -Djavax.net.debug=ssl + +How to set the TLS version +========================== + +**AWS SDK for Java 1.x** + +* Apache HTTP client: The SDK always prefers TLS 1.2 (if it's supported in the platform). + +**AWS SDK for Java 2.x** + +* ApacheHttpClient: The SDK always prefers TLS 1.2 (if it's supported in the platform). + +* UrlHttpConnectionClient: To enforce only TLS 1.2, you can use this Java command. + +.. code-block:: java + + java app.jar -Djdk.tls.client.protocols=TLSv1.2 + +Or use this code. + +.. code-block:: java + + System.setProperty("jdk.tls.client.protocols", "TLSv1.2"); + +* NettyNioHttpClient: The SDK dependency for Netty is TLS 1.2 (if it's supported in the platform). diff --git a/doc_source/security.rst b/doc_source/security.rst new file mode 100644 index 0000000..bdb10ca --- /dev/null +++ b/doc_source/security.rst @@ -0,0 +1,33 @@ +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################### +Security for |SERVICENAMETITLE| +############################### + +.. meta:: + :description: Provides security-related information for this AWS product or service. + :keywords: + +.. include:: common/_security-includes.txt + +.. include:: common/_security.txt + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + Compliance Validation + Data Protection + Enforcing TLS 1.2 + Identity and Access Management + Infrastructure Security + Resilience + S3 Encryption Client Migration diff --git a/doc_source/setup-credentials.rst b/doc_source/setup-credentials.rst index 9890cbb..7042377 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -48,14 +48,42 @@ Once you have set your AWS credentials using one of these methods, they will be by the |sdk-java| by using the default credential provider chain. For further information about working with AWS credentials in your Java applications, see :doc:`credentials`. + +.. _refresh-credentials: +Refreshing IMDS credentials +=========================== + +The |sdk-java| supports opt-in refreshing IMDS credentials in the background every 1 minute, regardless of the credential expiration time. +This allows you to refresh credentials more frequently and reduces the chance that not reaching IMDS impacts +the perceived AWS availability. + +.. code-block:: java + :linenos: + + 1. // Refresh credentials using a background thread, automatically every minute. This will log an error if IMDS is down during + 2. // a refresh, but your service calls will continue using the cached credentials until the credentials are refreshed + 3. // again one minute later. + 4. + 5. InstanceProfileCredentialsProvider credentials = + 6. InstanceProfileCredentialsProvider.createAsyncRefreshingProvider(true); + 7. + 8. AmazonS3Client.builder() + 9. .withCredentials(credentials) + 10. .build(); + 11. + 12. // This is new: When you are done with the credentials provider, you must close it to release the background thread. + 13. credentials.close(); + + .. _setup-credentials-setting-region: Setting the AWS Region ====================== You should set a default AWS Region that will be used for accessing AWS services with the AWS SDK -for Java. For the best network performance, you should choose a region that's geographically close -to you (or to your customers). +for Java. For the best network performance, choose a region that's geographically close +to you (or to your customers). For a list of regions for each service, see |regions-and-endpoints|_ +in the |AWS-gr|. .. note:: If you *don't* select a region, then |region-api-default| will be used by default. @@ -65,3 +93,8 @@ You can use similar techniques to setting credentials to set your default AWS re .. include:: common/sdk-shared-region.txt +.. toctree:: + :maxdepth: 1 + :titlesonly: + + prog-services-sts \ No newline at end of file diff --git a/doc_source/setup-install.rst b/doc_source/setup-install.rst index 2ceb2f5..2541b0c 100644 --- a/doc_source/setup-install.rst +++ b/doc_source/setup-install.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -47,7 +47,8 @@ system or IDE: which will automatically download, install and update the Java SDK for you. For more information and setup instructions, see the |tke-ug|_. -If you intend to build your projects using a different IDE, with Apache Ant or by any other means, +If you are using one the above methods (for example, +you are using Maven), then you do not need to download and install the AWS JAR files (you can skip the following section). If you intend to build your projects using a different IDE, with Apache Ant or by any other means, then download and extract the SDK as shown in the next section. .. _download-and-extract-sdk: @@ -76,7 +77,7 @@ The SDK contains the following directories: * :file:`samples` |ndash| contains working sample code that demonstrates how to use the SDK. -* :file:`third-party` |ndash| contains third-party libraries that are used by the SDK, such as +* :file:`third-party/lib` |ndash| contains third-party libraries that are used by the SDK, such as Apache commons logging, AspectJ and the Spring framework. To use the SDK, add the full path to the ``lib`` and ``third-party`` directories to the dependencies @@ -142,4 +143,3 @@ mode, even if you specify the ``-Client`` option at run time. Using the 32-bit version of the JVM with the ``-Server`` option at run time should provide comparable performance to the 64-bit JVM. - diff --git a/doc_source/setup-project-gradle.rst b/doc_source/setup-project-gradle.rst index 0fd33dc..a6d4dd6 100644 --- a/doc_source/setup-project-gradle.rst +++ b/doc_source/setup-project-gradle.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,13 +12,91 @@ Using the SDK with Gradle ######################### -To use the |sdk-java| in your Gradle_ project, use Spring's `dependency management plugin -`_ for Gradle, which can be -used to import the SDK's Maven Bill of Materials (BOM) to manage SDK dependencies for your project. -.. topic:: To configure the SDK for Gradle +.. meta:: + :description: How to use Gradle to set up your AWS SDK for Java project + :keywords: AWS SDK for Java, Gradle, BOM, install, download, setup - #. Add the dependency management plugin to your :file:`build.gradle` file + +To manage SDK dependencies for your Gradle_ project, import the Maven BOM for the |sdk-java| into the :file:`build.gradle` file. + +.. note:: In the following examples, replace *1.11.X* in the build file with a valid version of the |sdk-java|. Find the latest version in the + `AWS SDK for Java 1.11.x Reference `_. + + +Project setup for Gradle 4.6 or higher +====================================== + +`Since Gradle 4.6 `_, you can +use Gradle's improved POM support feature for importing bill of materials (BOM) files by declaring a dependency on a BOM. + + +.. topic:: To configure the |sdk-java| for Gradle 4.6 or later + + #. If you're using Gradle 5.0 or later, skip to step 2. Otherwise, enable the *IMPROVED_POM_SUPPORT* feature in the :file:`settings.gradle` file. + + .. code-block:: groovy + + enableFeaturePreview('IMPROVED_POM_SUPPORT') + + #. Add the BOM to the *dependencies* section of the :file:`build.gradle` file. + + .. code-block:: groovy + + ... + dependencies { + implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.X') + + // Declare individual SDK dependencies without version + ... + } + + #. Specify the SDK modules to use in the *dependencies* section. For example, the following includes a dependency for |S3long| (|S3|). + + .. code-block:: groovy + + ... + dependencies { + implementation 'com.amazonaws:aws-java-sdk-s3' + ... + } + +Gradle automatically resolves the correct version of your SDK dependencies by using the information from the BOM. + +The following is an example of a complete :file:`build.gradle` file that includes a dependency for |S3|. + +.. code-block:: groovy + + group 'aws.test' + version '1.0-SNAPSHOT' + + apply plugin: 'java' + + sourceCompatibility = 1.8 + + repositories { + mavenCentral() + } + + dependencies { + implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.X') + implementation 'com.amazonaws:aws-java-sdk-s3' + testCompile group: 'junit', name: 'junit', version: '4.11' + } + +.. note:: In the previous example, replace the dependency for |S3| with the dependencies of the AWS services you will use in your project. The modules (dependencies) that are managed by the |sdk-java| BOM are listed on Maven central repository (https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). + + +Project setup for Gradle versions earlier than 4.6 +================================================== + +Gradle versions earlier than 4.6 lack native BOM support. To manage |sdk-java| dependencies for your project, +use Spring's `dependency management plugin +`_ for Gradle to import the Maven BOM for the SDK. + +.. topic:: To configure the SDK for Gradle versions earlier than 4.6 + + #. Add the dependency management plugin to your :file:`build.gradle` file. .. code-block:: groovy @@ -27,40 +105,38 @@ used to import the SDK's Maven Bill of Materials (BOM) to manage SDK dependencie mavenCentral() } dependencies { - classpath "io.spring.gradle:dependency-management-plugin:1.0.3.RELEASE" + classpath "io.spring.gradle:dependency-management-plugin:1.0.9.RELEASE" } } apply plugin: "io.spring.dependency-management" - #. Add the BOM to the *dependencyManagement* section of the file + #. Add the BOM to the *dependencyManagement* section of the file. .. code-block:: groovy dependencyManagement { imports { - mavenBom 'com.amazonaws:aws-java-sdk-bom:1.11.228' + mavenBom 'com.amazonaws:aws-java-sdk-bom:1.11.X' } } - #. Specify the SDK modules that you'll be using in the *dependencies* section + #. Specify the SDK modules that you'll use in the *dependencies* section. For example, the following includes a dependency for |S3|. .. code-block:: groovy dependencies { compile 'com.amazonaws:aws-java-sdk-s3' - testCompile group: 'junit', name: 'junit', version: '4.11' } -Gradle will automatically resolve the correct version of your SDK dependencies using the information -from the BOM. +Gradle automatically resolves the correct version of your SDK dependencies by using the information from the BOM. -Here's the complete :file:`build.gradle` file: +The following is an example of a complete :file:`build.gradle` file that includes a dependency for |S3|. .. code-block:: groovy group 'aws.test' - version '1.0-SNAPSHOT' + version '1.0' apply plugin: 'java' @@ -72,10 +148,10 @@ Here's the complete :file:`build.gradle` file: buildscript { repositories { - mavenCentral() + mavenCentral() } dependencies { - classpath "io.spring.gradle:dependency-management-plugin:1.0.3.RELEASE" + classpath "io.spring.gradle:dependency-management-plugin:1.0.9.RELEASE" } } @@ -83,7 +159,7 @@ Here's the complete :file:`build.gradle` file: dependencyManagement { imports { - mavenBom 'com.amazonaws:aws-java-sdk-bom:1.11.228' + mavenBom 'com.amazonaws:aws-java-sdk-bom:1.11.X' } } @@ -92,5 +168,7 @@ Here's the complete :file:`build.gradle` file: testCompile group: 'junit', name: 'junit', version: '4.11' } -.. note:: For more detail about specifying SDK dependencies using the BOM, see - :doc:`setup-project-maven`. +.. note:: In the previous example, replace the dependency for |S3| with the dependencies of the AWS service you will use in your project. The modules (dependencies) that are managed by the |sdk-java| BOM are listed on Maven central repository (https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). + +For more information about specifying SDK dependencies by using the BOM, see +:doc:`setup-project-maven`. diff --git a/doc_source/setup-project-maven.rst b/doc_source/setup-project-maven.rst index f62ebc8..8fadd1d 100644 --- a/doc_source/setup-project-maven.rst +++ b/doc_source/setup-project-maven.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -82,7 +82,7 @@ SDK you want to use: com.amazonaws aws-java-sdk-bom - 1.11.106 + 1.11.327 pom import @@ -111,6 +111,8 @@ component. +You can also refer to the *AWS Code Catalog* to learn what dependencies to use for a given AWS service. Refer to the POM file under a specific service example. +For example, if you are interested in the dependencies for the AWS S3 service, see the :sdk-examples-java-s3:`complete example ` on GitHub. (Look at the pom under /java/example_code/s3). .. _configuring-maven-entire-sdk: @@ -126,7 +128,7 @@ declare it in your :file:`pom.xml` like this: com.amazonaws aws-java-sdk - 1.11.106 + 1.11.327 @@ -151,4 +153,3 @@ GitHub `_, unpack it locally, and then exec Maven command:: mvn clean install - diff --git a/doc_source/signup-create-iam-user.rst b/doc_source/signup-create-iam-user.rst index 2bf7b7c..1a1e207 100644 --- a/doc_source/signup-create-iam-user.rst +++ b/doc_source/signup-create-iam-user.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the diff --git a/doc_source/snippets/CreateSwfDomain-list_swf_domains.java b/doc_source/snippets/CreateSwfDomain-list_swf_domains.java index dccb741..cbd7ed7 100644 --- a/doc_source/snippets/CreateSwfDomain-list_swf_domains.java +++ b/doc_source/snippets/CreateSwfDomain-list_swf_domains.java @@ -1,5 +1,5 @@ /* - Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. + Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This file is licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of diff --git a/doc_source/snippets/CreateSwfDomain-register_swf_domain.java b/doc_source/snippets/CreateSwfDomain-register_swf_domain.java index ad1eded..aacc2cf 100644 --- a/doc_source/snippets/CreateSwfDomain-register_swf_domain.java +++ b/doc_source/snippets/CreateSwfDomain-register_swf_domain.java @@ -1,5 +1,5 @@ /* - Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. + Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This file is licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of diff --git a/doc_source/snippets/CreateSwfDomain/CreateSwfDomain.java b/doc_source/snippets/CreateSwfDomain/CreateSwfDomain.java index 7e54088..191e643 100644 --- a/doc_source/snippets/CreateSwfDomain/CreateSwfDomain.java +++ b/doc_source/snippets/CreateSwfDomain/CreateSwfDomain.java @@ -1,5 +1,5 @@ /* - Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. + Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This file is licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of diff --git a/doc_source/snippets/CreateSwfDomain/build.xml b/doc_source/snippets/CreateSwfDomain/build.xml index cb999e5..bef385a 100644 --- a/doc_source/snippets/CreateSwfDomain/build.xml +++ b/doc_source/snippets/CreateSwfDomain/build.xml @@ -1,5 +1,5 @@ ` method for the state of the Spot +` method for the state of the Spot request ID we want to monitor. The request ID created in Step 2 is embedded in the response to our :code:`requestSpotInstances` @@ -401,8 +378,8 @@ Step 5: Cleaning Up Your Spot Requests and Instances Lastly, we need to clean up our requests and instances. It is important to both cancel any outstanding requests :emphasis:`and` terminate any instances. Just canceling your requests will not terminate your instances, which means that you will continue to pay for them. If you terminate your -instances, your Spot requests may be canceled, but there are some scenarios |mdash| such as if you -use persistent bids|mdash|where terminating your instances is not sufficient to stop your request +instances, your Spot requests may be canceled, but there are some scenarios such as if you +use persistent bids where terminating your instances is not sufficient to stop your request from being re-fulfilled. Therefore, it is a best practice to both cancel any active bids and terminate any running instances. @@ -531,5 +508,3 @@ Next Steps ========== Proceed with :doc:`tutorial-spot-adv-java`. - - diff --git a/doc_source/welcome.rst b/doc_source/welcome.rst index ae9d55b..e4215e5 100644 --- a/doc_source/welcome.rst +++ b/doc_source/welcome.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,7 +12,7 @@ :description: Welcome to the AWS Java Developer Guide -.. _`aws sdk for java 2.0 developer guide`: http://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/welcome.html +.. _`aws sdk for java 2.x developer guide`: http://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/welcome.html ################################ @@ -24,11 +24,11 @@ applications that work with |S3|, |EC2|, |SDB|, and more. We regularly add suppo to the |sdk-java|. For a list of the supported services and their API versions that are included with each release of the SDK, view the `release notes`_ for the version that you're working with. -AWS SDK for Java 2.0 Developer Preview -====================================== -Take a look at the new AWS SDK for Java 2.0 developer preview at https://github.com/aws/aws-sdk-java-v2/. +AWS SDK for Java 2.x +===================== +Take a look at the new AWS SDK for Java 2.x at https://github.com/aws/aws-sdk-java-v2/. It includes much awaited features, such as a way to plug in a HTTP implementation. To get started, -see the `AWS SDK for Java 2.0 Developer Guide`_. +see the `AWS SDK for Java 2.x Developer Guide`_. .. _additional-resources: @@ -58,6 +58,8 @@ developers: + `Gitter channel `_ +* The `AWS Code Sample Catalog `_ + * `@awsforjava (Twitter) `_ * `release notes `_