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/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 0737153..c8adbe8 100644 --- a/doc_source/conf.py +++ b/doc_source/conf.py @@ -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 diff --git a/doc_source/creating-clients.rst b/doc_source/creating-clients.rst index fe1b14b..d35a445 100644 --- a/doc_source/creating-clients.rst +++ b/doc_source/creating-clients.rst @@ -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 291a869..2d017ea 100644 --- a/doc_source/credentials.rst +++ b/doc_source/credentials.rst @@ -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/examples-crypto-kms.rst b/doc_source/examples-crypto-kms.rst index ab7c5bc..b0dc34d 100644 --- a/doc_source/examples-crypto-kms.rst +++ b/doc_source/examples-crypto-kms.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 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 + + 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-kms: +.. _strict-authenticated-encryption-kms: -Encryption-Only Mode -==================== +Strict authenticated encryption +=============================== -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 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-kms: -Authenticated Encryption Mode +Authenticated encryption mode ============================= When you use :classname:`AuthenticatedEncryption` mode, an improved key wrapping algorithm is @@ -106,52 +123,11 @@ To enable this mode, specify the :classname:`AuthenticatedEncryption` value in t **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-kms: - -Strict Authenticated Encryption -=============================== - -To 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: 278-284 - :dedent: 8 - :language: java - -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 7a211e3..5afbd50 100644 --- a/doc_source/examples-crypto-masterkey.rst +++ b/doc_source/examples-crypto-masterkey.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 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 @@ -114,52 +97,14 @@ To enable this mode, specify the :classname:`AuthenticatedEncryption` value in t **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 -: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: 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 db71298..c37c681 100644 --- a/doc_source/examples-crypto.rst +++ b/doc_source/examples-crypto.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 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 5caefc1..b360d0a 100644 --- a/doc_source/examples-dynamodb-items.rst +++ b/doc_source/examples-dynamodb-items.rst @@ -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 5a27dbd..faff57d 100644 --- a/doc_source/examples-dynamodb-tables.rst +++ b/doc_source/examples-dynamodb-tables.rst @@ -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** diff --git a/doc_source/examples-ec2-regions-zones.rst b/doc_source/examples-ec2-regions-zones.rst index 553b0dd..568ae5e 100644 --- a/doc_source/examples-ec2-regions-zones.rst +++ b/doc_source/examples-ec2-regions-zones.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 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-iam.rst b/doc_source/examples-iam.rst index 92005a0..46500e3 100644 --- a/doc_source/examples-iam.rst +++ b/doc_source/examples-iam.rst @@ -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-update-channel.rst b/doc_source/examples-pinpoint-update-channel.rst index 31f1a0a..c27a545 100644 --- a/doc_source/examples-pinpoint-update-channel.rst +++ b/doc_source/examples-pinpoint-update-channel.rst @@ -42,7 +42,7 @@ and pass that object to the :dedent: 2 :language: java -See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. More Information diff --git a/doc_source/examples-s3-bucket-policies.rst b/doc_source/examples-s3-bucket-policies.rst index d6335a1..f8b8e0c 100644 --- a/doc_source/examples-s3-bucket-policies.rst +++ b/doc_source/examples-s3-bucket-policies.rst @@ -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 e16efb0..91afff7 100644 --- a/doc_source/examples-s3-buckets.rst +++ b/doc_source/examples-s3-buckets.rst @@ -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 e2dcc22..2cff970 100644 --- a/doc_source/examples-s3-objects.rst +++ b/doc_source/examples-s3-objects.rst @@ -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 8a551e9..a3e62e7 100644 --- a/doc_source/examples-s3-transfermanager.rst +++ b/doc_source/examples-s3-transfermanager.rst @@ -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: 61-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: 59-62, 64, 66-70 +.. 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: 37-41, 43, 45-49 +.. 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: 35-46 +.. 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-62, 65-68, 71-74 +.. 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-150, 153-155, 158-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: 83-84 +.. 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 1a9329f..2b31a3c 100644 --- a/doc_source/examples-s3-website-configuration.rst +++ b/doc_source/examples-s3-website-configuration.rst @@ -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-sqs-messages.rst b/doc_source/examples-sqs-messages.rst index 67aa64e..d4427c9 100644 --- a/doc_source/examples-sqs-messages.rst +++ b/doc_source/examples-sqs-messages.rst @@ -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/generating-sdk-metrics.rst b/doc_source/generating-sdk-metrics.rst old mode 100644 new mode 100755 index 0f84966..3c25c58 --- a/doc_source/generating-sdk-metrics.rst +++ b/doc_source/generating-sdk-metrics.rst @@ -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:: diff --git a/doc_source/getting-started.rst b/doc_source/getting-started.rst old mode 100644 new mode 100755 index 44b1963..738611c --- a/doc_source/getting-started.rst +++ b/doc_source/getting-started.rst @@ -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/index.rst b/doc_source/index.rst index 8abe472..59814c8 100644 --- a/doc_source/index.rst +++ b/doc_source/index.rst @@ -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-region-selection.rst b/doc_source/java-dg-region-selection.rst index de6e25c..e6a1ae0 100644 --- a/doc_source/java-dg-region-selection.rst +++ b/doc_source/java-dg-region-selection.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 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 bf90958..82f1fec 100644 --- a/doc_source/java-dg-roles.rst +++ b/doc_source/java-dg-roles.rst @@ -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 73aacf2..343550d 100644 --- a/doc_source/java-dg-samples.rst +++ b/doc_source/java-dg-samples.rst @@ -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/lambda-examples.rst b/doc_source/lambda-examples.rst new file mode 100644 index 0000000..2687321 --- /dev/null +++ b/doc_source/lambda-examples.rst @@ -0,0 +1,28 @@ +.. 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. + +########################################## +Lambda Examples Using the |sdk-java| +########################################## + +.. meta:: + :description: Programming Amazon Lambda using the AWS SDK for Java. + :keywords: AWS SDK for Java code examples + +This section provides examples of programming Lambda using the |sdk-java|. + +.. include:: includes/complete-examples-note.txt + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Service Operations + diff --git a/doc_source/prog-services-sts.rst b/doc_source/prog-services-sts.rst index 59e7400..f82ecb5 100644 --- a/doc_source/prog-services-sts.rst +++ b/doc_source/prog-services-sts.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 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.rst b/doc_source/prog-services.rst index b1bbd18..995b1b3 100644 --- a/doc_source/prog-services.rst +++ b/doc_source/prog-services.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 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,13 +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/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 341a8e7..70fc1e8 100644 --- a/doc_source/section-client-configuration.rst +++ b/doc_source/section-client-configuration.rst @@ -70,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. @@ -119,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. @@ -127,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 c9caf99..7042377 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -48,6 +48,33 @@ 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 @@ -65,3 +92,9 @@ You can use similar techniques to setting credentials to set your default AWS re .. The following file is in the shared content at https://github.com/awsdocs/aws-doc-shared-content .. 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 d304e8d..2541b0c 100644 --- a/doc_source/setup-install.rst +++ b/doc_source/setup-install.rst @@ -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: diff --git a/doc_source/setup-project-gradle.rst b/doc_source/setup-project-gradle.rst index 1adf58c..a6d4dd6 100644 --- a/doc_source/setup-project-gradle.rst +++ b/doc_source/setup-project-gradle.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2018 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 d71d415..8fadd1d 100644 --- a/doc_source/setup-project-maven.rst +++ b/doc_source/setup-project-maven.rst @@ -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: diff --git a/doc_source/swf-basics.rst b/doc_source/swf-basics.rst index 08cb056..58ed4c9 100644 --- a/doc_source/swf-basics.rst +++ b/doc_source/swf-basics.rst @@ -34,7 +34,7 @@ Basic |SWF| applications will require the following dependencies, which are incl you have, but the versions that are supplied with the SDK have been tested for compatibility, and are the ones you should use. -|jflow| applications require additonal setup, *and* additional dependencies. See the |jflow-dg|_ for +|jflow| applications require additional setup, *and* additional dependencies. See the |jflow-dg|_ for more information about using the framework. Imports diff --git a/doc_source/swf-graceful-shutdown.rst b/doc_source/swf-graceful-shutdown.rst index baa3684..73cf8d3 100644 --- a/doc_source/swf-graceful-shutdown.rst +++ b/doc_source/swf-graceful-shutdown.rst @@ -30,9 +30,8 @@ attempt a graceful shutdown of the activity worker. Here is the complete code: -.. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/ActivityWorkerWithGracefulShutdown.java +.. literalinclude:: swf.java.activity_worker_with_graceful_shutdown.complete.txt :language: java - :lines: 16- In this version, the polling code that was in the ``main`` function in the original version has been moved into its own method, ``pollAndExecute``. diff --git a/doc_source/swf-hello.rst b/doc_source/swf-hello.rst index 514fabe..f39befb 100644 --- a/doc_source/swf-hello.rst +++ b/doc_source/swf-hello.rst @@ -115,7 +115,7 @@ Create a SWF project .. code-block:: sh mvn archetype:generate -DartifactId=helloswf \ - -DgroupId=example.swf.hello -DinteractiveMode=false + -DgroupId=aws.example.helloswf -DinteractiveMode=false This will create a new project with a standard maven project structure: @@ -126,9 +126,9 @@ Create a SWF project └── src ├── main │   └── java - │   └── example - │   └── swf - │   └── hello + │   └── aws + │   └── example + │   └── helloswf │   └── App.java └── test └── ... @@ -185,24 +185,22 @@ interest of time, these steps *will be implied every time you add a new file to #. Add a :code-java:`package` declaration to the beginning of each file to declare its namespace. The example project uses: - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/HelloTypes.java + .. literalinclude:: swf.java.hello_types.package.txt :language: java - :lines: 16 #. Add :code-java:`import` declarations for the :aws-java-class:`AmazonSimpleWorkflowClient ` class and for multiple classes in the ``com.amazonaws.services.simpleworkflow.model`` namespace. To simplify things, we'll use: - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/HelloTypes.java + .. literalinclude:: swf.java.hello_types.import.txt :language: java - :lines: 18-20 .. _swf-hello-hellotypes: Register a domain, workflow and activity types ---------------------------------------------- -We'll begin by creating a new executeable class, :file:`HelloTypes.java`. This file will contain shared +We'll begin by creating a new executable class, :file:`HelloTypes.java`. This file will contain shared data that different parts of your workflow will need to know about, such as the name and version of your activity and workflow types, the domain name and the task list name. @@ -212,9 +210,8 @@ your activity and workflow types, the domain name and the task list name. #. Declare the :classname:`HelloTypes` class and provide it with values to use for your registered activity and workflow types: - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/HelloTypes.java + .. literalinclude:: swf.java.hello_types.string_declare.txt :language: java - :lines: 22-28, 83 These values will be used throughout the code. @@ -222,18 +219,16 @@ your activity and workflow types, the domain name and the task list name. ` class. This is the basic interface to the |SWF| methods provided by the |sdk-java|. - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/HelloTypes.java + .. literalinclude:: swf.java.hello_types.client.txt :language: java - :lines: 30-31 :dedent: 4 #. Add a new function to register a SWF domain. A *domain* is a logical container for a number of related SWF activity and workflow types. SWF components can only communicate with each other if they exist within the same domain. - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/HelloTypes.java + .. literalinclude:: swf.java.hello_types.new_function.txt :language: java - :lines: 33-42 :dedent: 4 When you register a domain, you provide it with a *name* (any set of 1 |ndash| 256 characters @@ -254,9 +249,8 @@ your activity and workflow types, the domain name and the task list name. #. Add a function to register a new activity type. An *activity* represents a unit of work in your workflow. - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/HelloTypes.java + .. literalinclude:: swf.java.hello_types.new_activity_type.txt :language: java - :lines: 44-60 :dedent: 4 An activity type is identified by a *name* and a *version*, which are used to uniquely identify @@ -276,9 +270,8 @@ your activity and workflow types, the domain name and the task list name. #. Add a function to register a new workflow type. A *workflow*, also known as a *decider* represents the logic of your workflow's execution. - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/HelloTypes.java + .. literalinclude:: swf.java.hello_types.new_workflow_type.txt :language: java - :lines: 62-76 :dedent: 4 Similar to activity types, workflow types are identified by a *name* and a *version* and also @@ -292,9 +285,8 @@ your activity and workflow types, the domain name and the task list name. #. Finally, make the class executable by providing it a :code-java:`main` method, which will register the domain, the activity type, and the workflow type in turn: - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/HelloTypes.java + .. literalinclude:: swf.java.hello_types.main.txt :language: java - :lines: 78-82 :dedent: 4 You can :ref:`build ` and :ref:`run ` the application now @@ -319,19 +311,20 @@ We'll implement a simple activity worker that drives a single activity. #. Open your text editor and create the file :file:`ActivityWorker.java`, adding a package declaration and imports according to the :ref:`common steps `. + + .. literalinclude:: swf.java.activity_worker.import.txt + :language: java #. Add the :classname:`ActivityWorker` class to the file, and give it a data member to hold a SWF client that we'll use to interact with |SWF|: - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/ActivityWorker.java + .. literalinclude:: swf.java.activity_worker.client.txt :language: java - :lines: 22-24, 75 #. Add the method that we'll use as an activity: - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/ActivityWorker.java + .. literalinclude:: swf.java.activity_worker.sayHello.txt :language: java - :lines: 26-28 :dedent: 4 The activity simply takes a string, combines it into a greeting and returns the result. Although @@ -341,9 +334,8 @@ We'll implement a simple activity worker that drives a single activity. #. Add a :methodname:`main` method that we'll use as the activity task polling method. We'll start it by adding some code to poll the task list for activity tasks: - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/ActivityWorker.java + .. literalinclude:: swf.java.activity_worker.poll_method.txt :language: java - :lines: 30-42, 74 :dedent: 4 The activity receives tasks from |SWF| by calling the SWF client's @@ -358,10 +350,9 @@ We'll implement a simple activity worker that drives a single activity. :methodname:`main` method, right after the code that polls for the task and retrieves its task token. - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/ActivityWorker.java + .. literalinclude:: swf.java.activity_worker.process_tasks.txt :language: java - :lines: 44-72 - :dedent: 12 + :dedent: 8 If the task token is not :code-java:`null`, then we can start running the activity method (:methodname:`sayHello`), providing it with the input data that was sent with the task. @@ -397,26 +388,23 @@ schedule a new activity or not) and takes an appropriate action (such as schedul #. Add a few additional imports to the file: - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/WorkflowWorker.java + .. literalinclude:: swf.java.workflow_worker.import.txt :language: java - :lines: 21-23 #. Declare the :classname:`WorkflowWorker` class, and create an instance of the :aws-java-class:`AmazonSimpleWorkflowClient ` class used to access SWF methods. - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/WorkflowWorker.java + .. literalinclude:: swf.java.workflow_worker.client.txt :language: java - :lines: 25-27, 139 #. Add the :methodname:`main` method. The method loops continuously, polling for decision tasks using the SWF client's :methodname:`pollForDecisionTask` method. The :aws-java-class:`PollForDecisionTaskRequest ` provides the details. - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/WorkflowWorker.java + .. literalinclude:: swf.java.workflow_worker.main.txt :language: java - :lines: 29-52 :dedent: 4 Once a task is received, we call its :methodname:`getTaskToken` method, which returns a string @@ -428,9 +416,8 @@ schedule a new activity or not) and takes an appropriate action (such as schedul #. Add the :methodname:`executeDecisionTask` method, taking the task token (a :classname:`String`) and the :classname:`HistoryEvent` list. - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/WorkflowWorker.java + .. literalinclude:: swf.java.workflow_worker.execute_decision_task_token.txt :language: java - :lines: 60-67, 138 :dedent: 4 We also set up some data members to keep track of things such as: @@ -447,9 +434,8 @@ schedule a new activity or not) and takes an appropriate action (such as schedul objects that were sent with the task, based on the event type reported by the :methodname:`getEventType` method. - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/WorkflowWorker.java + .. literalinclude:: swf.java.workflow_worker.execute_decision_task_history_events.txt :language: java - :lines: 69-102 :dedent: 8 For the purposes of our workflow, we are most interested in: @@ -480,9 +466,8 @@ schedule a new activity or not) and takes an appropriate action (such as schedul #. After the :code-java:`switch` statement, add more code to respond with an appropriate *decision* based on the task that was received. - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/WorkflowWorker.java + .. literalinclude:: swf.java.workflow_worker.task_decision.txt :language: java - :lines: 104-132 :dedent: 8 * If the activity hasn't been scheduled yet, we respond with a :classname:`ScheduleActivityTask` @@ -505,9 +490,8 @@ schedule a new activity or not) and takes an appropriate action (such as schedul processing the task. Add this code at the end of the :methodname:`executeDecisionTask` method that we've been writing: - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/WorkflowWorker.java + .. literalinclude:: swf.java.workflow_worker.return_decision_objects.txt :language: java - :lines: 134-138 :dedent: 8 The SWF client's :methodname:`respondDecisionTaskCompleted` method takes the task token that @@ -524,9 +508,8 @@ Finally, we'll write some code to start the workflow execution. #. Add the :classname:`WorkflowStarter` class: - .. literalinclude:: example_code/swf/src/main/java/aws/example/helloswf/WorkflowStarter.java + .. literalinclude:: swf.java.workflow_starter.complete.txt :language: java - :lines: 22- The :classname:`WorkflowStarter` class consists of a single method, :methodname:`main`, which takes an optional argument passed on the command-line as input data for the workflow. @@ -597,7 +580,7 @@ applications. java -cp target/helloswf-1.0.jar:/path/to/sdk/lib/*:/path/to/sdk/third-party/lib/* \ example.swf.hello.HelloTypes -The style that you use is up to you. If you had no trouble building the code, buth then try to run +The style that you use is up to you. If you had no trouble building the code, both then try to run the examples and get a series of "NoClassDefFound" errors, it is likely because the classpath is set incorrectly. diff --git a/doc_source/tutorial-spot-adv-java.rst b/doc_source/tutorial-spot-adv-java.rst index 58b817d..2d8a13a 100644 --- a/doc_source/tutorial-spot-adv-java.rst +++ b/doc_source/tutorial-spot-adv-java.rst @@ -16,9 +16,9 @@ Tutorial: Advanced |EC2| Spot Request Management ################################################ -|EC2| spot instances allow you to bid on unused |EC2| capacity and run those instances for as long +|EC2| Spot Instances allow you to bid on unused |EC2| capacity and run those instances for as long as your bid exceeds the current *spot price*. |EC2| changes the spot price periodically based on -supply and demand. For more information about spot instances, see :ec2-ug:`Spot Instances +supply and demand. For more information about Spot Instances, see :ec2-ug:`Spot Instances ` in the |EC2-ug|. @@ -139,7 +139,7 @@ sample. Note you only need to run this application once to create a new security .. _tutor-spot-adv-req-opts: -Detailed spot instance request creation options +Detailed Spot Instance request creation options =============================================== As we explained in :doc:`tutorial-spot-instances-java`, you need to build your request with an @@ -149,7 +149,7 @@ Let's start by creating a :code:`RequestSpotInstanceRequest` object. The request number of instances you want and the bid price. Additionally, we need to set the :code:`LaunchSpecification` for the request, which includes the instance type, AMI ID, and security group you want to use. After the request is populated, we call the :code:`requestSpotInstances` -method on the :code:`AmazonEC2Client` object. An example of how to request a Spot instance follows. +method on the :code:`AmazonEC2Client` object. An example of how to request a Spot Instance follows. (The following code is the same as what we used in the first tutorial.) @@ -265,13 +265,13 @@ period is shown in the following code. .. _tutor-spot-adv-grouping: -Grouping your |EC2| spot instance requests +Grouping your |EC2| Spot Instance requests ========================================== -You have the option of grouping your Spot instance requests in several different ways. We'll look at +You have the option of grouping your Spot Instance requests in several different ways. We'll look at the benefits of using launch groups, Availability Zone groups, and placement groups. -If you want to ensure your Spot instances are all launched and terminated together, then you have +If you want to ensure your Spot Instances are all launched and terminated together, then you have the option to leverage a launch group. A launch group is a label that groups a set of bids together. All instances in a launch group are started and terminated together. Note, if instances in a launch group have already been fulfilled, there is no guarantee that new instances launched with the same @@ -396,7 +396,7 @@ example shows you how to set an Availability Zone. ec2.requestSpotInstances(requestRequest); Lastly, you can specify a :emphasis:`placement group` if you are using High Performance Computing -(HPC) Spot instances, such as cluster compute instances or cluster GPU instances. Placement groups +(HPC) Spot Instances, such as cluster compute instances or cluster GPU instances. Placement groups provide you with lower latency and high-bandwidth connectivity between the instances. An example of how to set a placement group follows. @@ -452,7 +452,7 @@ class. How to persist a root partition after interruption or termination ================================================================= -One of the easiest ways to manage interruption of your Spot instances is to ensure that your data is +One of the easiest ways to manage interruption of your Spot Instances is to ensure that your data is checkpointed to an |EBSlong| (|EBS|) volume on a regular cadence. By checkpointing periodically, if there is an interruption you will lose only the data created since the last checkpoint (assuming no other non-idempotent actions are performed in between). To make this process easier, you can @@ -528,7 +528,7 @@ that we include in the launch specification. Assuming you wanted to re-attach this volume to your instance on startup, you can also use the block device mapping settings. Alternatively, if you attached a non-root partition, you can specify the -Amazon EBS volumes you want to attach to your Spot instance after it resumes. You do this simply by +Amazon EBS volumes you want to attach to your Spot Instance after it resumes. You do this simply by specifying a snapshot ID in your :code:`EbsBlockDevice` and alternative device name in your :code:`BlockDeviceMapping` objects. By leveraging block device mappings, it can be easier to bootstrap your instance. @@ -605,7 +605,7 @@ Canceling spot requests and terminating instances Canceling a spot request ------------------------ -To cancel a spot instance request, call :methodname:`cancelSpotInstanceRequests` on the EC2 client +To cancel a Spot Instance request, call :methodname:`cancelSpotInstanceRequests` on the EC2 client with a :aws-java-class:`CancelSpotInstanceRequestsRequest ` object. @@ -613,10 +613,10 @@ with a :aws-java-class:`CancelSpotInstanceRequestsRequest :lines: 18-27 :language: java -Terminating spot instances +Terminating Spot Instances -------------------------- -You can terminate any spot instances that are running by passing their IDs to the EC2 client's +You can terminate any Spot Instances that are running by passing their IDs to the EC2 client's :methodname:`terminateInstances()` method. .. literalinclude:: snippets/ec2/cancel-terminate-spot-request.java diff --git a/doc_source/tutorial-spot-instances-java.rst b/doc_source/tutorial-spot-instances-java.rst index 71341ec..31d9ea5 100644 --- a/doc_source/tutorial-spot-instances-java.rst +++ b/doc_source/tutorial-spot-instances-java.rst @@ -17,11 +17,11 @@ Tutorial: |EC2| Spot Instances Overview ======== -Spot Instances allow you to bid on unused |EC2long| (|EC2|) capacity and run the acquired instances -for as long as your bid exceeds the current :emphasis:`Spot Price`. |EC2| changes the Spot Price -periodically based on supply and demand, and customers whose bids meet or exceed it gain access to -the available Spot Instances. Like On-Demand Instances and Reserved Instances, Spot Instances -provide you another option for obtaining more compute capacity. +Spot Instances enable you to bid on unused |EC2long| (|EC2|) capacity t up to 90% versus the On-Demand +Instance price and run the acquired instances for as long as your bid exceeds the current +:emphasis:`Spot Price`. |EC2| changes the Spot Price periodically based on supply and demand, and customers +whose bids meet or exceed it gain access to the available Spot Instances. Like On-Demand Instances and +Reserved Instances, Spot Instances provide you another option for obtaining more compute capacity. Spot Instances can significantly lower your |EC2| costs for batch processing, scientific research, image processing, video encoding, data and web crawling, financial analysis, and testing. @@ -188,7 +188,7 @@ always determine the latest version AMI by following these steps: Alternatively, you can use the :code:`DescribeImages` API, but leveraging that command is outside the scope of this tutorial. -There are many ways to approach bidding for Spot instances; to get a broad overview of the various +There are many ways to approach bidding for Spot Instances; to get a broad overview of the various approaches you should view the `Bidding for Spot Instances `_ video. However, to get started, we'll describe three common strategies: bid to ensure cost is less than on-demand pricing; @@ -207,10 +207,10 @@ quickly as possible. On-Demand price), anticipating that your one-time Spot request would most likely be fulfilled and run for enough consecutive compute time to complete the job. - * Or, you could bid at the lower end of the price range, and plan to combine many instances - launched over time through a persistent request. The instances would run long enough--in - aggregate--to complete the job at an even lower total cost. (We will explain how to automate - this task later in this tutorial.) + * Or, you could specify the amount you are willing to pay for Spot Instances as a % of the On-Demand Instance price + , and plan to combine many instances launched over time through a persistent request. If the specified + price is exceeded, then the Spot Instance will terminate. (We will explain how to automate this task + later in this tutorial.) * :emphasis:`Pay No More than the Value of the Result` You have a data processing job to run. You understand the value of the job's results well enough to know how much they are worth in terms @@ -228,7 +228,10 @@ quickly as possible. After you choose your bid price, you are ready to request a Spot Instance. For the purposes of this tutorial, we will bid the On-Demand price ($0.03) to maximize the chances that the bid will be fulfilled. You can determine the types of available instances and the On-Demand prices for instances -by going to Amazon EC2 Pricing page. To request a Spot Instance, you simply need to build your +by going to Amazon EC2 Pricing page. While a Spot Instancee is running, you pay the Spot price that's in effect for +the time period your instances are running. Spot Instance prices are set by Amazon EC2 and adjust gradually based +on long-term trends in supply and demand for Spot Instance capacity. You can also specify the amount you are willing +to pay for a Spot Instance as a % of the On-Demand Instance price.To request a Spot Instance, you simply need to build your request with the parameters you chose earlier. We start by creating a :code:`RequestSpotInstanceRequest` object. The request object requires the number of instances you want to start and the bid price. Additionally, you need to set the :code:`LaunchSpecification` for diff --git a/doc_source/welcome.rst b/doc_source/welcome.rst index 256d4d3..e4215e5 100644 --- a/doc_source/welcome.rst +++ b/doc_source/welcome.rst @@ -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 `_