diff --git a/.gitignore b/.gitignore index 71055ef..c7b77bf 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ README.html doc_build/ doc_output/ build_dependencies/ +*.swp diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..39d4a99 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Guidelines for contributing + +Thank you for your interest in contributing to AWS documentation! We greatly value feedback and contributions from our community. + +Please read through this document before you submit any pull requests or issues. It will help us work together more effectively. + +## What to expect when you contribute + +When you submit a pull request, our team is notified and will respond as quickly as we can. We'll do our best to work with you to ensure that your pull request adheres to our style and standards. If we merge your pull request, we might make additional edits later for style or clarity. + +The AWS documentation source files on GitHub aren't published directly to the official documentation website. If we merge your pull request, we'll publish your changes to the documentation website as soon as we can, but they won't appear immediately or automatically. + +We look forward to receiving your pull requests for: + +* New content you'd like to contribute (such as new code samples or tutorials) +* Inaccuracies in the content +* Information gaps in the content that need more detail to be complete +* Typos or grammatical errors +* Suggested rewrites that improve clarity and reduce confusion + +**Note:** We all write differently, and you might not like how we've written or organized something currently. We want that feedback. But please be sure that your request for a rewrite is supported by the previous criteria. If it isn't, we might decline to merge it. + +## How to contribute + +To contribute, send us a pull request. For small changes, such as fixing a typo or adding a link, you can use the [GitHub Edit Button](https://blog.github.com/2011-04-26-forking-with-the-edit-button/). For larger changes: + +1. [Fork the repository](https://help.github.com/articles/fork-a-repo/). +2. In your fork, make your change in a branch that's based on this repo's **master** branch. +3. Commit the change to your fork, using a clear and descriptive commit message. +4. [Create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/), answering any questions in the pull request form. + +Before you send us a pull request, please be sure that: + +1. You're working from the latest source on the **master** branch. +2. You check [existing open](https://github.com/awsdocs/aws-java-developer-guide/pulls), and [recently closed](https://github.com/awsdocs/aws-java-developer-guide/pulls?q=is%3Apr+is%3Aclosed), pull requests to be sure that someone else hasn't already addressed the problem. +3. You [create an issue](https://github.com/awsdocs/aws-java-developer-guide/issues/new) before working on a contribution that will take a significant amount of your time. + +For contributions that will take a significant amount of time, [open a new issue](https://github.com/awsdocs/aws-java-developer-guide/issues/new) to pitch your idea before you get started. Explain the problem and describe the content you want to see added to the documentation. Let us know if you'll write it yourself or if you'd like us to help. We'll discuss your proposal with you and let you know whether we're likely to accept it. We don't want you to spend a lot of time on a contribution that might be outside the scope of the documentation or that's already in the works. + +## Finding contributions to work on + +If you'd like to contribute, but don't have a project in mind, look at the [open issues](https://github.com/awsdocs/aws-java-developer-guide/issues) in this repository for some ideas. Any issues with the [help wanted](https://github.com/awsdocs/aws-java-developer-guide/labels/help%20wanted) or [enhancement](https://github.com/awsdocs/aws-java-developer-guide/labels/enhancement) labels are a great place to start. + +In addition to written content, we really appreciate new examples and code samples for our documentation, such as examples for different platforms or environments, and code samples in additional languages. + +## Code of conduct + +This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). For more information, see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact [opensource-codeofconduct@amazon.com](mailto:opensource-codeofconduct@amazon.com) with any additional questions or comments. + +## Security issue notifications + +If you discover a potential security issue, please notify AWS Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public issue on GitHub. + +## Licensing + +See the [LICENSE](https://github.com/awsdocs/aws-java-developer-guide/blob/master/LICENSE) file for this project's licensing. We will ask you to confirm the licensing of your contribution. We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. diff --git a/LICENSE b/LICENSE index 3dbca7b..7785b90 100644 --- a/LICENSE +++ b/LICENSE @@ -1,282 +1,152 @@ -###################################################################################### -Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License -###################################################################################### +Creative Commons Attribution-ShareAlike 4.0 International Public License -By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and -conditions of this Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public -License ("Public License"). To the extent this Public License may be interpreted as a contract, You -are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, -and the Licensor grants You such rights in consideration of benefits the Licensor receives from -making the Licensed Material available under these terms and conditions. +By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. Section 1 – Definitions. -======================== - -a. Adapted Material means material subject to Copyright and Similar Rights that is derived from or - based upon the Licensed Material and in which the Licensed Material is translated, altered, - arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright - and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed - Material is a musical work, performance, or sound recording, Adapted Material is always produced - where the Licensed Material is synched in timed relation with a moving image. - -b. Adapter's License means the license You apply to Your Copyright and Similar Rights in Your - contributions to Adapted Material in accordance with the terms and conditions of this Public - License. - -c. BY-NC-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, - approved by Creative Commons as essentially the equivalent of this Public License. - -d. Copyright and Similar Rights means copyright and/or similar rights closely related to copyright - including, without limitation, performance, broadcast, sound recording, and Sui Generis Database - Rights, without regard to how the rights are labeled or categorized. For purposes of this Public - License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. - -e. Effective Technological Measures means those measures that, in the absence of proper authority, - may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright - Treaty adopted on December 20, 1996, and/or similar international agreements. - -f. Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation - to Copyright and Similar Rights that applies to Your use of the Licensed Material. - -g. License Elements means the license attributes listed in the name of a Creative Commons Public - License. The License Elements of this Public License are Attribution, NonCommercial, and - ShareAlike. - -h. Licensed Material means the artistic or literary work, database, or other material to which the - Licensor applied this Public License. - -i. Licensed Rights means the rights granted to You subject to the terms and conditions of this - Public License, which are limited to all Copyright and Similar Rights that apply to Your use of - the Licensed Material and that the Licensor has authority to license. - -j. Licensor means the individual(s) or entity(ies) granting rights under this Public License. - -k. NonCommercial means not primarily intended for or directed towards commercial advantage or - monetary compensation. For purposes of this Public License, the exchange of the Licensed Material - for other material subject to Copyright and Similar Rights by digital file-sharing or similar - means is NonCommercial provided there is no payment of monetary compensation in connection with - the exchange. -l. Share means to provide material to the public by any means or process that requires permission - under the Licensed Rights, such as reproduction, public display, public performance, - distribution, dissemination, communication, or importation, and to make material available to the - public including in ways that members of the public may access the material from a place and at a - time individually chosen by them. -m. Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of - the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, - as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the - world. - -n. You means the individual or entity exercising the Licensed Rights under this Public License. Your - has a corresponding meaning. + + a. Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, approved by Creative Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. + + e. Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License. + + i. Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights under this Public License. + + k. Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. Section 2 – Scope. -================== - -a. License grant. - - 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a - worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the - Licensed Rights in the Licensed Material to: - - A. reproduce and Share the Licensed Material, in whole or in part, for NonCommercial purposes - only; and - - B. produce, reproduce, and Share Adapted Material for NonCommercial purposes only. - - 2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply - to Your use, this Public License does not apply, and You do not need to comply with its terms - and conditions. - - 3. Term. The term of this Public License is specified in Section 6(a). - - 4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise - the Licensed Rights in all media and formats whether now known or hereafter created, and to - make technical modifications necessary to do so. The Licensor waives and/or agrees not to - assert any right or authority to forbid You from making technical modifications necessary to - exercise the Licensed Rights, including technical modifications necessary to circumvent - Effective Technological Measures. For purposes of this Public License, simply making - modifications authorized by this Section 2(a)(4) never produces Adapted Material. - - 5. Downstream recipients. - - A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material - automatically receives an offer from the Licensor to exercise the Licensed Rights under the - terms and conditions of this Public License. - - B. Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material - from You automatically receives an offer from the Licensor to exercise the Licensed Rights - in the Adapted Material under the conditions of the Adapter’s License You apply. - - C. No downstream restrictions. You may not offer or impose any additional or different terms - or conditions on, or apply any Effective Technological Measures to, the Licensed Material - if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed - Material. - - D. No endorsement. Nothing in this Public License constitutes or may be construed as - permission to assert or imply that You are, or that Your use of the Licensed Material is, - connected with, or sponsored, endorsed, or granted official status by, the Licensor or - others designated to receive attribution as provided in Section 3(a)(1)(A)(i). - -b. Other rights. - - 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor - are publicity, privacy, and/or other similar personality rights; however, to the extent - possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor - to the limited extent necessary to allow You to exercise the Licensed Rights, but not - otherwise. - - 2. Patent and trademark rights are not licensed under this Public License. - - 3. To the extent possible, the Licensor waives any right to collect royalties from You for the - exercise of the Licensed Rights, whether directly or through a collecting society under any - voluntary or waivable statutory or compulsory licensing scheme. In all other cases the - Licensor expressly reserves any right to collect such royalties, including when the Licensed - Material is used other than for NonCommercial purposes. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: + + A. reproduce and Share the Licensed Material, in whole or in part; and + + B. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. + + 3. Term. The term of this Public License is specified in Section 6(a). + + 4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. + + 5. Downstream recipients. + + A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. + + B. Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply. + + C. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. + + 6. No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this Public License. + + 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. Section 3 – License Conditions. -=============================== Your exercise of the Licensed Rights is expressly made subject to the following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified form), You must: -a. Attribution. - - 1. If You Share the Licensed Material (including in modified form), You must: + A. retain the following if it is supplied by the Licensor with the Licensed Material: - A. retain the following if it is supplied by the Licensor with the Licensed Material: + i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); - i. identification of the creator(s) of the Licensed Material and any others designated to - receive attribution, in any reasonable manner requested by the Licensor (including by - pseudonym if designated); + ii. a copyright notice; - ii. a copyright notice; + iii. a notice that refers to this Public License; - iii. a notice that refers to this Public License; + iv. a notice that refers to the disclaimer of warranties; - iv. a notice that refers to the disclaimer of warranties; + v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; - v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; + B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and - B. indicate if You modified the Licensed Material and retain an indication of any previous - modifications; and - - C. indicate the Licensed Material is licensed under this Public License, and include the text - of, or the URI or hyperlink to, this Public License. - - 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the - medium, means, and context in which You Share the Licensed Material. For example, it may be - reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that - includes the required information. - - 3. If requested by the Licensor, You must remove any of the information required by Section - 3(a)(1)(A) to the extent reasonably practicable. - -b. ShareAlike. - - In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the - following conditions also apply. - - 1. The Adapter’s License You apply must be a Creative Commons license with the same License - Elements, this version or later, or a BY-NC-SA Compatible License. - - 2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You - may satisfy this condition in any reasonable manner based on the medium, means, and context in - which You Share Adapted Material. - - 3. You may not offer or impose any additional or different terms or conditions on, or apply any - Effective Technological Measures to, Adapted Material that restrict exercise of the rights - granted under the Adapter's License You apply. + C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. + + 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. + + b. ShareAlike.In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply. + + 1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply. Section 4 – Sui Generis Database Rights. -======================================== -Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed -Material: - -a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, - and Share all or a substantial portion of the contents of the database for NonCommercial purposes - only; - -b. if You include all or a substantial portion of the database contents in a database in which You - have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights - (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); - and - -c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of - the contents of the database. - -For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under -this Public License where the Licensed Rights include other Copyright and Similar Rights. +Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database; + + b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and + + c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. +For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. Section 5 – Disclaimer of Warranties and Limitation of Liability. -================================================================= - -a. Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor - offers the Licensed Material as-is and as-available, and makes no representations or warranties - of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This - includes, without limitation, warranties of title, merchantability, fitness for a particular - purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or - absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not - allowed in full or in part, this disclaimer may not apply to You. - -b. To the extent possible, in no event will the Licensor be liable to You on any legal theory - (including, without limitation, negligence) or otherwise for any direct, special, indirect, - incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages - arising out of this Public License or use of the Licensed Material, even if the Licensor has been - advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of - liability is not allowed in full or in part, this limitation may not apply to You. - -c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a - manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver - of all liability. + + a. Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You. + + b. To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You. + + c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. Section 6 – Term and Termination. -================================= - -a. This Public License applies for the term of the Copyright and Similar Rights licensed here. - However, if You fail to comply with this Public License, then Your rights under this Public - License terminate automatically. - -b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: - - 1. automatically as of the date the violation is cured, provided it is cured within 30 days of - Your discovery of the violation; or - - 2. upon express reinstatement by the Licensor. - - For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to - seek remedies for Your violations of this Public License. - -c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate - terms or conditions or stop distributing the Licensed Material at any time; however, doing so - will not terminate this Public License. - -d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. + + a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or + + 2. upon express reinstatement by the Licensor. + + c. For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. + + d. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. + + e. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. Section 7 – Other Terms and Conditions. -======================================= - -a. The Licensor shall not be bound by any additional or different terms or conditions communicated - by You unless expressly agreed. - -b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein - are separate from and independent of the terms and conditions of this Public License. + + a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. Section 8 – Interpretation. -=========================== - -a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, - reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could - lawfully be made without permission under this Public License. - -b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall - be automatically reformed to the minimum extent necessary to make it enforceable. If the - provision cannot be reformed, it shall be severed from this Public License without affecting the - enforceability of the remaining terms and conditions. - -c. No term or condition of this Public License will be waived and no failure to comply consented to - unless expressly agreed to by the Licensor. - -d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver - of, any privileges and immunities that apply to the Licensor or You, including from the legal - processes of any jurisdiction or authority. - + + a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. + + c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. + + d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. diff --git a/LICENSE-SAMPLECODE b/LICENSE-SAMPLECODE new file mode 100644 index 0000000..7e0bd89 --- /dev/null +++ b/LICENSE-SAMPLECODE @@ -0,0 +1,14 @@ +Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. + +Permission is hereby granted, free of charge, to any person obtaining a copy of this +software and associated documentation files (the "Software"), to deal in the Software +without restriction, including without limitation the rights to use, copy, modify, +merge, publish, distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, +INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/LICENSE-SUMMARY b/LICENSE-SUMMARY new file mode 100644 index 0000000..fa2e570 --- /dev/null +++ b/LICENSE-SUMMARY @@ -0,0 +1,5 @@ +Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. + +The documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the LICENSE file. + +The sample code within this documentation is made available under a modified MIT license. See the LICENSE-SAMPLECODE file. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..5e90b8c --- /dev/null +++ b/Makefile @@ -0,0 +1,22 @@ +# -*- coding: utf-8 -*- +# +# Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. +# +# This file is licensed under the Apache License, Version 2.0 (the "License"). +# You may not use this file except in compliance with the License. A copy of the +# License is located at +# +# http://aws.amazon.com/apache2.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. +# +# ------------------------------------------------------------------ +# A simple Makefile to build docs with 'make'. +# ------------------------------------------------------------------ +all: + python build_docs.py + +html: + python build_docs.py html diff --git a/README.rst b/README.rst index 4c80a30..7ac8f27 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,13 +12,18 @@ aws-java-developer-guide ######################## -This repository contains source content for the official `AWS SDK for Java Developer Guide`_. The -source code for the `AWS SDK for Java`_ is also on GitHub, at https://github.com/aws/aws-sdk-java/. +This repository contains source content for the official `AWS Java Developer Guide`_. The source +code for the `AWS SDK for Java`_ is also on GitHub, at https://github.com/aws/aws-sdk-java/. The guide content is written in reStructuredText_ and built using Sphinx_. It relies upon content which is provided in the AWS documentation team's `shared content`_ and `SDK examples`_ repositories. +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/. +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`_. Reporting issues ================ @@ -65,6 +70,22 @@ The build process will automatically download a snapshot of its dependencies, co ``doc_build`` directory and will then generate output into the ``doc_output`` directory. +Code examples in the documentation +---------------------------------- + +The code examples featured in this documentation can be found in a separate repository: +`aws-doc-sdk-examples `_. Full +code and build files are included, so you can build and run any of the provided examples yourself. + +In addition to examples in Java, you'll also find examples for each of the other AWS SDKs. If you +find issues with any of the examples, you can submit issues or fork the repository and submit a pull +request! + +The code examples are provided under the *Apache 2.0* open source license. See the example +repository's `README `_ for +more details. + + Copyright and license ===================== @@ -83,7 +104,8 @@ repository. .. ================================================================================= .. _`available sphinx builders`: http://www.sphinx-doc.org/en/stable/builders.html -.. _`aws sdk for java developer guide`: http://docs.aws.amazon.com/java-sdk/latest/developer-guide/welcome.html +.. _`aws java developer guide`: http://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/welcome.html +.. _`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`: https://aws.amazon.com/sdk-for-java/ .. _`forking the repository`: https://help.github.com/articles/fork-a-repo/ .. _`pull request`: https://help.github.com/articles/using-pull-requests/ @@ -94,4 +116,3 @@ repository. .. _restructuredtext: http://docutils.sourceforge.net/rst.html .. _sphinx: http://www.sphinx-doc.org/en/stable/ .. _substitutions: http://www.sphinx-doc.org/en/stable/rest.html#substitutions - diff --git a/build_docs.py b/build_docs.py index cb2cda3..b21443d 100755 --- a/build_docs.py +++ b/build_docs.py @@ -1,7 +1,7 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- # -# Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +# Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. # # This file is licensed under the Apache License, Version 2.0 (the "License"). # You may not use this file except in compliance with the License. A copy of the diff --git a/doc_source/.gitignore b/doc_source/.gitignore index 5193fae..4423b35 100644 --- a/doc_source/.gitignore +++ b/doc_source/.gitignore @@ -1 +1,3 @@ example_code +.vscode +_build \ No newline at end of file diff --git a/doc_source/_includes.txt b/doc_source/_includes.txt index 31d44d5..ce7ff73 100644 --- a/doc_source/_includes.txt +++ b/doc_source/_includes.txt @@ -1,16 +1,34 @@ +.. 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. + .. project-specific includes for this project. -.. |sdk-java-dl| replace:: http://sdk-for-java.amazonwebservices.com/latest/aws-java-sdk.zip +.. |sdk-java-dl| replace:: https://sdk-for-java.amazonwebservices.com/latest/aws-java-sdk.zip .. |sdk-java-github| replace:: AWS SDK for Java (GitHub) -.. _sdk-java-github: http://github.com/aws/aws-sdk-java +.. _sdk-java-github: https://github.com/aws/aws-sdk-java .. |mvn| replace:: Maven .. |mvnlong| replace:: Apache |mvn| -.. _Gradle: http://gradle.com/ -.. _Maven: http://maven.apache.org/ +.. _Gradle: https://gradle.com/ +.. _Maven: https://maven.apache.org/ .. _mvn: Maven_ .. _mvnlong: Maven_ -.. |s3client| replace:: :java-api:`AmazonS3 ` +.. |cwclient| replace:: :aws-java-class:`AmazonCloudWatchClient ` +.. |cweclient| replace:: :aws-java-class:`AmazonCloudWatchEventsClient ` +.. |ddbclient| replace:: :aws-java-class:`AmazonDynamoDB ` +.. |ec2client| replace:: :aws-java-class:`AmazonEC2Client ` +.. |iamclient| replace:: :aws-java-class:`AmazonIdentityManagementClient ` +.. |pinpointclient| replace:: :aws-java-class:`AmazonPinpointClient ` +.. |s3client| replace:: :aws-java-class:`AmazonS3 ` +.. |sqsclient| replace:: :aws-java-class:`AmazonSQS ` +.. |xfermgr| replace:: :aws-java-class:`TransferManager ` diff --git a/doc_source/basics-async.rst b/doc_source/basics-async.rst index f16185d..3c29ca5 100644 --- a/doc_source/basics-async.rst +++ b/doc_source/basics-async.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,18 +12,17 @@ Asynchronous Programming ######################## +.. meta:: + :description: How asynchronous programming works in the AWS SDK for Java and best practices for + handling exceptions + You can use either *synchronous* or *asynchronous* methods to call operations on AWS services. Synchronous methods block your thread's execution until the client receives a response from the service. Asynchronous methods return immediately, giving control back to the calling thread without waiting for a response. -Since an asynchronous method returns before a response is available, you need a way to get the -response when it's ready. The |sdk-java| provides two methods: *Futures* and *callback methods*. - -.. contents:: - :local: - :depth: 2 - +Because an asynchronous method returns before a response is available, you need a way to get the +response when it's ready. The |sdk-java| provides two ways: *Future objects* and *callback methods*. .. _basics-async-future: @@ -31,16 +30,17 @@ Java Futures ============ Asynchronous methods in the |sdk-java| return a :javase-ref:`Future ` -object that will contain the results of the asynchronous operation *in the future*. +object that contains the results of the asynchronous operation *in the future*. -Call the Future's :methodname:`isDone()` method to see if the service has provided a response object -yet. Once the response is ready, you can get the response object by calling the Future's -:methodname:`get()` method. You can use this mechanism to periodically poll for the asynchronous -operation's results while your application continues to work on other things. +Call the :code-java:`Future` :methodname:`isDone()` method to see if the service has provided a +response object yet. When the response is ready, you can get the response object by calling the +:code-java:`Future` :methodname:`get()` method. You can use this mechanism to periodically poll for +the asynchronous operation's results while your application continues to work on other things. -Here is an example of an asynchronous operation that calls a |LAM| function, receiving a Future that -can hold an :java-api:`InvokeResult ` object. The -:classname:`InvokeResult` object is retrieved only after :methodname:`isDone()` is ``true``: +Here is an example of an asynchronous operation that calls a |LAM| function, receiving a +:code-java:`Future` that can hold an :aws-java-class:`InvokeResult +` object. The :classname:`InvokeResult` object is retrieved only +after :methodname:`isDone()` is ``true``. .. literalinclude:: snippets/lambda_invoke_example/src/main/java/example/lambda/InvokeLambdaFunctionAsync.java :language: java @@ -51,14 +51,14 @@ can hold an :java-api:`InvokeResult ` object Asynchronous Callbacks ====================== -In addition to using Java Futures to monitor the status of asynchronous requests, the SDK also -allows you to implement a class that uses the :java-api:`AsyncHandler ` -interface, which provides two methods that are called depending on how the request completed: -:methodname:`onSuccess` and :methodname:`onError`. +In addition to using the Java :code-java:`Future` object to monitor the status of asynchronous +requests, the SDK also enables you to implement a class that uses the :aws-java-class:`AsyncHandler +` interface. :code-java:`AsyncHandler` provides two methods that are called +depending on how the request completed: :methodname:`onSuccess` and :methodname:`onError`. The major advantage of the callback interface approach is that it frees you from having to poll the -Future object to find out when the request has completed. Instead, your code can immediately start -its next activity, and rely on the SDK to call your handler at the right time. +:code-java:`Future` object to find out when the request has completed. Instead, your code can +immediately start its next activity, and rely on the SDK to call your handler at the right time. .. literalinclude:: snippets/lambda_invoke_example/src/main/java/example/lambda/InvokeLambdaFunctionCallback.java :language: java @@ -76,30 +76,28 @@ Callback Execution Your implementation of :classname:`AsyncHandler` is executed inside the thread pool owned by the asynchronous client. Short, quickly executed code is most appropriate inside your :classname:`AsyncHandler` implementation. Long-running or blocking code inside your handler methods -can cause contention for the thread pool used by the asynchronous client and can prevent the client -from being able to execute requests. If you have a long-running task that needs to begin from a -callback, have the callback run its task in a new thread or in a thread pool managed by your -application. +can cause contention for the thread pool used by the asynchronous client, and can prevent the client +from executing requests. If you have a long-running task that needs to begin from a callback, have +the callback run its task in a new thread or in a thread pool managed by your application. Thread Pool Configuration ------------------------- -The asynchronous clients in the SDK provide a default thread pool that should work for most +The asynchronous clients in the |sdk-java| provide a default thread pool that should work for most applications. You can implement a custom :javase-ref:`ExecutorService -` and pass it to |sdk-java| asynchronous clients if you want -more control over how the thread pools are managed. +` and pass it to |sdk-java| asynchronous clients for more +control over how the thread pools are managed. -For example, you could provide a :classname:`ExecutorService` implementation that uses a custom +For example, you could provide an :classname:`ExecutorService` implementation that uses a custom :javase-ref:`ThreadFactory ` to control how threads in the pool are named, or to log additional information about thread usage. -Amazon S3 Asynchronous Access ------------------------------ - -The :java-api:`TransferManager ` class in the SDK -offers asynchronous support for working with the |S3long| (|S3|). :classname:`TransferManager` -manages asynchronous uploads and downloads, provides detailed progress reporting on transfers, and -supports callbacks into different events. +|S3| Asynchronous Access +------------------------ +The :aws-java-class:`TransferManager ` class in the +SDK offers asynchronous support for working with the |S3|. :classname:`TransferManager` manages +asynchronous uploads and downloads, provides detailed progress reporting on transfers, and supports +callbacks into different events. diff --git a/doc_source/basics.rst b/doc_source/basics.rst index 4431659..83cf334 100644 --- a/doc_source/basics.rst +++ b/doc_source/basics.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,22 +8,31 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -################# -|sdk-java| Basics -################# +#################### +Using the |sdk-java| +#################### -This section provides important general information about programming with the |sdk-java|. -Information in this section applies to all services that you might be using with the |sdk-java|. +.. meta:: + :description: Programming information for the AWS SDK for Java + :keywords: -For information that is specific to a particular service (EC2, SWF, etc.), see the -:doc:`prog-services` section. +This section provides important general information about programming with the |sdk-java| that applies +to all services you might use with the SDK. + +For service-specific programming information and examples (for |EC2|, |S3|, |SWF|, etc.), see +:doc:`prog-services`. .. toctree:: :maxdepth: 1 + best-practices creating-clients credentials java-dg-region-selection java-dg-exceptions basics-async java-dg-logging + section-client-configuration + java-dg-access-control + java-dg-jvm-ttl + generating-sdk-metrics diff --git a/doc_source/best-practices.rst b/doc_source/best-practices.rst new file mode 100644 index 0000000..c33d46c --- /dev/null +++ b/doc_source/best-practices.rst @@ -0,0 +1,57 @@ +.. 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. + +###################################################### +Best Practices for AWS Development with the |sdk-java| +###################################################### + +.. meta:: + :description: AWS coding best practices using the AWS SDK for Java. + :keywords: + +The following best practices can help you avoid issues or trouble as you develop AWS applications +with the |sdk-java|. We've organized best practices by service. + +.. best-practices-s3: + +|s3| +==== + +.. _s3-avoid-resetexception: + +Avoid ResetExceptions +--------------------- + +When you upload objects to |s3| by using +streams (either through an |s3client| client or |xfermgr|), you might encounter network +connectivity or timeout issues. By default, the |sdk-java| attempts to retry failed transfers by marking +the input stream before +the start of a transfer and then resetting it before retrying. + +If the stream doesn't support mark and reset, the SDK throws a :aws-java-class:`ResetException` +when there are transient failures and retries are enabled. + +**Best Practice** + +We recommend that you use streams that support mark and reset operations. + +The most reliable way to avoid a :aws-java-class:`ResetException` is to provide data by using a +:javase-ref:`File ` or :javase-ref:`FileInputStream `, which +the |sdk-java| can handle without being constrained by mark and reset limits. + +If the stream isn't a :javase-ref:`FileInputStream ` but does support mark and +reset, you can set the mark limit by using the :methodname:`setReadLimit` method of +:aws-java-class:`RequestClientOptions`. Its default value is 128 KB. Setting the read limit value to +*one byte greater than the size of stream* will reliably avoid a :aws-java-class:`ResetException`. + +For example, if the maximum expected size of a stream is 100,000 bytes, set the read limit to 100,001 +(100,000 + 1) bytes. The mark and reset will always work for 100,000 bytes or less. Be aware that +this might cause some streams to buffer that number of bytes into memory. + 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 ae90c21..c8adbe8 100644 --- a/doc_source/conf.py +++ b/doc_source/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +# Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"). You may not # use this file except in compliance with the License. A copy of the License @@ -121,7 +121,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'alabaster' +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 @@ -373,17 +373,40 @@ extlinks = {} # These URLs make maintaining the extlinks easier. -java_api_url = 'http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/' -javase_api_url = 'http://docs.oracle.com/javase/7/docs/api/' +aws_java_api_url = 'https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/' +javase_api_url = 'https://docs.oracle.com/javase/8/docs/api/' javadoc_f = 'index.html?%s.html' # javadoc link + frames javadoc_nf = '%s.html' # javadoc link - frames # extlinks['role'] = (url_string, term_prepended_by) -extlinks['java-api'] = (java_api_url + 'index.html?com/amazonaws/%s.html', '') -extlinks['java-ref'] = (java_api_url + javadoc_f, '') -extlinks['java-ref-nf'] = (java_api_url + javadoc_nf, '') + +# a generic link to the AWS SDK reference docs. Doesn't work well in a frame. +extlinks['aws-java-ref'] = (aws_java_api_url + 'com/amazonaws/%s', '') + +# a link to a class within the AWS SDK -- can use frames. +extlinks['aws-java-class'] = (aws_java_api_url + (javadoc_f % 'com/amazonaws/%s'), '') + +# links to the Java SE documentation. extlinks['javase-ref'] = (javase_api_url + javadoc_f, '') extlinks['javase-ref-nf'] = (javase_api_url + javadoc_nf, '') -extlinks['sdk-examples-java'] = ( - 'https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java/example_code/s3/src/main/java/aws/example/%s', - '') +# links to examples for a particular service (ex: :sdk-examples-java-s3:`ListTables.java`) +samples_url = 'https://github.com/awsdocs/aws-doc-sdk-examples/' +for svc in [ + 'cloudwatch', + 'cloudwatchevents', + 'dynamodb', + 'ec2', + 'iam', + 's3', + 'sqs', + ]: + extlinks['sdk-examples-java-%s' % svc] = (samples_url + + 'blob/master/java/example_code/{svc}/src/main/java/aws/example/{svc}/'.format(svc=svc) + + '%s', '') + +for svc in [ + 'pinpoint' + ]: + extlinks['sdk-examples-java-%s' % svc] = (samples_url + + 'blob/master/java/example_code/{svc}/src/main/java/com/example/{svc}/'.format(svc=svc) + + '%s', '') diff --git a/doc_source/create-key-pair.rst b/doc_source/create-key-pair.rst index 7d46f77..3e65052 100644 --- a/doc_source/create-key-pair.rst +++ b/doc_source/create-key-pair.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -17,43 +17,43 @@ key pair when you connect to the instance. You can create a key pair or use an e that you've used when launching other instances. For more information, see :ec2-ug:`Amazon EC2 Key Pairs ` in the |EC2-ug|. -**To create a key pair and save the private key** +.. topic:: To create a key pair and save the private key -1. Create and initialize a :java-api:`CreateKeyPairRequest - ` instance. Use the :java-ref:`withKeyName - ` - method to set the key pair name, as follows: + #. Create and initialize a :aws-java-class:`CreateKeyPairRequest + ` instance. Use the :aws-java-ref:`withKeyName + ` + method to set the key pair name, as follows: - .. code-block:: java + .. code-block:: java - CreateKeyPairRequest createKeyPairRequest = new CreateKeyPairRequest(); + CreateKeyPairRequest createKeyPairRequest = new CreateKeyPairRequest(); - createKeyPairRequest.withKeyName(keyName); + createKeyPairRequest.withKeyName(keyName); - .. important:: Key pair names must be unique. If you attempt to create a key pair with the same - key name as an existing key pair, you'll get an exception. + .. important:: Key pair names must be unique. If you attempt to create a key pair with the + same key name as an existing key pair, you'll get an exception. -2. Pass the request object to the :java-ref:`createKeyPair - ` - method. The method returns a :java-api:`CreateKeyPairResult - ` instance, as follows: + #. Pass the request object to the :aws-java-ref:`createKeyPair + ` + method. The method returns a :aws-java-class:`CreateKeyPairResult + ` instance, as follows: - .. code-block:: java + .. code-block:: java - CreateKeyPairResult createKeyPairResult = - amazonEC2Client.createKeyPair(createKeyPairRequest); + CreateKeyPairResult createKeyPairResult = + amazonEC2Client.createKeyPair(createKeyPairRequest); -3. Call the result object's :java-ref:`getKeyPair - ` method to obtain a - :java-api:`KeyPair ` object. Call the :code:`KeyPair` object's - :java-ref:`getKeyMaterial ` - method to obtain the unencrypted PEM-encoded private key, as follows: + #. Call the result object's :aws-java-ref:`getKeyPair + ` method to obtain a + :aws-java-class:`KeyPair ` object. Call the :code:`KeyPair` + object's :aws-java-ref:`getKeyMaterial ` + method to obtain the unencrypted PEM-encoded private key, as follows: - .. code-block:: java + .. code-block:: java - KeyPair keyPair = new KeyPair(); + KeyPair keyPair = new KeyPair(); - keyPair = createKeyPairResult.getKeyPair(); + keyPair = createKeyPairResult.getKeyPair(); - String privateKey = keyPair.getKeyMaterial(); + String privateKey = keyPair.getKeyMaterial(); diff --git a/doc_source/create-security-group.rst b/doc_source/create-security-group.rst index 08433d8..38ffae3 100644 --- a/doc_source/create-security-group.rst +++ b/doc_source/create-security-group.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -26,102 +26,106 @@ EC2-Classic and EC2-VPC, see :ec2-ug:`Supported Platforms ` in the |EC2-ug|. -**To create a security group** +.. topic:: To create a security group -1. Create and initialize a :java-api:`CreateSecurityGroupRequest - ` instance. Use the :java-ref:`withGroupName - ` - method to set the security group name, and the :java-ref:`withDescription - ` - method to set the security group description, as follows: + #. Create and initialize a :aws-java-class:`CreateSecurityGroupRequest + ` instance. Use the + :aws-java-ref:`withGroupName + ` method + to set the security group name, and the :aws-java-ref:`withDescription + ` + method to set the security group description, as follows: - .. code-block:: java + .. code-block:: java - CreateSecurityGroupRequest csgr = new CreateSecurityGroupRequest(); + CreateSecurityGroupRequest csgr = new CreateSecurityGroupRequest(); + csgr.withGroupName("JavaSecurityGroup").withDescription("My security group"); - csgr.withGroupName("JavaSecurityGroup").withDescription("My security group"); + The security group name must be unique within the AWS region in which you initialize your + |EC2| client. You must use US-ASCII characters for the security group name and description. - The security group name must be unique within the AWS region in which you initialize your |EC2| - client. You must use US-ASCII characters for the security group name and description. + #. Pass the request object as a parameter to the :aws-java-ref:`createSecurityGroup + ` + method. The method returns a :aws-java-class:`CreateSecurityGroupResult + ` object, as follows: -2. Pass the request object as a parameter to the :java-ref:`createSecurityGroup - ` - method. The method returns a :java-api:`CreateSecurityGroupResult - ` object, as follows: - - .. code-block:: java + .. code-block:: java CreateSecurityGroupResult createSecurityGroupResult = - amazonEC2Client.createSecurityGroup(createSecurityGroupRequest); + amazonEC2Client.createSecurityGroup(csgr); - If you attempt to create a security group with the same name as an existing security group, - :code:`createSecurityGroup` throws an exception. + If you attempt to create a security group with the same name as an existing security group, + :code:`createSecurityGroup` throws an exception. By default, a new security group does not allow any inbound traffic to your |EC2| instance. To allow inbound traffic, you must explicitly authorize security group ingress. You can authorize ingress for individual IP addresses, for a range of IP addresses, for a specific protocol, and for TCP/UDP ports. -**To authorize security group ingress** +.. topic:: To authorize security group ingress + + #. Create and initialize an :aws-java-class:`IpPermission ` + instance. Use the :aws-java-ref:`withIpv4Ranges + ` method to set the + range of IP addresses to authorize ingress for, and use the :aws-java-ref:`withIpProtocol + ` method to set the IP + protocol. Use the :aws-java-ref:`withFromPort + ` and + :aws-java-ref:`withToPort + ` methods to specify + range of ports to authorize ingress for, as follows: -1. Create and initialize an :java-api:`IpPermission ` instance. - Use the :java-ref:`withIpRanges - ` method - to set the range of IP addresses to authorize ingress for, and use the :java-ref:`withIpProtocol - ` method to - set the IP protocol. Use the :java-ref:`withFromPort - ` and - :java-ref:`withToPort - ` methods to - specify range of ports to authorize ingress for, as follows: + .. code-block:: java - .. code-block:: java + IpPermission ipPermission = + new IpPermission(); - IpPermission ipPermission = - new IpPermission(); + IpRange ipRange1 = new IpRange().withCidrIp("111.111.111.111/32"); + IpRange ipRange2 = new IpRange().withCidrIp("150.150.150.150/32"); - ipPermission.withIpRanges("111.111.111.111/32", "150.150.150.150/32") - .withIpProtocol("tcp") - .withFromPort(22) - .withToPort(22); + ipPermission.withIpv4Ranges(Arrays.asList(new IpRange[] {ipRange1, ipRange2})) + .withIpProtocol("tcp") + .withFromPort(22) + .withToPort(22); - All the conditions that you specify in the :code:`IpPermission` object must be met in order for - ingress to be allowed. + All the conditions that you specify in the :code:`IpPermission` object must be met in order + for ingress to be allowed. - Specify the IP address using CIDR notation. If you specify the protocol as TCP/UDP, you must - provide a source port and a destination port. You can authorize ports only if you specify TCP or - UDP. + Specify the IP address using CIDR notation. If you specify the protocol as TCP/UDP, you must + provide a source port and a destination port. You can authorize ports only if you specify TCP + or UDP. -2. Create and initialize an :java-api:`AuthorizeSecurityGroupIngressRequest - ` instance. Use the - :code:`withGroupName` method to specify the security group name, and pass the - :code:`IpPermission` object you initialized earlier to the :java-ref:`withIpPermissions - ` - method, as follows: + #. Create and initialize an :aws-java-class:`AuthorizeSecurityGroupIngressRequest + ` instance. Use the + :code:`withGroupName` method to specify the security group name, and pass the + :code:`IpPermission` object you initialized earlier to the :aws-java-ref:`withIpPermissions + ` + method, as follows: - .. code-block:: java + .. code-block:: java - AuthorizeSecurityGroupIngressRequest authorizeSecurityGroupIngressRequest = - new AuthorizeSecurityGroupIngressRequest(); + AuthorizeSecurityGroupIngressRequest authorizeSecurityGroupIngressRequest = + new AuthorizeSecurityGroupIngressRequest(); - authorizeSecurityGroupIngressRequest.withGroupName("JavaSecurityGroup") - .withIpPermissions(ipPermission); + authorizeSecurityGroupIngressRequest.withGroupName("JavaSecurityGroup") + .withIpPermissions(ipPermission); -3. Pass the request object into the :java-ref:`authorizeSecurityGroupIngress - ` - method, as follows: + #. Pass the request object into the :aws-java-ref:`authorizeSecurityGroupIngress + ` + method, as follows: - .. code-block:: java + .. code-block:: java - amazonEC2Client.authorizeSecurityGroupIngress(authorizeSecurityGroupIngressRequest); + amazonEC2Client.authorizeSecurityGroupIngress(authorizeSecurityGroupIngressRequest); - If you call :code:`authorizeSecurityGroupIngress` with IP addresses for which ingress is already - authorized, the method throws an exception. Create and initialize a new :code:`IpPermission` - object to authorize ingress for different IPs, ports, and protocols before calling - :code:`AuthorizeSecurityGroupIngress`. + If you call :code:`authorizeSecurityGroupIngress` with IP addresses for which ingress is + already authorized, the method throws an exception. Create and initialize a new + :code:`IpPermission` object to authorize ingress for different IPs, ports, and protocols + before calling :code:`AuthorizeSecurityGroupIngress`. -Whenever you call the :code:`authorizeSecurityGroupIngress` or -:java-ref:`authorizeSecurityGroupEgress -` methods, a rule is -added to your security group. +Whenever you call the :aws-java-ref:`authorizeSecurityGroupIngress +` +or :aws-java-ref:`authorizeSecurityGroupEgress +` +methods, a rule is added to your security group. diff --git a/doc_source/creating-clients.rst b/doc_source/creating-clients.rst index a045a0a..d35a445 100644 --- a/doc_source/creating-clients.rst +++ b/doc_source/creating-clients.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,22 +12,36 @@ Creating Service Clients ######################## -To make requests to |AWSlong|, you first create a service client object. The -preferred way to do this is to use the service client builder. Each AWS service has a service interface -that has methods for each action in the service API. For example, the service interface for -|DDBlong| is named :java-api:`AmazonDynamoDB `. Each service interface has a corresponding client builder you can use to construct -an implementation of the service interface. The client builder class for |DDB| is named -:java-api:`AmazonDynamoDBClientBuilder `. +.. meta:: + :description: How to create service clients by using the AWS SDK for Java. + :keywords: -To obtain an instance of the client builder, use the static factory method ``standard``, as shown in the following example. +To make requests to |AWSlong|, you first create a service client object. The recommended +way is +to use the service client builder. + +Each AWS service has a service interface with methods +for each action in the service API. For example, the service interface for |DDBlong| is named +:aws-java-class:`AmazonDynamoDB `. Each service interface has a +corresponding client builder you can use to construct an implementation of the service interface. +The client builder class for |DDB| is named :aws-java-class:`AmazonDynamoDBClientBuilder +`. + +Obtaining a Client Builder +========================== + +To obtain an instance of the client builder, use the static factory method ``standard``, +as shown in the following example. .. code-block:: java AmazonDynamoDBClientBuilder builder = AmazonDynamoDBClientBuilder.standard(); -Once you obtain a builder, you can customize properties of the client by using many fluent setters -in the builder API. For example, you can set a custom region and a custom credentials provider as follows. +Once you have a builder, you can customize the client's properties by using many fluent +setters +in the builder API. For example, you can set a custom region and a custom credentials provider, as +follows. .. code-block:: java @@ -36,11 +50,16 @@ in the builder API. For example, you can set a custom region and a custom creden .withCredentials(new ProfileCredentialsProvider("myProfile")) .build(); -.. note:: The fluent withXXX methods return the ``builder`` object so that you can chain the method calls for convenience and more readable code. After you configure all the properties you want, you can call the ``build`` method to create the client. Once a client is created, it is immutable and any calls to ``setRegion`` or ``setEndpoint`` will fail. +.. note:: The fluent ``withXXX`` methods return the ``builder`` object so that you can chain the + method calls for convenience and for more readable code. After you configure the properties you + want, + you can call the ``build`` method to create the client. Once a client is created, it's immutable + and any calls to ``setRegion`` or ``setEndpoint`` will fail. + +A builder can create multiple clients with the same configuration. When you're writing your +application, be aware that the builder is mutable and not thread-safe. -A builder can create multiple clients with the same configuration. When you're writing your application, be aware that the builder is -mutable and not thread-safe. The following -code uses the builder as a factory for client instances. +The following code uses the builder as a factory for client instances. .. code-block:: java @@ -55,9 +74,9 @@ code uses the builder as a factory for client instances. } } -The builder also exposes fluent setters for :java-api:`ClientConfiguration `', -:java-api:`RequestMetricCollector `, and custom -:java-api:`RequestHandler2 `. +The builder also exposes fluent setters for :aws-java-class:`ClientConfiguration `' +and :aws-java-class:`RequestMetricCollector `, and a custom list of +:aws-java-class:`RequestHandler2 `. The following is a complete example that overrides all configurable properties. @@ -73,59 +92,64 @@ The following is a complete example that overrides all configurable properties. Creating Async Clients ====================== -The |sdk-java| also has asynchronous (or async) clients for every service, except for |S3long|. There is also a corresponding async -client builder for every service. +The |sdk-java| has asynchronous (or async) clients for every service (except for |S3|), and a corresponding +async client builder for every service. -**To create an async |DDB| client with the default ExecutorService** +.. topic:: To create an async |DDB| client with the default ExecutorService -.. code-block:: java + .. code-block:: java - AmazonDynamoDBAsync ddbAsync = AmazonDynamoDBAsyncClientBuilder.standard() - .withRegion(Regions.US_WEST_2) - .withCredentials(new ProfileCredentialsProvider("myProfile")) - .build(); + AmazonDynamoDBAsync ddbAsync = AmazonDynamoDBAsyncClientBuilder.standard() + .withRegion(Regions.US_WEST_2) + .withCredentials(new ProfileCredentialsProvider("myProfile")) + .build(); In addition to the configuration options that the synchronous (or sync) client builder supports, -the async client allows you to set a custom :java-api:`ExecutorFactory ` -to change the ``ExecutorService`` that the async client uses. ``ExecutorFactory`` is a functional -interface, so it interoperates with Java 8 lambda expressions and method references. +the async client enables you to set a custom :aws-java-class:`ExecutorFactory ` +to change the :classname:`ExecutorService` that the async client uses. :classname:`ExecutorFactory` +is a functional interface, so it interoperates with Java 8 lambda expressions and method references. -**To create an async client with a custom executor** +.. topic:: To create an async client with a custom executor -.. code-block:: java + .. code-block:: java - AmazonDynamoDBAsync ddbAsync = AmazonDynamoDBAsyncClientBuilder.standard() - .withExecutorFactory(() -> Executors.newFixedThreadPool(10)) - .build(); + AmazonDynamoDBAsync ddbAsync = AmazonDynamoDBAsyncClientBuilder.standard() + .withExecutorFactory(() -> Executors.newFixedThreadPool(10)) + .build(); -Default Client -============== -Both the sync and async client builders have another factory method called ``defaultClient``. This -method creates a service client with the default configuration and with credentials and region -obtained from the environment. If credentials or region cannot be determined from the environment -that the application is running in, the call to ``defaultClient`` will fail. See :doc:`credentials` and -:doc:`java-dg-region-selection` for more information on how credentials and region are -determined. -**To create a default service client** +Using DefaultClient +=================== -.. code-block:: java +Both the sync and async client builders have another factory method named +:methodname:`defaultClient`. This method creates a service client with the default configuration, +using the default provider chain to load credentials and the AWS Region. If credentials or +the region can't be determined from the environment that the application is running in, the call to +:methodname:`defaultClient` fails. See :doc:`credentials` and :doc:`java-dg-region-selection` +for more information about how credentials and region are determined. + +.. topic:: To create a default service client + + .. code-block:: java + + AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient(); - AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient(); 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, you can call the ``shutdown`` method. After calling ``shutdown``, all client -resources are released and the client is unusable. -**To shut down a client** +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. +Explicitly shut down clients when they are no longer needed to avoid resource leaks. -.. code-block:: java +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. - AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient(); - ddb.shutdown(); - // Client is now unusable +.. topic:: To shut down a client + .. code-block:: java + AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient(); + ddb.shutdown(); + // Client is now unusable diff --git a/doc_source/credentials.rst b/doc_source/credentials.rst index 3bf5e3b..2d017ea 100644 --- a/doc_source/credentials.rst +++ b/doc_source/credentials.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,112 +12,117 @@ Working with AWS Credentials ############################ -To make requests to Amazon Web Services, you will need to supply AWS credentials to the |sdk-java|. -There are a number of ways to do this: +.. meta:: + :description: How to load credentials for AWS using the AWS SDK for Java. + :keywords: -* Use the default credential provider chain :emphasis:`(recommended)` +To make requests to |AWSlong|, you must supply AWS credentials to the |sdk-java|. +You can do this in the following ways: + +* Use the default credential provider chain :emphasis:`(recommended)`. * Use a specific credential provider or provider chain (or create your own). -* Supply the credentials yourself. These can be either root account credentials, |IAM| credentials +* Supply the credentials yourself. These can be root account credentials, |IAM| credentials, or temporary credentials retrieved from |STS|. -.. important:: It is *strongly recommended*, from a security standpoint, that you *use IAM users* - instead of the root account for AWS access. For more information, see `IAM Best Practices - `_ in |iam-ug|. - -This topic provides information about how to load credentials for AWS using the |sdk-java|. - -.. contents:: - :depth: 1 - :local: +.. important:: For security, we *strongly recommend* that you *use IAM + users* instead of the root account for AWS access. For more information, see :iam-ug:`IAM Best Practices + ` in the |iam-ug|. .. _credentials-default: Using the Default Credential Provider Chain =========================================== -When you initialize a new service client without supplying any arguments, the |sdk-java| will -attempt to find AWS credentials using the :emphasis:`default credential provider chain` implemented -by the :java-api:`DefaultAWSCredentialsProviderChain ` -class. The default credential provider chain looks for credentials in this order: +When you initialize a new service client without supplying any arguments, the |sdk-java| +attempts to find AWS credentials by using the :emphasis:`default credential provider chain` implemented +by the :aws-java-class:`DefaultAWSCredentialsProviderChain ` +class. The default credential provider chain looks for credentials in this order: + +#. **Environment variables** |ndash| :envvar:`AWS_ACCESS_KEY_ID` and :envvar:`AWS_SECRET_ACCESS_KEY`. + The |sdk-java| uses the :aws-java-class:`EnvironmentVariableCredentialsProvider ` + class to load these credentials. -1. **Environment Variables** |ndash| :envvar:`AWS_ACCESS_KEY_ID` and - :envvar:`AWS_SECRET_ACCESS_KEY`. The |sdk-java| uses the - :java-api:`EnvironmentVariableCredentialsProvider ` - class to load these credentials. +#. **Java system properties** |ndash| :code:`aws.accessKeyId` and :code:`aws.secretKey`. + The |sdk-java| uses the :aws-java-class:`SystemPropertiesCredentialsProvider ` + to load these credentials. -2. **Java System Properties** |ndash| :code:`aws.accessKeyId` and :code:`aws.secretKey`. The - |sdk-java| uses the :java-api:`SystemPropertiesCredentialsProvider - ` to load these credentials. +#. **Web Identity Token credentials** from the environment or container. -3. **The default credential profiles file** |ndash| typically located at - :filename:`~/.aws/credentials` (this location may vary per platform), this credentials file is - shared by many of the AWS SDKs and by the AWS CLI. The |sdk-java| uses the - :java-api:`ProfileCredentialsProvider ` to load these - credentials. +#. **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. - You can create a credentials file by using the :code:`aws configure` command provided by the AWS - CLI, or you can create it by hand-editing the file with a text editor. For information about the - credentials file format, see :ref:`credentials-file-format`. + You can create a credentials file by using the :code:`aws configure` command provided by the AWS + CLI, or you can create it by editing the file with a text editor. For information about the + credentials file format, see :ref:`credentials-file-format`. +#. **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. You can specify the IP address for this value. -4. **Instance profile credentials** |ndash| these credentials can be used on EC2 instances, and are - delivered through the Amazon EC2 metadata service. The |sdk-java| uses the - :java-api:`InstanceProfileCredentialsProvider ` to load - these credentials. +#. **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. 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 ------------------- -AWS credentials must be set in :emphasis:`at least one` of the preceding locations in order to be -used. For information about setting credentials, visit one of the following topics: +To be able to use AWS credentials, they must be set in :emphasis:`at least one` of the +preceding locations. For information about setting credentials, see the following topics: -* For information about specifying credentials in the :emphasis:`environment` or in the default - :emphasis:`credential profiles file`, see :doc:`setup-credentials`. +* To specify credentials in the :emphasis:`environment` or in the default + :emphasis:`credential profiles file`, see :doc:`setup-credentials`. -* For information about setting Java :emphasis:`system properties`, see the `System Properties - `_ tutorial on the - official :title:`Java Tutorials` website. +* To set Java :emphasis:`system properties`, see the + `System Properties `_ + tutorial on the official :title:`Java Tutorials` website. -* For information about how to set up and use :emphasis:`instance profile credentials` for use - with your EC2 instances, see :doc:`java-dg-roles`. +* To set up and use :emphasis:`instance profile credentials` with + your EC2 instances, see :doc:`java-dg-roles`. Setting an Alternate Credentials Profile ---------------------------------------- -The SDK for Java will use the `default` profile by default but there are a couple of ways to customize +The |sdk-java| uses the `default` profile by default, but there are ways to customize which profile is sourced from the credentials file. -The AWS Profile environment variable can be used to change the profile loaded by the SDK. +You can use the AWS Profile environment variable to change the profile loaded by the SDK. -For example, on |unixes| you would run the following command to change the profile to `myProfile` +For example, on |unixes| you would run the following command to change the profile to `myProfile`. .. code-block:: sh export AWS_PROFILE="myProfile" -On Windows you would use the following: +On Windows you would use the following. .. code-block:: bat set AWS_PROFILE="myProfile" -Setting the AWS_PROFILE environment variable will affect credential loading for all other officially -supported AWS SDKs and Tools (including the AWS CLI and the AWS CLI for PowerShell). If you want -to only change the profile for a Java application, you can use the system property `aws.profile` instead. -Please note that the environment variable takes precedence over the system property. +Setting the AWS_PROFILE environment variable affects credential loading for all officially +supported AWS SDKs and Tools (including the AWS CLI and the AWS CLI for PowerShell). +To change only the profile for a Java application, you can use the system property `aws.profile` instead. + +.. note:: The environment variable takes precedence over the system property. Setting an Alternate Credentials File Location ---------------------------------------------- -Although the SDK for Java will load AWS credentials automatically from the default credentials file -location, you can also specify the location yourself by setting the |aws-credfile-var| environment -variable with the full pathname to the credentials file. +The |sdk-java| loads AWS credentials automatically from the default credentials file +location. However, you can also specify the location by setting the |aws-credfile-var| environment +variable with the full path to the credentials file. -This feature can be used to temporarily change the location where the SDK for Java looks for your -credentials file (by setting this variable with the command-line, for example), or you can set the -environment variable in your user or system environment to change it for the user or system-wide. +You can use this feature to temporarily change the location where the |sdk-java| looks for +your credentials file (for example, by setting this variable with the command line). Or you +can set the environment variable in your user or system environment to change it for the user or systemwide. .. include:: common/procedure-override-shared-credfile-location.txt @@ -127,8 +132,8 @@ environment variable in your user or system environment to change it for the use AWS Credentials File Format --------------------------- -When you create an AWS credentials file using the :code:`aws configure` command, it creates a file -with the following format: +When you use the :code:`aws configure` command to create an AWS credentials file, the command creates +a file with the following format. .. code-block:: ini @@ -140,14 +145,14 @@ with the following format: aws_access_key_id={YOUR_ACCESS_KEY_ID} aws_secret_access_key={YOUR_SECRET_ACCESS_KEY} -The profile name is specified in square brackets (For example: :code:`[default]`), followed by the -configurable fields in that profile as key/value pairs. You can have multiple profiles in your +The profile name is specified in square brackets (for example, :code:`[default]`), followed by the +configurable fields in that profile as key-value pairs. You can have multiple profiles in your credentials file, which can be added or edited using :samp:`aws configure --profile {PROFILE_NAME}` to select the profile to configure. You can specify additional fields, such as :code:`aws_session_token`, -:code:`metadata_service_timeout` and :code:`metadata_service_num_attempts`. These are not -configurable with the CLI |mdash| you must edit the file by hand if you wish to use them. For more +:code:`metadata_service_timeout`, and :code:`metadata_service_num_attempts`. These are not +configurable with the CLI |mdash| you must edit the file by hand if you want to use them. For more information about the configuration file and its available fields, see :cli-ug:`Configuring the AWS Command Line Interface ` in the |cli-ug|. @@ -155,19 +160,16 @@ Command Line Interface ` in the |cli-ug|. Loading Credentials ------------------- -Once credentials have been set, you can load them using the |sdk-java| default credential provider +After you set credentials, you can load them by using the default credential provider chain. -:emphasis:`To load credentials using the default credential provider chain` - -* Instantiate an AWS Service client without explicitly providing credentials to the builder. For example: +To do this, you instantiate an AWS Service client without explicitly providing credentials to the builder, as follows. - .. code-block:: java - - AmazonS3 s3Client = AmazonS3ClientBuilder.standard() - .withRegion(Regions.US_WEST_2) - .build(); +.. code-block:: java + AmazonS3 s3Client = AmazonS3ClientBuilder.standard() + .withRegion(Regions.US_WEST_2) + .build(); .. _credentials-specify-provider: @@ -175,29 +177,27 @@ chain. Specifying a Credential Provider or Provider Chain ================================================== -If you want to specify a different credential provider than the :emphasis:`default` credential -provider chain, you can specify it via the client builder. +You can specify a credential provider that is different from the :emphasis:`default` credential +provider chain by using the client builder. -:emphasis:`To specify a specific credentials provider` +You provide an instance of a credentials provider or provider chain to a client builder that +takes an :aws-java-class:`AWSCredentialsProvider ` interface as input. The +following example shows how to use :emphasis:`environment` credentials specifically. -* Provide an instance of a credentials provider or provider chain to a client builder - that takes an :java-api:`AWSCredentialsProvider ` interface as input. - For example, to use :emphasis:`environment` credentials specifically: - .. code-block:: java +.. code-block:: java - AmazonS3 s3Client = AmazonS3ClientBuilder.standard() - .withCredentials(new EnvironmentVariableCredentialsProvider()) - .build(); + AmazonS3 s3Client = AmazonS3ClientBuilder.standard() + .withCredentials(new EnvironmentVariableCredentialsProvider()) + .build(); -For the full list of |sdk-java|-supplied credential providers and provider chains, see the list of -"All known implementing classes" in the reference topic for :java-api:`AWSCredentialsProvider -`. +For the full list of |sdk-java|-supplied credential providers and provider chains, +see **All Known Implementing Classes** in :aws-java-class:`AWSCredentialsProvider `. .. tip:: You can use this technique to supply credential providers or provider chains that you - create, by implementing your own credential provider that implements the - :emphasis:`AWSCredentialsProvider` interface, or by sub-classing the - :java-api:`AWSCredentialsProviderChain ` class. + create by using your own credential provider that implements the + :code-java:`AWSCredentialsProvider` interface, or by subclassing the + :aws-java-class:`AWSCredentialsProviderChain ` class. .. _credentials-explicit: @@ -205,21 +205,24 @@ For the full list of |sdk-java|-supplied credential providers and provider chain Explicitly Specifying Credentials ================================= -If neither the default credential chain or a specific or custom provider or provider chain works for -your code, you can set credentials explicitly by supplying them yourself. If you have retrieved -temporary credentials using |STS|, use this method to specify the credentials for AWS access. +If the default credential chain or a specific or custom provider or provider chain doesn't work for +your code, you can set credentials that you supply explicitly. If you've retrieved temporary +credentials using |STS|, use this method to specify the credentials for AWS access. + -**To explicitly supply credentials to an AWS client:** +.. topic:: To explicitly supply credentials to an AWS client -Instantiate a class that provides the :java-api:`AWSCredentials ` interface, -such as :java-api:`BasicAWSCredentials `, supplying it with the AWS access -key and secret key you will use for the connection. + #. Instantiate a class that provides the :aws-java-class:`AWSCredentials ` + interface, such as :aws-java-class:`BasicAWSCredentials `, and supply + it with the AWS access key and secret key you will use for the connection. -Create a :java-api:`AWSStaticCredentialsProvider ` with the AWSCredentials object. + #. Create an :aws-java-class:`AWSStaticCredentialsProvider ` with + the :code-java:`AWSCredentials` object. -Configure the client builder with the AWSStaticCredentialsProvider and build the client. + #. Configure the client builder with the :code-java:`AWSStaticCredentialsProvider` and build the client. -For example: + +The following is an example. .. code-block:: java @@ -229,20 +232,17 @@ For example: .build(); When using :doc:`temporary credentials obtained from STS `, create a -:java-api:`BasicSessionCredentials ` object, passing it the -STS-supplied credentials and session token: +:aws-java-class:`BasicSessionCredentials ` object, passing it the +STS-supplied credentials and session token. .. literalinclude:: snippets/sts_basic_session_creds.java :language: java :lines: 14- -See Also -======== - -* :doc:`signup-create-iam-user` - -* :doc:`setup-credentials` - -* :doc:`java-dg-roles` +More Info +========= +* :doc:`signup-create-iam-user` +* :doc:`setup-credentials` +* :doc:`java-dg-roles` diff --git a/doc_source/data-protection.rst b/doc_source/data-protection.rst new file mode 100644 index 0000000..185e987 --- /dev/null +++ b/doc_source/data-protection.rst @@ -0,0 +1,46 @@ +.. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +##################################### +Data Protection in |SERVICENAMETITLE| +##################################### + +.. meta:: + :description: Learn how the AWS shared responsibility model applies to data protection in this AWS product or service. + :keywords: + +.. include:: common/_security-includes.txt + +|SERVICENAMESENTENCECASE| conforms to the `shared responsibility model `_, +which includes regulations and guidelines for data protection. |AWSlong| (|AWS|) is responsible for protecting the global infrastructure +that runs all the |AWS| services. |AWS| maintains control over data hosted on this infrastructure, including the security configuration +controls for handling customer content and personal data. |AWS| customers and APN partners, acting either as data controllers or data +processors, are responsible for any personal data that they put in the |AWS| Cloud. + +For data protection purposes, we recommend that you protect |AWS| account credentials and set up individual user accounts with +|IAMlong| (|IAM|), so that each user is given only the permissions necessary to fulfill their job duties. We also recommend that +you secure your data in the following ways: + +* Use multi-factor authentication (MFA) with each account. +* Use SSL/TLS to communicate with |AWS| resources. To use a minimum TLS version of 1.2, see `Enforcing TLS 1.2 `_. +* Set up API and user activity logging with |CTlong|. +* Use |AWS| encryption solutions, along with all default security controls within |AWS| services. +* Use advanced managed security services such as |MCElong|, which assists in discovering and securing personal data that + is stored in |S3|. + +We strongly recommend that you never put sensitive identifying information, such as your customers' account numbers, into +free-form fields such as a **Name** field. This includes when you work with |SERVICENAME| or other |AWS| services +using the console, API, |CLI|, or |AWS| SDKs. Any data that you enter into |SERVICENAME| or other services might get picked up +for inclusion in diagnostic logs. When you provide a URL to an external server, don't include credentials information in the URL +to validate your request to that server. + +For more information about data protection, see the +`AWS Shared Responsibility Model and GDPR `_ +blog post on the *AWS Security Blog*. \ No newline at end of file diff --git a/doc_source/disaster-recovery-resiliency.rst b/doc_source/disaster-recovery-resiliency.rst new file mode 100644 index 0000000..e4abd93 --- /dev/null +++ b/doc_source/disaster-recovery-resiliency.rst @@ -0,0 +1,29 @@ +Resilience for this AWS Product or Service +========================================== + +The Amazon Web Services (AWS) global infrastructure is built around AWS +Regions and Availability Zones. + +AWS Regions provide multiple physically separated and isolated +Availability Zones, which are connected with low-latency, +high-throughput, and highly redundant networking. + +With Availability Zones, you can design and operate applications and +databases that automatically fail over between Availability Zones +without interruption. Availability Zones are more highly available, +fault tolerant, and scalable than traditional single or multiple data +center infrastructures. + +For more information about AWS Regions and Availability Zones, see `AWS +Global +Infrastructure `__. + +This AWS product or service follows the `shared responsibility +model `__ +through the specific Amazon Web Services (AWS) services it supports. For +AWS service security information, see the `AWS service security +documentation +page `__ +and `AWS services that are in scope of AWS compliance efforts by +compliance +program `__. diff --git a/doc_source/document-history.rst b/doc_source/document-history.rst index d21d1a8..1b3c234 100644 --- a/doc_source/document-history.rst +++ b/doc_source/document-history.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -14,87 +14,135 @@ Document History This topic describes important changes to the |sdk-java-dg| over the course of its history. -**Last documentation update:** |today| +**This documentation was built on:** |today| + +Mar 22, 2018 + Removed managing Tomcat sessions in |DDB| example as that tool is no longer supported. + +Nov 2, 2017 + Added cryptography examples for |S3| encryption client, including new topics: + :doc:`examples-crypto` and :doc:`examples-crypto-kms` and :doc:`examples-crypto-masterkey`. + +Apr 14, 2017 + Made a number of updates to the :doc:`examples-s3` section, including new topics: + :doc:`examples-s3-access-permissions` and :doc:`examples-s3-website-configuration`. + +Apr 04, 2017 + A new topic, :doc:`generating-sdk-metrics` describes how to generate application and SDK + performance metrics for the |sdk-java|. + +Apr 03, 2017 + Added new |CW| examples to the :doc:`examples-cloudwatch` section: + :doc:`examples-cloudwatch-get-metrics`, :doc:`examples-cloudwatch-publish-custom-metrics`, + :doc:`examples-cloudwatch-create-alarms`, :doc:`examples-cloudwatch-use-alarm-actions`, and + :doc:`examples-cloudwatch-send-events` + +Mar 27, 2017 + Added more |EC2| examples to the :doc:`prog-services-ec2` section: :doc:`examples-ec2-instances`, + :doc:`examples-ec2-elastic-ip`, :doc:`examples-ec2-regions-zones`, :doc:`examples-ec2-key-pairs`, + and :doc:`examples-ec2-security-groups`. + +Mar 21, 2017 + Added a new set of |IAM| examples to the :doc:`examples-iam` section: + :doc:`examples-iam-access-keys`, :doc:`examples-iam-users`, :doc:`examples-iam-account-aliases`, + :doc:`examples-iam-policies`, and :doc:`examples-iam-server-certificates` + +Mar 13, 2017 + Added three new topics to the |SQS| section: :doc:`examples-sqs-long-polling`, + :doc:`examples-sqs-visibility-timeout`, and :doc:`examples-sqs-dead-letter-queues`. + +Jan 26, 2017 + Added a new |S3| topic, :doc:`examples-s3-transfermanager`, and a new :doc:`best-practices` topic + in the :doc:`basics` section. + +Jan 16, 2017 + Added a new |S3| topic, :doc:`examples-s3-bucket-policies`, and two new |SQS| topics, + :doc:`examples-sqs-message-queues` and :doc:`examples-sqs-messages`. + +Dec 16, 2016 + Added new example topics for |DDB|: :doc:`examples-dynamodb-tables` and + :doc:`examples-dynamodb-items`. + +Sep 26, 2016 + The topics in the **Advanced** section have been moved into :doc:`basics`, since they really are + central to using the SDK. Aug 25, 2016 - A new topic, :doc:`creating-clients`, has been added to the :doc:`basics` section, which - demonstrates how to use *client builders* to simplify the creation of AWS service clients. + A new topic, :doc:`creating-clients`, has been added to :doc:`basics`, which demonstrates how to + use *client builders* to simplify the creation of AWS service clients. - The :doc:`prog-services` section has been updated with :doc:`new examples for S3 ` - which are backed by a `repository on GitHub `_ that contains the complete - example code. + The :doc:`prog-services` section has been updated with :doc:`new examples for S3 ` + which are backed by a `repository on GitHub `_ that contains the complete + example code. May 02, 2016 - A new topic, :doc:`basics-async`, has been added to the :doc:`basics` section, describing how to - work with asynchronous client methods that return :classname:`Future` objects or that take an - :classname:`AsyncHandler`. + A new topic, :doc:`basics-async`, has been added to the :doc:`basics` section, describing how to + work with asynchronous client methods that return :classname:`Future` objects or that take an + :classname:`AsyncHandler`. Apr 26, 2016 - The *SSL Certificate Requirements* topic has been removed, since it is no longer relevant. - Support for SHA-1 signed certificates was deprecated in 2015 and the site that housed the test - scripts has been removed. + The *SSL Certificate Requirements* topic has been removed, since it is no longer relevant. + Support for SHA-1 signed certificates was deprecated in 2015 and the site that housed the test + scripts has been removed. Mar 14, 2016 - Added a new topic to the |SWF| section: :doc:`swf-lambda-task`, which describes how to implement - a |SWF| workflow that calls |LAM| functions as tasks as an alternative to using traditional - |SWF| activities. + Added a new topic to the |SWF| section: :doc:`swf-lambda-task`, which describes how to implement + a |SWF| workflow that calls |LAM| functions as tasks as an alternative to using traditional |SWF| + activities. Mar 04, 2016 - The :doc:`prog-services-swf` section has been updated with new content: + The :doc:`prog-services-swf` section has been updated with new content: - * :doc:`swf-basics` |ndash| Provides basic information about how to include SWF in your - projects. + * :doc:`swf-basics` |ndash| Provides basic information about how to include SWF in your projects. - * :doc:`swf-hello` |ndash| A new tutorial that provides step-by-step guidance for Java - developers new to |SWF|. + * :doc:`swf-hello` |ndash| A new tutorial that provides step-by-step guidance for Java developers + new to |SWF|. - * :doc:`swf-graceful-shutdown` |ndash| Describes how you can gracefully shut down |SWF| - worker classes using Java's concurrency classes. + * :doc:`swf-graceful-shutdown` |ndash| Describes how you can gracefully shut down |SWF| worker + classes using Java's concurrency classes. Feb 23, 2016 - The source for the |sdk-java-dg| has been moved to :github:`aws-java-developer-guide - `. + The source for the |sdk-java-dg| has been moved to :github:`aws-java-developer-guide + `. Dec 28, 2015 - :doc:`java-dg-jvm-ttl` has been moved from :doc:`advanced` into the :doc:`basics` section, and - has been rewritten for clarity. + :doc:`java-dg-jvm-ttl` has been moved from **Advanced** into :doc:`basics`, and has been + rewritten for clarity. - :doc:`setup-project-maven` has been updated with information about how to include the - SDK's bill of materials (BOM) in your project. + :doc:`setup-project-maven` has been updated with information about how to include the SDK's bill + of materials (BOM) in your project. Aug 04, 2015 - *SSL Certificate Requirements* is a new topic in the :doc:`getting-started` section that - describes AWS' move to SHA256-signed certificates for SSL connections, and how to fix early 1.6 - and previous Java environments to use these certificates, which are :emphasis:`required` for AWS - access after September 30, 2015. + *SSL Certificate Requirements* is a new topic in the :doc:`getting-started` section that + describes AWS' move to SHA256-signed certificates for SSL connections, and how to fix early 1.6 + and previous Java environments to use these certificates, which are :emphasis:`required` for AWS + access after September 30, 2015. - .. note:: Java 1.7+ is already capable of working with SHA256-signed certificates. + .. note:: Java 1.7+ is already capable of working with SHA256-signed certificates. May 14, 2014 - The :doc:`introduction ` and :doc:`getting started ` material has been - heavily revised to support the new guide structure and now includes guidance about how to - :doc:`setup-credentials`. + The :doc:`introduction ` and :doc:`getting started ` material has been + heavily revised to support the new guide structure and now includes guidance about how to + :doc:`setup-credentials`. - The discussion of :doc:`code samples ` has been moved into its own topic in the - :ref:`additional-resources` section. + The discussion of :doc:`code samples ` has been moved into its own topic in the + :ref:`additional-resources` section. - Information about how to :ref:`view the SDK revision history ` has been moved - into the introduction. + Information about how to :ref:`view the SDK revision history ` has been moved + into the introduction. May 9, 2014 - The overall structure of the |sdk-java| documentation has been simplified, and the - :doc:`getting-started` and :ref:`additional-resources` topics have been updated. + The overall structure of the |sdk-java| documentation has been simplified, and the + :doc:`getting-started` and :ref:`additional-resources` topics have been updated. - New topics have been added: + New topics have been added: - * :doc:`credentials` |ndash| discusses the various ways that you can specify credentials for use - with the |sdk-java|. + * :doc:`credentials` |ndash| discusses the various ways that you can specify credentials for use + with the |sdk-java|. - * :doc:`java-dg-roles` |ndash| provides information about how to securely specify credentials - for applications running on EC2 instances. + * :doc:`java-dg-roles` |ndash| provides information about how to securely specify credentials for + applications running on EC2 instances. Sep 9, 2013 - This topic, *Document History*, tracks changes to the |sdk-java-dg|. It is intended as a companion - to the release notes history. - - + This topic, *Document History*, tracks changes to the |sdk-java-dg|. It is intended as a + companion to the release notes history. diff --git a/doc_source/examples-cloudwatch-create-alarms.rst b/doc_source/examples-cloudwatch-create-alarms.rst new file mode 100644 index 0000000..5fe9241 --- /dev/null +++ b/doc_source/examples-cloudwatch-create-alarms.rst @@ -0,0 +1,101 @@ +.. 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. + +######################## +Working with |CW| Alarms +######################## + +.. meta:: + :description: How to create, list, and delete alarms in Amazon CloudWatch using the AWS SDK for + Java + :keywords: create alarm, delete alarm, list alarms, metric alarms, example code + +Create an Alarm +=============== + +To create an alarm based on a |cw| metric, call the |cwclient|'s :methodname:`putMetricAlarm` method +with a :aws-java-class:`PutMetricAlarmRequest ` +filled with the alarm conditions. + +**Imports** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/PutMetricAlarm.java + :lines: 16-23 + :language: java + +**Code** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/PutMetricAlarm.java + :lines: 43-66 + :dedent: 8 + :language: java + + +List Alarms +=========== + +To list the |cw| alarms that you have created, call the |cwclient|'s :methodname:`describeAlarms` +method with a :aws-java-class:`DescribeAlarmsRequest +` that you can use to set options for the result. + +**Imports** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/DescribeAlarms.java + :lines: 16-20 + :language: java + +**Code** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/DescribeAlarms.java + :lines: 29-48 + :dedent: 8 + :language: java + +The list of alarms can be obtained by calling :methodname:`getMetricAlarms` on the +:aws-java-class:`DescribeAlarmsResult ` that is +returned by :methodname:`describeAlarms`. + +The results may be *paged*. To retrieve the next batch of results, call :methodname:`setNextToken` +on the original request object with the return value of the :classname:`DescribeAlarmsResult` +object's :methodname:`getNextToken` method, and pass the modified request object back to another +call to :methodname:`describeAlarms`. + +.. tip:: You can also retrieve alarms for a specific metric by using the |cwclient|'s + :methodname:`describeAlarmsForMetric` method. Its use is similar to :methodname:`describeAlarms`. + + +Delete Alarms +============= + +To delete |cw| alarms, call the |cwclient|'s :methodname:`deleteAlarms` method with a +:aws-java-class:`DeleteAlarmsRequest ` containing one +or more names of alarms that you want to delete. + +**Imports** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/DeleteAlarm.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/DeleteAlarm.java + :lines: 38-44 + :dedent: 8 + :language: java + + +More Information +================ + +* :cw-ug:`Creating Amazon CloudWatch Alarms ` in the |cw-ug| +* :cw-api:`PutMetricAlarm ` in the |cw-api| +* :cw-api:`DescribeAlarms ` in the |cw-api| +* :cw-api:`DeleteAlarms ` in the |cw-api| diff --git a/doc_source/examples-cloudwatch-get-metrics.rst b/doc_source/examples-cloudwatch-get-metrics.rst new file mode 100644 index 0000000..940681d --- /dev/null +++ b/doc_source/examples-cloudwatch-get-metrics.rst @@ -0,0 +1,53 @@ +.. 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. + +######################### +Getting Metrics from |CW| +######################### + +.. meta:: + :description: How to list metrics from Amazon CloudWatch using the AWS SDK for Java. + :keywords: Amazon Cloudwatch, AWS SDK for Java, metrics, listing, code examples + +Listing Metrics +=============== + +To list |cw| metrics, create a :aws-java-class:`ListMetricsRequest +` and call the |cwclient|'s :methodname:`listMetrics` +method. You can use the :classname:`ListMetricsRequest` to filter the returned metrics by namespace, +metric name, or dimensions. + +.. note:: A list of metrics and dimensions that are posted by AWS services can be found within the + :cw-ug:`Amazon CloudWatch Metrics and Dimensions Reference ` in the |cw-ug|. + +**Imports** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/ListMetrics.java + :lines: 16-20 + :language: java + +**Code** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/ListMetrics.java + :lines: 41-63 + :dedent: 8 + :language: java + +The metrics are returned in a :aws-java-class:`ListMetricsResult +` by calling its :methodname:`getMetrics` method. The +results may be *paged*. To retrieve the next batch of results, call :methodname:`setNextToken` on +the original request object with the return value of the :classname:`ListMetricsResult` object's +:methodname:`getNextToken` method, and pass the modified request object back to another call to +:methodname:`listMetrics`. + +More Information +================ + +* :cw-api:`ListMetrics ` in the |cw-api|. diff --git a/doc_source/examples-cloudwatch-publish-custom-metrics.rst b/doc_source/examples-cloudwatch-publish-custom-metrics.rst new file mode 100644 index 0000000..cac7e04 --- /dev/null +++ b/doc_source/examples-cloudwatch-publish-custom-metrics.rst @@ -0,0 +1,55 @@ +.. 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. + +############################# +Publishing Custom Metric Data +############################# + +.. meta:: + :description: How to publish your own custom metric data to Amazon Cloudwatch using the AWS SDK + for Java. + :keywords: Amazon Cloudwatch, AWS SDK for Java, custom metrics, code examples + + +A number of AWS services publish :cw-ug:`their own metrics ` in namespaces beginning +with "AWS/" You can also publish custom metric data using your own namespace (as long as it doesn't +begin with "AWS/"). + +Publish Custom Metric Data +========================== + +To publish your own metric data, call the |cwclient|'s :methodname:`putMetricData` method with a +:aws-java-class:`PutMetricDataRequest `. The +:classname:`PutMetricDataRequest` must include the custom namespace to use for the data, and +information about the data point itself in a :aws-java-class:`MetricDatum +` object. + +.. note:: You cannot specify a namespace that begins with "AWS/". Namespaces that begin with + "AWS/" are reserved for use by Amazon Web Services products. + +**Imports** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/PutMetricData.java + :lines: 16-22 + :language: java + +**Code** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/PutMetricData.java + :lines: 41-58 + :dedent: 8 + :language: java + +More Information +================ + +* :cw-ug:`Using Amazon CloudWatch Metrics ` in the |cw-ug|. +* :cw-ug:`AWS Namespaces ` in the |cw-ug|. +* :cw-api:`PutMetricData ` in the |cw-api|. diff --git a/doc_source/examples-cloudwatch-send-events.rst b/doc_source/examples-cloudwatch-send-events.rst new file mode 100644 index 0000000..15d43fa --- /dev/null +++ b/doc_source/examples-cloudwatch-send-events.rst @@ -0,0 +1,104 @@ +.. 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. + +###################### +Sending Events to |CW| +###################### + +.. meta:: + :description: How to add events, rules and rule targets for Amazon Cloudwatch using the AWS SDK + for Java. + :keywords: cloudwatch events, add rule, add events, add targets, code examples + +.. include:: common/desc-cloudwatch-events.txt + +Add Events +========== + +To add custom |cw| events, call the |cweclient|'s :methodname:`putEvents` method with a +:aws-java-class:`PutEventsRequest ` object that +contains one or more :aws-java-class:`PutEventsRequestEntry +` objects that provide details about each +event. You can specify several parameters for the entry such as the source and type of the event, +resources associated with the event, and so on. + +.. note:: You can specify a maximum of 10 events per call to :methodname:`putEvents`. + +**Imports** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/PutEvents.java + :lines: 16-20 + :language: java + +**Code** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/PutEvents.java + :lines: 40-55 + :dedent: 8 + :language: java + + +Add Rules +========= + +To create or update a rule, call the |cweclient|'s :methodname:`putRule` method with a +:aws-java-class:`PutRuleRequest ` with the name of +the rule and optional parameters such as the :cwe-ug:`event pattern +`, IAM role to associate with the rule, and a :cwe-ug:`scheduling +expression ` that describes how often the rule is run. + +**Imports** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/PutRule.java + :lines: 16-20 + :language: java + +**Code** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/PutRule.java + :lines: 41-50 + :dedent: 8 + :language: java + + +Add Targets +=========== + +Targets are the resources that are invoked when a rule is triggered. Example targets include |ec2| +instances, |lam| functions, |ak| streams, |ecs| tasks, |sfn| state machines, and built-in targets. + +To add a target to a rule, call the |cweclient|'s :methodname:`putTargets` method with a +:aws-java-class:`PutTargetsRequest ` containing +the rule to update and a list of targets to add to the rule. + +**Imports** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/PutTargets.java + :lines: 16-20 + :language: java + +**Code** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/PutTargets.java + :lines: 45-56 + :dedent: 8 + :language: java + + +More Information +================ + +* :cwe-ug:`Adding Events with PutEvents ` in the |cwe-ug| +* :cwe-ug:`Schedule Expressions for Rules ` in the |cwe-ug| +* :cwe-ug:`Event Types for CloudWatch Events ` in the |cwe-ug| +* :cwe-ug:`Events and Event Patterns ` in the |cwe-ug| +* :cwe-api:`PutEvents ` in the |cwe-api| +* :cwe-api:`PutTargets ` in the |cwe-api| +* :cwe-api:`PutRule ` in the |cwe-api| diff --git a/doc_source/examples-cloudwatch-use-alarm-actions.rst b/doc_source/examples-cloudwatch-use-alarm-actions.rst new file mode 100644 index 0000000..a317a27 --- /dev/null +++ b/doc_source/examples-cloudwatch-use-alarm-actions.rst @@ -0,0 +1,78 @@ +.. 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. + +########################### +Using Alarm Actions in |CW| +########################### + +.. meta:: + :description: How to enable or disable alarm actions for Amazon Cloudwatch with the AWS SDK for + Java. + :keywords: cloudwatch alarms, enable alarms, disable alarms, code examples + +Using |cw| alarm actions, you can create alarms that perform actions such as automatically stopping, +terminating, rebooting, or recovering |ec2| instances. + +.. note:: Alarm actions can be added to an alarm by using the :aws-java-class:`PutMetricAlarmRequest + `'s :methodname:`setAlarmActions` method when + :doc:`creating an alarm `. + + +Enable Alarm Actions +==================== + +To enable alarm actions for a |cw| alarm, call the |cwclient|'s :methodname:`enableAlarmActions` +with a :aws-java-class:`EnableAlarmActionsRequest +` containing one or more names of alarms whose +actions you want to enable. + +**Imports** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/EnableAlarmActions.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/EnableAlarmActions.java + :lines: 39-45 + :dedent: 8 + :language: java + + +Disable Alarm Actions +===================== + +To disable alarm actions for a |cw| alarm, call the |cwclient|'s :methodname:`disableAlarmActions` +with a :aws-java-class:`DisableAlarmActionsRequest +` containing one or more names of alarms whose +actions you want to disable. + +**Imports** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/DisableAlarmActions.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/cloudwatch/src/main/java/aws/example/cloudwatch/DisableAlarmActions.java + :lines: 39-45 + :dedent: 8 + :language: java + +More Information +================ + +* :cw-ug:`Create Alarms to Stop, Terminate, Reboot, or Recover an Instance ` in + the |cw-ug| +* :cw-api:`PutMetricAlarm ` in the |cw-api| +* :cw-api:`EnableAlarmActions ` in the |cw-api| +* :cw-api:`DisableAlarmActions ` in the |cw-api| diff --git a/doc_source/examples-cloudwatch.rst b/doc_source/examples-cloudwatch.rst new file mode 100644 index 0000000..db3414f --- /dev/null +++ b/doc_source/examples-cloudwatch.rst @@ -0,0 +1,35 @@ +.. 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. + +################################## +|CW| Examples Using the |sdk-java| +################################## + +.. meta:: + :description: Programming Amazon Cloudwatch using the AWS SDK for Java + :keywords: AWS SDK for Java code examples, Cloudwatch + +This section provides examples of programming |cw|_ using the |sdk-java|_. + +.. include:: common/desc-cloudwatch.txt + +For more information about |cw|, see the |cw-ug|_. + +.. include:: includes/complete-examples-note.txt + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + examples-cloudwatch-get-metrics + examples-cloudwatch-publish-custom-metrics + examples-cloudwatch-create-alarms + examples-cloudwatch-use-alarm-actions + examples-cloudwatch-send-events diff --git a/doc_source/examples-crypto-kms.rst b/doc_source/examples-crypto-kms.rst new file mode 100644 index 0000000..b0dc34d --- /dev/null +++ b/doc_source/examples-crypto-kms.rst @@ -0,0 +1,133 @@ +.. 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| client-side encryption with |KMS| managed keys +################################################### + +.. meta:: + :description: How to use the cryptography configuration settings for the AWS SDK for Java + :keywords: AWS SDK for Java code examples, cryptography, encryption + +The following examples use the +: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 +decrypted. + +.. note:: + The following examples demonstrate how to use the |S3| client-side + encryption with |KMS| managed keys. To learn how to use encryption with your own keys, + see :doc:`examples-crypto-masterkey`. + +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 +================ + +Import the following classes for these examples. + +**Imports** + +.. 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; + +.. _strict-authenticated-encryption-kms: + +Strict authenticated encryption +=============================== + +Strict authenticated encryption is the default mode if no :classname:`CryptoMode` is specified. + +To explicitly enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the +:methodName:`withCryptoConfiguration` method. + +.. note:: To use client-side authenticated encryption, you must include the latest + `Bouncy Castle jar `_ file + in the classpath of your application. + +**Code** + +.. 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** + +.. 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** + +.. code-block:: java + + System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3)); + +.. _authenticated-encryption-kms: + +Authenticated encryption mode +============================= + +When you use :classname:`AuthenticatedEncryption` mode, an improved key wrapping algorithm is +applied during encryption. When decrypting in this mode, the algorithm can verify the integrity +of the decrypted object and throw an exception if the check fails. +For more details about how authenticated encryption works, see the +:blog:`Amazon S3 Client-Side Authenticated Encryption ` +blog post. + +.. note:: To use client-side authenticated encryption, you must include the latest + `Bouncy Castle jar `_ + file in the classpath of your application. + +To enable this mode, specify the :classname:`AuthenticatedEncryption` value in the +:methodName:`withCryptoConfiguration` method. + + +**Code** + +.. code-block:: java + + 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 new file mode 100644 index 0000000..5afbd50 --- /dev/null +++ b/doc_source/examples-crypto-masterkey.rst @@ -0,0 +1,110 @@ +.. 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| client-side encryption with client master keys +################################################### + +.. meta:: + :description: How to use the cryptography configuration settings for the AWS SDK for Java + :keywords: AWS SDK for Java code examples + +The following examples use the +: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 +be decrypted. + +.. note:: + The following examples demonstrate using the |S3| client-side + 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 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 +================ + +Import the following classes for these examples. + +**Imports** + +.. code-block:: java + + 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; + +.. _strict-authenticated-encryption: + +Strict authenticated encryption +=============================== + +Strict authenticated encryption is the default mode if no :classname:`CryptoMode` is specified. + +To explicitly enable this mode, specify the :classname:`StrictAuthenticatedEncryption` value in the +:methodName:`withCryptoConfiguration` method. + +.. note:: To use client-side authenticated encryption, you must include the latest + `Bouncy Castle jar `_ file + in the classpath of your application. + +**Code** + +.. code-block:: java + + AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard() + .withRegion(Regions.US_WEST_2) + .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption))) + .withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) + .build(); + + s3Encryption.putObject(bucket_name, ENCRYPTED_KEY2, "This is the 2nd content to encrypt"); + + +Authenticated encryption mode +============================= + +When you use :classname:`AuthenticatedEncryption` mode, an improved key wrapping algorithm is +applied during encryption. When decrypting in this mode, the algorithm can verify the integrity +of the decrypted object and throw an exception if the check fails. +For more details about how authenticated encryption works, see the +:blog:`Amazon S3 Client-Side Authenticated Encryption ` +blog post. + +.. note:: To use client-side authenticated encryption, you must include the latest + `Bouncy Castle jar `_ file + in the classpath of your application. + +To enable this mode, specify the :classname:`AuthenticatedEncryption` value in the +:methodName:`withCryptoConfiguration` method. + +**Code** + +.. code-block:: java + + AmazonS3EncryptionV2 s3EncryptionClientV2 = AmazonS3EncryptionClientV2Builder.standard() + .withRegion(Regions.DEFAULT_REGION) + .withClientConfiguration(new ClientConfiguration()) + .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode(CryptoMode.AuthenticatedEncryption)) + .withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) + .build(); + + s3EncryptionClientV2.putObject(bucket_name, ENCRYPTED_KEY1, "This is the 1st content to encrypt"); + diff --git a/doc_source/examples-crypto.rst b/doc_source/examples-crypto.rst new file mode 100644 index 0000000..c37c681 --- /dev/null +++ b/doc_source/examples-crypto.rst @@ -0,0 +1,49 @@ +.. 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. + +############################### +Use |S3| client-side encryption +############################### + +.. meta:: + :description: How to use the cryptography configuration settings for the AWS SDK for Java + :keywords: AWS SDK for Java code examples + +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. 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 + + examples-crypto-masterkey + examples-crypto-kms + + diff --git a/doc_source/examples-dynamodb-items.rst b/doc_source/examples-dynamodb-items.rst new file mode 100644 index 0000000..b360d0a --- /dev/null +++ b/doc_source/examples-dynamodb-items.rst @@ -0,0 +1,144 @@ +.. 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. + +########################### +Working with Items in |DDB| +########################### + +.. meta:: + :description: How to retrieve (get), add, and update items in Amazon DynamoDB tables. + :keywords: AWS for Java SDK code examples, items from DynamoDB tables + + +In |ddb|, an item is a collection of *attributes*, each of which has a *name* and a *value*. An +attribute value can be a scalar, set, or document type. For more information, see :ddb-dg:`Naming +Rules and Data Types ` in the |ddb-dg|. + +.. _dynamodb-get-item: + +Retrieve (Get) an Item from a Table +=================================== + +Call the |ddbclient|'s :methodname:`getItem` method and pass it a +:aws-java-class:`GetItemRequest ` object with the table +name and primary key value of the item you want. It returns a +:aws-java-class:`GetItemResult ` object. + +You can use the returned :classname:`GetItemResult` object's :methodname:`getItem()` method to +retrieve a :javase-ref:`Map ` of key (String) and value +(:aws-java-class:`AttributeValue `) pairs that are associated +with +the item. + +**Imports** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/GetItem.java + :lines: 15-21 + :language: java + +**Code** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/GetItem.java + :lines: 68-102 + :dedent: 8 + :language: java + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. + + +.. _dynamodb-add-item: + +Add a New Item to a Table +========================= + +Create a :javase-ref:`Map ` of key-value pairs that +represent the item's attributes. These must include values for the table's primary key fields. If the +item identified by the primary key already exists, its fields are *updated* by the request. + +.. note:: If the named table doesn't exist for your account and region, a + :aws-java-class:`ResourceNotFoundException ` is + thrown. + +**Imports** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/PutItem.java + :lines: 15-20 + :language: java + +**Code** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/PutItem.java + :lines: 76-96 + :dedent: 8 + :language: java + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. + + +.. _dynamodb-update-item: + +Update an Existing Item in a Table +================================== + +You can update an attribute for an item that already exists in a table by using the |ddbclient|'s +:methodname:`updateItem` method, providing a table name, primary key value, and a map of fields to +update. + +.. note:: If the named table doesn't exist for your account and region, or if the item identified by + the primary key you passed in doesn't exist, a :aws-java-class:`ResourceNotFoundException + ` is thrown. + +**Imports** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateItem.java + :lines: 15-22 + :language: java + +**Code** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateItem.java + :lines: 82-105 + :dedent: 8 + :language: java + +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 +========= + +* :ddb-dg:`Guidelines for Working with Items ` in the |ddb-dg| +* :ddb-dg:`Working with Items in DynamoDB ` in the |ddb-dg| diff --git a/doc_source/examples-dynamodb-tables.rst b/doc_source/examples-dynamodb-tables.rst new file mode 100644 index 0000000..faff57d --- /dev/null +++ b/doc_source/examples-dynamodb-tables.rst @@ -0,0 +1,226 @@ +.. 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. + +############################ +Working with Tables in |DDB| +############################ + +.. meta:: + :description: How to create, describe, modify (update) and delete Amazon DynamoDB tables. + :keywords: AWS SDK for Java code examples, DynamoDB tables + + +Tables are the containers for all items in a |DDB| database. Before you can add or remove data from +|DDB|, you must create a table. + +For each table, you must define: + +* A table *name* that is unique for your account and region. + +* A *primary key* for which every value must be unique; no two items in your table can have the + same primary key value. + + A primary key can be *simple*, consisting of a single partition (HASH) key, or *composite*, consisting + of a partition and a sort (RANGE) key. + + Each key value has an associated *data type*, enumerated by the + :aws-java-class:`ScalarAttributeType ` class. The key + value can be binary (B), numeric (N), or a string (S). For more information, see + :ddb-dg:`Naming Rules and Data Types ` in the |ddb-dg|. + +* *Provisioned throughput* values that define the number of reserved read/write capacity units + for the table. + + .. tip:: :pricing:`Amazon DynamoDB pricing ` is based on the provisioned throughput + values that you set on your tables, so reserve only as much capacity as you think + you'll need for your table. + + Provisioned throughput for a table can be modified at any time, so you can adjust capacity + if your needs change. + +.. _dynamodb-create-table: + +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. 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. + +.. These Imports/Code headings are sufficient without the colons + +**Imports** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/CreateTable.java + :lines: 15-24 + :language: java + +.. _dynamodb-create-table-simple: + +Create a Table with a Simple Primary Key +---------------------------------------- + +This code creates a table with a simple primary key ("Name"). + +**Code** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/CreateTable.java + :lines: 59-75 + :dedent: 8 + :language: java + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. + +.. _dynamodb-create-table-composite: + +Create a Table with a Composite Primary Key +--------------------------------------------- + +Add another +:aws-java-class:`AttributeDefinition ` and +:aws-java-class:`KeySchemaElement ` to +:aws-java-class:`CreateTableRequest `. + +**Code** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/CreateTableCompositeKey.java + :lines: 59-68 + :dedent: 8 + :language: java + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. + +.. _dynamodb-list-tables: + +List Tables +=========== + +You can list the tables in a particular region by calling the :aws-java-class:`DynamoDB client +`'s :methodname:`listTables` method. + +.. note:: If the named table doesn't exist for your account and region, a + :aws-java-class:`ResourceNotFoundException ` + is thrown. + +**Imports** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/ListTables.java + :lines: 15-19 + :language: java + +**Code** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/ListTables.java + :lines: 33-67 + :dedent: 8 + :language: java + +By default, up to 100 tables are returned per call |mdash| use +:methodname:`getLastEvaluatedTableName` on the returned :aws-java-class:`ListTablesResult ` object +to get the last table that was evaluated. You can use this value to start the listing after the last +returned +value of the previous listing. + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. + +.. _dynamodb-describe-table: + +Describe (Get Information about) a Table +======================================== + +Call the :aws-java-class:`DynamoDB client +`'s :methodname:`describeTable` method. + +.. note:: If the named table doesn't exist for your account and region, a + :aws-java-class:`ResourceNotFoundException ` + is thrown. + +**Imports** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/DescribeTable.java + :lines: 15-20 + :language: java + +**Code** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/DescribeTable.java + :lines: 51-88 + :dedent: 8 + :language: java + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. + + +.. _dynamodb-update-table: + +Modify (Update) a Table +======================= + +You can modify your table's provisioned throughput values at any time by calling the +:aws-java-class:`DynamoDB client `'s :methodname:`updateTable` +method. + +.. note:: If the named table doesn't exist for your account and region, a + :aws-java-class:`ResourceNotFoundException ` + is thrown. + +**Imports** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateTable.java + :lines: 15-18 + :language: java + +**Code** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateTable.java + :lines: 57-68 + :dedent: 8 + :language: java + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. + + +.. _dynamodb-delete-table: + +Delete a Table +============== + +Call the :aws-java-class:`DynamoDB client `'s +:methodname:`deleteTable` method and pass it the table's name. + +.. note:: If the named table doesn't exist for your account and region, a + :aws-java-class:`ResourceNotFoundException ` + is thrown. + +**Imports** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/DeleteTable.java + :lines: 15-17 + :language: java + +**Code** + +.. literalinclude:: example_code/dynamodb/src/main/java/aws/example/dynamodb/DeleteTable.java + :lines: 52-59 + :dedent: 8 + :language: java + +See the :sdk-examples-java-dynamodb:`complete example ` on GitHub. + +More Info +========= + +* :ddb-dg:`Guidelines for Working with Tables ` in the |ddb-dg| +* :ddb-dg:`Working with Tables in DynamoDB ` in the |ddb-dg| diff --git a/doc_source/advanced.rst b/doc_source/examples-dynamodb.rst similarity index 53% rename from doc_source/advanced.rst rename to doc_source/examples-dynamodb.rst index eb2406a..1ede57b 100644 --- a/doc_source/advanced.rst +++ b/doc_source/examples-dynamodb.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,20 +8,21 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -############### -Advanced Topics -############### +################################### +|ddb| Examples Using the |sdk-java| +################################### -The topics in this section extend the content in :doc:`basics`, presenting information about -advanced programming techniques and comprehensive examples of using the |sdk-java|. +This section provides examples of programming |ddb|_ using the |sdk-java|_. -.. tip:: See :ref:`additional-resources` for more examples and additional resources available for - |sdk-java| developers! +.. meta:: + :description: Programming Amazon DynamoDB using the AWS SDK for Java + :keywords: AWS SDK for Java code examples + +.. include:: includes/complete-examples-note.txt .. toctree:: + :titlesonly: :maxdepth: 1 - section-client-configuration - java-dg-access-control - java-dg-jvm-ttl - + examples-dynamodb-tables + examples-dynamodb-items diff --git a/doc_source/examples-ec2-elastic-ip.rst b/doc_source/examples-ec2-elastic-ip.rst new file mode 100644 index 0000000..b13cade --- /dev/null +++ b/doc_source/examples-ec2-elastic-ip.rst @@ -0,0 +1,123 @@ +.. 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. + +################################### +Using Elastic IP Addresses in |EC2| +################################### + +.. meta:: + :description: How to allocate, use, list, and release Elastic IP addresses for EC2 instances with + the AWS SDK for Java. + :keywords: AWS SDK for Java, code examples, EC2, Elastic IP, allocate address, release address, + assign address, associate address, list addresses + + +Allocating an Elastic IP Address +================================ + +To use an Elastic IP address, you first allocate one to your account, and then associate it with +your instance or a network interface. + +To allocate an Elastic IP address, call the |ec2client|'s :methodname:`allocateAddress` method with +an :aws-java-class:`AllocateAddressRequest ` object +containing the network type (classic EC2 or VPC). + +The returned :aws-java-class:`AllocateAddressResult ` +contains an allocation ID that you can use to associate the address with an instance, by passing the +allocation ID and instance ID in a :aws-java-class:`AssociateAddressRequest +` to the |ec2client|'s :methodname:`associateAddress` +method. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/AllocateAddress.java + :lines: 16-22 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/AllocateAddress.java + :lines: 42-58 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Describing Elastic IP Addresses +=============================== + +To list the Elastic IP addresses assigned to your account, call the |ec2client|'s +:methodname:`describeAddresses` method. It returns a :aws-java-class:`DescribeAddressesResult +` which you can use to get a list of +:aws-java-class:`Address ` objects that represent the Elastic IP +addresses on your account. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeAddresses.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeAddresses.java + :lines: 28-42 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Releasing an Elastic IP Address +=============================== + +To release an Elastic IP address, call the |ec2client|'s :methodname:`releaseAddress` method, +passing it a :aws-java-class:`ReleaseAddressRequest ` +containing the allocation ID of the Elastic IP address you want to release. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/ReleaseAddress.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/ReleaseAddress.java + :lines: 39-44 + :dedent: 8 + :language: java + +After you release an Elastic IP address, it is released to the AWS IP address pool and might be +unavailable to you afterward. Be sure to update your DNS records and any servers or devices that +communicate with the address. If you attempt to release an Elastic IP address that you already +released, you'll get an *AuthFailure* error if the address is already allocated to another AWS +account. + +If you are using *EC2-Classic* or a *default VPC*, then releasing an Elastic IP address +automatically disassociates it from any instance that it's associated with. To disassociate an +Elastic IP address without releasing it, use the |ec2client|'s :methodname:`disassociateAddress` +method. + +If you are using a non-default VPC, you *must* use :methodname:`disassociateAddress` to disassociate +the Elastic IP address before you try to release it. Otherwise, |EC2| returns an error +(*InvalidIPAddress.InUse*). + +See the :sdk-examples-java-ec2:`complete example `. + + +More Information +================ + +* :ec2-ug:`Elastic IP Addresses ` in the |ec2-ug| +* :ec2-api:`AllocateAddress` in the |ec2-api| +* :ec2-api:`DescribeAddresses` in the |ec2-api| +* :ec2-api:`ReleaseAddress` in the |ec2-api| diff --git a/doc_source/examples-ec2-instances.rst b/doc_source/examples-ec2-instances.rst new file mode 100644 index 0000000..88e681f --- /dev/null +++ b/doc_source/examples-ec2-instances.rst @@ -0,0 +1,209 @@ +.. 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. + +######################## +Managing |EC2| Instances +######################## + +.. meta:: + :description: How to create, start, stop, reboot, list and monitor EC2 instances using the AWS + SDK for Java. + :keywords: AWS SDK for Java, code examples, EC2 instances, create instance, start instance, stop + instance, reboot instance, monitor instance, list instances, describe instances + +Creating an Instance +==================== + +Create a new |EC2| instance by calling the |ec2client|'s :methodname:`runInstances` method, +providing it with a :aws-java-class:`RunInstancesRequest ` +containing the :ec2-ug:`Amazon Machine Image (AMI) ` to use and an :ec2-ug:`instance type +`. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/CreateInstance.java + :lines: 16-20 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/CreateInstance.java + :lines: 44-54 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Starting an Instance +==================== + +To start an |EC2| instance, call the |ec2client|'s :methodname:`startInstances` method, providing it +with a :aws-java-class:`StartInstancesRequest ` containing +the ID of the instance to start. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/StartStopInstance.java + :lines: 16-17, 20 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/StartStopInstance.java + :lines: 30-31, 49-52 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Stopping an Instance +==================== + +To stop an |EC2| instance, call the |ec2client|'s :methodname:`stopInstances` method, providing it +with a :aws-java-class:`StopInstancesRequest ` containing +the ID of the instance to stop. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/StartStopInstance.java + :lines: 16-17, 21 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/StartStopInstance.java + :lines: 59-60, 77-80 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Rebooting an Instance +===================== + +To reboot an |EC2| instance, call the |ec2client|'s :methodname:`rebootInstances` method, providing it +with a :aws-java-class:`RebootInstancesRequest ` containing +the ID of the instance to reboot. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/RebootInstance.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/RebootInstance.java + :lines: 39-44 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Describing Instances +==================== + +To list your instances, create a :aws-java-class:`DescribeInstancesRequest +` and call the |ec2client|'s +:methodname:`describeInstances` method. It will return a :aws-java-class:`DescribeInstancesResult +` object that you can use to list the |EC2| instances +for your account and region. + +Instances are grouped by *reservation*. Each reservation corresponds to the call to +:methodname:`startInstances` that launched the instance. To list your instances, you must first call +the :classname:`DescribeInstancesResult` class' :methodname:`getReservations' method, and then call +:methodname:`getInstances` on each returned :aws-java-class:`Reservation +` object. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeInstances.java + :lines: 16-21 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeInstances.java + :lines: 30-58 + :dedent: 8 + :language: java + +Results are paged; you can get further results by passing the value returned from the result +object's :methodname:`getNextToken` method to your original request object's +:methodname:`setNextToken` method, then using the same request object in your next call to +:methodname:`describeInstances`. + +See the :sdk-examples-java-ec2:`complete example `. + + +Monitoring an Instance +====================== + +You can monitor various aspects of your |EC2| instances, such as CPU and network utilization, +available memory, and disk space remaining. To learn more about instance monitoring, see +:ec2-ug:`Monitoring Amazon EC2 ` in the |ec2-ug|. + +To start monitoring an instance, you must create a :aws-java-class:`MonitorInstancesRequest +` with the ID of the instance to monitor, and pass it to +the |ec2client|'s :methodname:`monitorInstances` method. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/MonitorInstance.java + :lines: 16-18 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/MonitorInstance.java + :lines: 30-31, 50-53 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Stopping Instance Monitoring +============================ + +To stop monitoring an instance, create an :aws-java-class:`UnmonitorInstancesRequest +` with the ID of the instance to stop monitoring, and +pass it to the |ec2client|'s :methodname:`unmonitorInstances` method. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/MonitorInstance.java + :lines: 16-17, 19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/MonitorInstance.java + :lines: 62-63, 82-85 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +More Information +================ + +* :ec2-api:`RunInstances` in the |ec2-api| +* :ec2-api:`DescribeInstances` in the |ec2-api| +* :ec2-api:`StartInstances` in the |ec2-api| +* :ec2-api:`StopInstances` in the |ec2-api| +* :ec2-api:`RebootInstances` in the |ec2-api| +* :ec2-api:`MonitorInstances` in the |ec2-api| +* :ec2-api:`UnmonitorInstances` in the |ec2-api| diff --git a/doc_source/examples-ec2-key-pairs.rst b/doc_source/examples-ec2-key-pairs.rst new file mode 100644 index 0000000..4461cff --- /dev/null +++ b/doc_source/examples-ec2-key-pairs.rst @@ -0,0 +1,98 @@ +.. 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. + +############################ +Working with |EC2| Key Pairs +############################ + +.. meta:: + :description: How to create, list and delete EC2 key pairs using the AWS SDK for Java. + :keywords: AWS SDK for Java, code examples, EC2 key pairs, create key pair, list key pairs, delete + key pair + + +Creating a Key Pair +=================== + +To create a key pair, call the |ec2client|'s :methodname:`createKeyPair` method with a +:aws-java-class:`CreateKeyPairRequest ` that contains the +key's name. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/CreateKeyPair.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/CreateKeyPair.java + :lines: 39-44 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Describing Key Pairs +==================== + +To list your key pairs or to get information about them, call the |ec2client|'s +:methodname:`describeKeyPairs` method. It returns a :aws-java-class:`DescribeKeyPairsResult +` that you can use to access the list of key pairs by +calling its :methodname:`getKeyPairs` method, which returns a list of :aws-java-class:`KeyPairInfo +` objects. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeKeyPairs.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeKeyPairs.java + :lines: 28-38 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Deleting a Key Pair +=================== + +To delete a key pair, call the |ec2client|'s :methodname:`deleteKeyPair` method, passing it a +:aws-java-class:`DeleteKeyPairRequest ` that contains the +name of the key pair to delete. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DeleteKeyPair.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DeleteKeyPair.java + :lines: 39-44 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +More Information +================ + +* :ec2-ug:`Amazon EC2 Key Pairs ` in the |ec2-ug| +* :ec2-api:`CreateKeyPair` in the |ec2-api| +* :ec2-api:`DescribeKeyPairs` in the |ec2-api| +* :ec2-api:`DeleteKeyPair` in the |ec2-api| diff --git a/doc_source/examples-ec2-regions-zones.rst b/doc_source/examples-ec2-regions-zones.rst new file mode 100644 index 0000000..568ae5e --- /dev/null +++ b/doc_source/examples-ec2-regions-zones.rst @@ -0,0 +1,107 @@ +.. 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. + +################################## +Use regions and availability zones +################################## + +.. meta:: + :description: How to list EC2 regions and availability zones using the AWS SDK for Java. + :keywords: AWS SDK for Java, code examples, EC2, list regions, describe regions, list availability + zones, describe availability zones + + +Describe regions +================ + +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. + +**Imports** + +.. literalinclude:: ec2.java1.describe_region_and_zones.import.txt + :language: java + +**Code** + +.. literalinclude:: ec2.java1.describe_region_and_zones.regions.txt + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Describe availability zones +=========================== + +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. + +**Imports** + +.. literalinclude:: ec2.java1.describe_region_and_zones.import.txt + :language: java + +**Code** + +.. 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 +================ + +* :ec2-ug:`Regions and Availability Zones ` in the |ec2-ug| +* :ec2-api:`DescribeRegions` in the |ec2-api| +* :ec2-api:`DescribeAvailabilityZones` in the |ec2-api| diff --git a/doc_source/examples-ec2-security-groups.rst b/doc_source/examples-ec2-security-groups.rst new file mode 100644 index 0000000..7900120 --- /dev/null +++ b/doc_source/examples-ec2-security-groups.rst @@ -0,0 +1,135 @@ +.. 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. + +##################################### +Working with Security Groups in |EC2| +##################################### + +.. meta:: + :description: How to create, configure and delete EC2 security groups with the AWS SDK for Java. + :keywords: AWS SDK for Java, code examples, EC2 security groups, create a security group, ingress + rules, egress rules, IP permissions, EC2 access + + +Creating a Security Group +========================= + +To create a security group, call the |ec2client|'s :methodname:`createSecurityGroup` method with a +:aws-java-class:`CreateSecurityGroupRequest ` that +contains the key's name. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/CreateSecurityGroup.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/CreateSecurityGroup.java + :lines: 45-54 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Configuring a Security Group +============================ + +A security group can control both inbound (ingress) and outbound (egress) traffic to your |EC2| +instances. + +To add ingress rules to your security group, use the |ec2client|'s +:methodname:`authorizeSecurityGroupIngress` method, providing the name of the security group and the +access rules (:aws-java-class:`IpPermission `) you want to assign +to it within an :aws-java-class:`AuthorizeSecurityGroupIngressRequest +` object. The following example shows how +to add IP permissions to a security group. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/CreateSecurityGroup.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/CreateSecurityGroup.java + :lines: 60-81 + :dedent: 8 + :language: java + +To add an egress rule to the security group, provide similar data in an +:aws-java-class:`AuthorizeSecurityGroupEgressRequest +` to the |ec2client|'s +:methodname:`authorizeSecurityGroupEgress` method. + +See the :sdk-examples-java-ec2:`complete example `. + + +Describing Security Groups +========================== + +To describe your security groups or get information about them, call the |ec2client|'s +:methodname:`describeSecurityGroups` method. It returns a +:aws-java-class:`DescribeSecurityGroupsResult ` +that you can use to access the list of security groups by calling its +:methodname:`getSecurityGroups` method, which returns a list of :aws-java-class:`SecurityGroupInfo +` objects. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeSecurityGroups.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DescribeSecurityGroups.java + :lines: 28-38 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +Deleting a Security Group +========================= + +To delete a security group, call the |ec2client|'s :methodname:`deleteSecurityGroup` method, passing +it a :aws-java-class:`DeleteSecurityGroupRequest ` +that contains the ID of the security group to delete. + +**Imports** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DeleteSecurityGroup.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/ec2/src/main/java/aws/example/ec2/DeleteSecurityGroup.java + :lines: 39-44 + :dedent: 8 + :language: java + +See the :sdk-examples-java-ec2:`complete example `. + + +More Information +================ + +* :ec2-ug:`Amazon EC2 Security Groups ` in the |ec2-ug| +* :ec2-ug:`Authorizing Inbound Traffic for Your Linux Instances ` in the |ec2-ug| +* :ec2-api:`CreateSecurityGroup` in the |ec2-api| +* :ec2-api:`DescribeSecurityGroups` in the |ec2-api| +* :ec2-api:`DeleteSecurityGroup` in the |ec2-api| +* :ec2-api:`AuthorizeSecurityGroupIngress` in the |ec2-api| diff --git a/doc_source/examples-iam-access-keys.rst b/doc_source/examples-iam-access-keys.rst new file mode 100644 index 0000000..fd904e2 --- /dev/null +++ b/doc_source/examples-iam-access-keys.rst @@ -0,0 +1,173 @@ +.. 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. + +########################## +Managing |IAM| Access Keys +########################## + +.. meta:: + :description: How to manage IAM access keys with the AWS SDK for Java. + :keywords: AWS SDK for Java, code examples, IAM access keys, creating, listing, updating, + deleting, getting last access time + + +Creating an Access Key +====================== + +To create an |IAM| access key, call the |iamclient| :methodname:`createAccessKey` method with an +:aws-java-class:`CreateAccessKeyRequest ` +object. + +:classname:`CreateAccessKeyRequest` has two constructors — one that takes a user name and another +with no parameters. If you use the version that takes no parameters, you must set the user name +using the :methodname:`withUserName` setter method before passing it to the +:methodname:`createAccessKey` method. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/CreateAccessKey.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/CreateAccessKey.java + :lines: 39-45 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Listing Access Keys +=================== + +To list the access keys for a given user, create a :aws-java-class:`ListAccessKeysRequest +` object that contains the user name to +list keys for, and pass it to the |iamclient|'s :methodname:`listAccessKeys` method. + +.. note:: If you do not supply a user name to :methodname:`listAccessKeys`, it will attempt to list + access keys associated with the AWS account that signed the request. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/ListAccessKeys.java + :lines: 16-20 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/ListAccessKeys.java + :lines: 39-61 + :dedent: 8 + :language: java + +The results of :methodname:`listAccessKeys` are paged (with a default maximum of 100 records per +call). You can call :methodname:`getIsTruncated` on the returned +:aws-java-class:`ListAccessKeysResult ` +object to see if the query returned fewer results then are available. If so, then call +:methodname:`setMarker` on the :classname:`ListAccessKeysRequest` and pass it back to the next +invocation of :methodname:`listAccessKeys`. + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Retrieving an Access Key's Last Used Time +========================================= + +To get the time an access key was last used, call the |iamclient|'s +:methodname:`getAccessKeyLastUsed` method with the access key's ID (which can be passed in using a +:aws-java-class:`GetAccessKeyLastUsedRequest +` object, or directly to the overload +that takes the access key ID directly. + +You can then use the returned :aws-java-class:`GetAccessKeyLastUsedResult +` object to retrieve the key's last +used time. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/AccessKeyLastUsed.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/AccessKeyLastUsed.java + :lines: 38-47 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +.. _iam-access-keys-update: + +Activating or Deactivating Access Keys +====================================== + +You can activate or deactivate an access key by creating an :aws-java-class:`UpdateAccessKeyRequest +` object, providing the access key ID, +optionally the user name, and the desired :aws-java-class:`Status +`, then passing the request object to the +|iamclient|'s :methodname:`updateAccessKey` method. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/UpdateAccessKey.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/UpdateAccessKey.java + :lines: 41-49 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Deleting an Access Key +====================== + +To permanently delete an access key, call the |iamclient|'s :methodname:`deleteKey` method, +providing it with a :aws-java-class:`DeleteAccessKeyRequest +` containing the access key's ID and +username. + +.. note:: Once deleted, a key can no longer be retrieved or used. To temporarily deactivate a key so + that it can be activated again later, use :ref:`updateAccessKey ` method + instead. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/DeleteAccessKey.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/DeleteAccessKey.java + :lines: 39-46 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +More Information +================ + +* :iam-api:`CreateAccessKey` in the |iam-api| +* :iam-api:`ListAccessKeys` in the |iam-api| +* :iam-api:`GetAccessKeyLastUsed` in the |iam-api| +* :iam-api:`UpdateAccessKey` in the |iam-api| +* :iam-api:`DeleteAccessKey` in the |iam-api| diff --git a/doc_source/examples-iam-account-aliases.rst b/doc_source/examples-iam-account-aliases.rst new file mode 100644 index 0000000..d94f774 --- /dev/null +++ b/doc_source/examples-iam-account-aliases.rst @@ -0,0 +1,104 @@ +.. 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. + +########################### +Using |IAM| Account Aliases +########################### + +.. meta:: + :description: How to set, get, and delete a policy for an Amazon S3 bucket. + :keywords: AWS for Java SDK code examples, bucket policies + +If you want the URL for your sign-in page to contain your company name or other friendly identifier +instead of your AWS account ID, you can create an alias for your AWS account. + +.. note:: AWS supports exactly one account alias per account. + + +Creating an Account Alias +========================= + +To create an account alias, call the |iamclient|'s :methodname:`createAccountAlias` method with a +:aws-java-class:`CreateAccountAliasRequest +` object that contains the alias name. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/CreateAccountAlias.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/CreateAccountAlias.java + :lines: 38-44 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Listing Account Aliases +======================= + +To list your account's alias, if any, call the |iamclient|'s :methodname:`listAccountAliases` +method. + +.. note:: The returned :aws-java-class:`ListAccountAliasesResponse + ` supports the same + :methodname:`getIsTruncated` and :methodname:`getMarker` methods as other |sdk-java| *list* + methods, but an AWS account can have only *one* account alias. + +**imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/ListAccountAliases.java + :lines: 16-18 + :language: java + +**code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/ListAccountAliases.java + :lines: 26-33 + :dedent: 8 + :language: java + +see the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Deleting an account alias +========================= + +To delete your account's alias, call the |iamclient|'s :methodname:`deleteAccountAlias` method. When +deleting an account alias, you must supply its name using a +:aws-java-class:`DeleteAccountAliasRequest +` object. + +**imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/DeleteAccountAlias.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/DeleteAccountAlias.java + :lines: 38-44 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + +More Information +================ + +* :iam-ug:`Your AWS Account ID and Its Alias ` in the |iam-ug| +* :iam-api:`CreateAccountAlias` in the |iam-api| +* :iam-api:`ListAccountAliases` in the |iam-api| +* :iam-api:`DeleteAccountAlias` in the |iam-api| diff --git a/doc_source/examples-iam-policies.rst b/doc_source/examples-iam-policies.rst new file mode 100644 index 0000000..b2ab3b2 --- /dev/null +++ b/doc_source/examples-iam-policies.rst @@ -0,0 +1,162 @@ +.. 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. + +########################### +Working with |IAM| Policies +########################### + +.. meta:: + :description: How to set, get, and delete a policy for an Amazon S3 bucket. + :keywords: AWS for Java SDK code examples, bucket policies + +Creating a Policy +================= + +To create a new policy, provide the policy's name and a JSON-formatted policy document in a +:aws-java-class:`CreatePolicyRequest ` to the +|iamclient|'s :methodname:`createPolicy` method. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/CreatePolicy.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/CreatePolicy.java + :lines: 62-69 + :dedent: 8 + :language: java + +|iam| policy documents are JSON strings with a :iam-ug:`well-documented syntax +`. Here is an example that provides access to make particular requests +to |ddb|. + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/CreatePolicy.java + :lines: 26-47 + :dedent: 4 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Getting a Policy +================ + +To retrieve an existing policy, call the |iamclient|'s :methodname:`getPolicy` method, providing the +policy's ARN within a :aws-java-class:`GetPolicyRequest +` object. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/GetPolicy.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/GetPolicy.java + :lines: 39-45 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Attaching a Role Policy +======================= + +You can attach a policy to an |IAM| :iam-ug:`role ` by calling the |iamclient|'s +:methodname:`attachRolePolicy` method, providing it with the role name and policy ARN in an +:aws-java-class:`AttachRolePolicyRequest +`. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/AttachRolePolicy.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/AttachRolePolicy.java + :lines: 43-45, 76-81 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Listing Attached Role Policies +============================== + +List attached policies on a role by calling the |iamclient|'s :methodname:`listAttachedRolePolicies` +method. It takes a :aws-java-class:`ListAttachedRolePoliciesRequest +` object that contains the role +name to list the policies for. + +Call :methodname:`getAttachedPolicies` on the returned +:aws-java-class:`ListAttachedRolePoliciesResult +` object to get the list of +attached policies. Results may be truncated; if the :classname:`ListAttachedRolePoliciesResult` +object's :methodname:`getIsTruncated` method returns :code-java:`true`, call the +:classname:`ListAttachedRolePoliciesRequest` object's :methodname:`setMarker` method and use it to +call :methodname:`listAttachedRolePolicies` again to get the next batch of results. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/AttachRolePolicy.java + :lines: 16-17, 20-24 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/AttachRolePolicy.java + :lines: 43-68 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Detaching a Role Policy +======================= + +To detach a policy from a role, call the |iamclient|'s :methodname:`detachRolePolicy` method, +providing it with the role name and policy ARN in a :aws-java-class:`DetachRolePolicyRequest +`. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/DetachRolePolicy.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/DetachRolePolicy.java + :lines: 39-46 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +More Information +================ + +* :iam-ug:`Overview of IAM Policies ` in the |iam-ug|. +* :iam-ug:`AWS IAM Policy Reference ` in the |iam-ug|. +* :iam-api:`CreatePolicy` in the |iam-api| +* :iam-api:`GetPolicy` in the |iam-api| +* :iam-api:`AttachRolePolicy` in the |iam-api| +* :iam-api:`ListAttachedRolePolicies` in the |iam-api| +* :iam-api:`DetachRolePolicy` in the |iam-api| diff --git a/doc_source/examples-iam-server-certificates.rst b/doc_source/examples-iam-server-certificates.rst new file mode 100644 index 0000000..93f3be4 --- /dev/null +++ b/doc_source/examples-iam-server-certificates.rst @@ -0,0 +1,145 @@ +.. 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. + +###################################### +Working with |IAM| Server Certificates +###################################### + +.. meta:: + :description: How to set, get, and delete a policy for an Amazon S3 bucket. + :keywords: AWS for Java SDK code examples, bucket policies + +To enable HTTPS connections to your website or application on AWS, you need an SSL/TLS *server +certificate*. You can use a server certificate provided by |acmlong| or one that you obtained from +an external provider. + +We recommend that you use |acm| to provision, manage, and deploy your server certificates. With +|acm| you can request a certificate, deploy it to your AWS resources, and let |acm| handle +certificate renewals for you. Certificates provided by |acm| are free. For more information about +|acm| , see the |acm-ug|_. + + +Getting a Server Certificate +============================ + +You can retrieve a server certificate by calling the |iamclient|'s +:methodname:`getServerCertificate` method, passing it a :aws-java-class:`GetServerCertificateRequest +` with the certificate's name. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/GetServerCertificate.java + :lines: 15-18 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/GetServerCertificate.java + :lines: 38-44 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Listing Server Certificates +=========================== + +To list your server certificates, call the |iamclient|'s :methodname:`listServerCertificates` method +with a :aws-java-class:`ListServerCertificatesRequest +`. It returns a +:aws-java-class:`ListServerCertificatesResult +`. + +Call the returned :classname:`ListServerCertificateResult` object's +:methodname:`getServerCertificateMetadataList` method to get a list of +:aws-java-class:`ServerCertificateMetadata +` objects that you can use to get +information about each certificate. + +Results may be truncated; if the :classname:`ListServerCertificateResult` object's +:methodname:`getIsTruncated` method returns :code-java:`true`, call the +:classname:`ListServerCertificatesRequest` object's :methodname:`setMarker` method and use it to +call :methodname:`listServerCertificates` again to get the next batch of results. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/ListServerCertificates.java + :lines: 16-20 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/ListServerCertificates.java + :lines: 28-51 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Updating a Server Certificate +============================= + +You can update a server certificate's name or path by calling the |iamclient|'s +:methodname:`updateServerCertificate` method. It takes a +:aws-java-class:`UpdateServerCertificateRequest +` object set with the server +certificate's current name and either a new name or new path to use. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/UpdateServerCertificate.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/UpdateServerCertificate.java + :lines: 40-49 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Deleting a Server Certificate +============================= + +To delete a server certificate, call the |iamclient|'s :methodname:`deleteServerCertificate` method +with a :aws-java-class:`DeleteServerCertificateRequest +` containing the certificate's +name. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/DeleteServerCertificate.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/DeleteServerCertificate.java + :lines: 38-46 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +More Information +================ + +* :iam-ug:`Working with Server Certificates ` in the |iam-ug| +* :iam-api:`GetServerCertificate` in the |iam-api| +* :iam-api:`ListServerCertificates` in the |iam-api| +* :iam-api:`UpdateServerCertificate` in the |iam-api| +* :iam-api:`DeleteServerCertificate` in the |iam-api| +* |acm-ug|_ diff --git a/doc_source/examples-iam-users.rst b/doc_source/examples-iam-users.rst new file mode 100644 index 0000000..e12eee4 --- /dev/null +++ b/doc_source/examples-iam-users.rst @@ -0,0 +1,125 @@ +.. 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. + +#################### +Managing |IAM| Users +#################### + +.. meta:: + :description: How to set, get, and delete a policy for an Amazon S3 bucket. + :keywords: AWS for Java SDK code examples, bucket policies + +Creating a User +=============== + +Create a new |IAM| user by providing the user name to the |iamclient|'s :methodname:`createUser` +method, either directly or using a :aws-java-class:`CreateUserRequest +` object containing the user name. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/CreateUser.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/CreateUser.java + :lines: 39-45 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Listing Users +============= + +To list the |IAM| users for your account, create a new :aws-java-class:`ListUsersRequest +` and pass it to the |iamclient|'s +:methodname:`listUsers` method. You can retrieve the list of users by calling :methodname:`getUsers` +on the returned :aws-java-class:`ListUsersResponse +` object. + +The list of users returned by :methodname:`listUsers` is paged. You can check to see there are more +results to retrieve by calling the response object's :methodname:`getIsTruncated` method. If it +returns :code-java:`true`, then call the request object's :methodname:`setMarker()` method, passing +it the return value of the response object's :methodname:`getMarker()` method. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/ListUsers.java + :lines: 16-20 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/ListUsers.java + :lines: 28-46 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Updating a User +=============== + +To update a user, call the |iamclient| object's :methodname:`updateUser` method, which takes a +:aws-java-class:`UpdateUserRequest ` object +that you can use to change the user's *name* or *path*. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/UpdateUser.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/UpdateUser.java + :lines: 40-47 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + + +Deleting a User +=============== + +To delete a user, call the |iamclient|'s :methodname:`deleteUser` request with a +:aws-java-class:`UpdateUserRequest ` object set +with the user name to delete. + +**Imports** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/DeleteUser.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/iam/src/main/java/aws/example/iam/DeleteUser.java + :lines: 39-51 + :dedent: 8 + :language: java + +See the :sdk-examples-java-iam:`complete example ` on GitHub. + +More Information +================ + +* :iam-ug:`IAM Users ` in the |iam-ug| +* :iam-ug:`Managing IAM Users ` in the |iam-ug| +* :iam-api:`CreateUser` in the |iam-api| +* :iam-api:`ListUsers` in the |iam-api| +* :iam-api:`UpdateUser` in the |iam-api| +* :iam-api:`DeleteUser` in the |iam-api| diff --git a/doc_source/examples-iam.rst b/doc_source/examples-iam.rst new file mode 100644 index 0000000..46500e3 --- /dev/null +++ b/doc_source/examples-iam.rst @@ -0,0 +1,34 @@ +.. 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. + +################################### +|IAM| Examples Using the |sdk-java| +################################### + +.. meta:: + :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|_ by using the |sdk-java|_. + +.. include:: common/desc-iam.txt + +.. include:: includes/complete-examples-note.txt + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + examples-iam-access-keys + examples-iam-users + examples-iam-account-aliases + examples-iam-policies + examples-iam-server-certificates + diff --git a/doc_source/examples-lambda.rst b/doc_source/examples-lambda.rst new file mode 100644 index 0000000..e524d4d --- /dev/null +++ b/doc_source/examples-lambda.rst @@ -0,0 +1,110 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +################################################# +Invoking, Listing, and Deleting Lambda Functions +################################################# + +.. meta:: + :description: How to invoke, list, and delete a Lambda function by using the AWS SDK for Java 2.x. + :keywords: Amazon Lambda, AWS SDK for Java 2.x, Lambda code examples, + deleteFunction, invoke, listFunctions + + +This section provides examples of programming with the Lambda service client by using the AWS SDK for Java. To learn how to +create a Lambda function, see `How to Create AWS Lambda functions `_. + +.. contents:: + :local: + :depth: 1 + +.. _invoke-function: +Invoke a Lambda function +======================== + +You can invoke a Lambda function by creating an :aws-java-class:`AWSLambda ` +object and invoking its :methodname:`invoke` method. Create an :aws-java-class:`InvokeRequest ` +object to specify additional information such as the function name and the payload to pass to the Lambda function. Function names +appear as *arn:aws:lambda:us-west-2:555556330391:function:HelloFunction*. You can retrieve the value by looking at the function in the AWS Console. + +To pass payload data to a function, invoke the :aws-java-class:`InvokeRequest ` +object's :methodname:`withPayload` method and specify a String in JSON format, as shown in the following code example. + +**Imports** + +.. literalinclude:: lambda.java1.invoke.import.txt + :language: java + +**Code** + +The following code example demonstrates how to invoke a Lambda function. + +.. literalinclude:: lambda.java1.invoke.main.txt + :language: java + +See the complete example on `Github +`_. + + +.. _list-function: + +List Lambda functions +===================== + +Build an :aws-java-class:`AWSLambda ` +object and invoke its :methodname:`listFunctions` method. +This method returns a :aws-java-class:`ListFunctionsResult ` object. +You can invoke this object's :methodname:`getFunctions` method to return a list of :aws-java-class:`FunctionConfiguration ` objects. +You can iterate through the list to retrieve information about the functions. For example, the following Java code example shows how to get each function name. + + +**Imports** + +.. literalinclude:: lambda.java1.list.import.txt + :language: java + +**Code** + +The following Java code example demonstrates how to retrieve a list of Lambda function names. + +.. literalinclude:: lambda.java1.list.main.txt + :language: java + +See the complete example on `Github +`_. + + +.. _delete-function: + +Delete a Lambda function +======================== + +Build an :aws-java-class:`AWSLambda ` +object and invoke its :methodname:`deleteFunction` method. +Create a :aws-java-class:`DeleteFunctionRequest ` +object and pass it to the :methodname:`deleteFunction` method. This object contains information such as the name of the function to delete. +Function names appear as *arn:aws:lambda:us-west-2:555556330391:function:HelloFunction*. You can retrieve the value by looking at the function in the AWS Console. + +**Imports** + +.. literalinclude:: lambda.java1.delete.import.txt + :language: java + +**Code** + +The following Java code demonstrates how to delete a Lambda function. + +.. literalinclude:: lambda.java1.delete.main.txt + :language: java + +See the complete example on `Github +`_. + + diff --git a/doc_source/examples-pinpoint-create-app.rst b/doc_source/examples-pinpoint-create-app.rst new file mode 100644 index 0000000..727f7c8 --- /dev/null +++ b/doc_source/examples-pinpoint-create-app.rst @@ -0,0 +1,72 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +####################################### +Creating and Deleting Apps in |PINlong| +####################################### + +.. meta:: + :description: How to create or delete an app in Amazon pinpoint. + :keywords: AWS for Java SDK code examples, amazon pinpoint + +An app is an |PINlong| project in which you define the audience for a distinct +application, and you engage this audience with tailored messages. The examples on +this page demonstrate how to create a new app or delete an existing one. + +Create an App +============= + +Create a new app in |PINlong| by providing an app name to the :aws-java-class:`CreateAppRequest +` object, and then passing that object to the +|pinpointclient|'s :methodname:`createApp` method. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateApp.java + :lines: 17-21 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateApp.java + :lines: 44-49 + :dedent: 2 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + + +Delete an App +============= + +To delete an app, call the |pinpointclient|'s :methodname:`deleteApp` request with a +:aws-java-class:`DeleteAppRequest ` object that's +set with the app name to delete. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/DeleteApp.java + :lines: 18-19 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/DeleteApp.java + :lines: 42-45 + :dedent: 2 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + +More Information +================ + +* :pin-api:`Apps ` in the |PIN-api| +* :pin-api:`App ` in the |PIN-api| diff --git a/doc_source/examples-pinpoint-create-campaign.rst b/doc_source/examples-pinpoint-create-campaign.rst new file mode 100644 index 0000000..c7548b4 --- /dev/null +++ b/doc_source/examples-pinpoint-create-campaign.rst @@ -0,0 +1,68 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################### +Creating Campaigns in |PINlong| +############################### + +.. meta:: + :description: How to create a campaign in Amazon pinpoint. + :keywords: AWS for Java SDK code examples, amazon pinpoint campaign + +You can use campaigns to help increase engagement between your app and your users. +You can create a campaign to reach out to a particular segment of your users with tailored +messages or special promotions. This example demonstrates how to create a new +standard campaign that sends a custom push notification to a specified segment. + +Create a Campaign +================= + +Before creating a new campaign, you must define a :aws-java-class:`Schedule +` and a :aws-java-class:`Message +` and set these values in a +:aws-java-class:`WriteCampaignRequest ` object. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateCampaign.java + :lines: 18-27 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateCampaign.java + :lines: 53-69 + :dedent: 8 + :language: java + +Then create a new campaign in |PINlong| by providing the :aws-java-class:`WriteCampaignRequest +` with the campaign configuration to a +:aws-java-class:`CreateCampaignRequest` object. Finally, pass the CreateCampaignRequest object to the +|pinpointclient|'s :methodname:`createCampaign` method. + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateCampaign.java + :lines: 71-74 + :dedent: 8 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + +More Information +================ + +* :pin-ug:`Amazon Pinpoint Campaigns ` in the |pin-ug| +* :pin-dg:`Creating Campaigns ` in the |pin-dg| +* :pin-api:`Campaigns ` in the |pin-api| +* :pin-api:`Campaign ` in the |pin-api| +* :pin-api:`Campaign Activities ` in the |pin-api| +* :pin-api:`Campaign Versions ` in the |pin-api| +* :pin-api:`Campaign Version ` in the |pin-api| diff --git a/doc_source/examples-pinpoint-create-endpoint.rst b/doc_source/examples-pinpoint-create-endpoint.rst new file mode 100644 index 0000000..5193644 --- /dev/null +++ b/doc_source/examples-pinpoint-create-endpoint.rst @@ -0,0 +1,62 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################### +Creating Endpoints in |PINlong| +############################### + +.. meta:: + :description: How to update an app endpoint in Amazon pinpoint. + :keywords: AWS for Java SDK code examples, amazon pinpoint endpoint + +An endpoint uniquely identifies a user device to which you can send +push notifications with |PINlong|. If your app is enabled with |PINlong| +support, your app automatically registers an endpoint with |PINlong| +when a new user opens your app. The following example demonstrates how to +add a new endpoint programmatically. + +Create an Endpoint +================== + +Create a new endpoint in |PINlong| by providing the endpoint data in an +:aws-java-class:`EndpointRequest ` object. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateEndpoint.java + :lines: 18-28 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateEndpoint.java + :lines: 92-136 + :dedent: 8 + :language: java + +Then create an :aws-java-class:`UpdateEndpointRequest ` +object with that EndpointRequest object. Finally, pass the UpdateEndpointRequest object to the +|pinpointclient|'s :methodname:`updateEndpoint` method. + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateEndpoint.java + :lines: 73-79 + :dedent: 8 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + + +More Information +================ + +* :pin-dg:`Adding Endpoint ` in the |pin-dg| +* :pin-api:`Endpoint ` in the |pin-api| diff --git a/doc_source/examples-pinpoint-create-segment.rst b/doc_source/examples-pinpoint-create-segment.rst new file mode 100644 index 0000000..90f3175 --- /dev/null +++ b/doc_source/examples-pinpoint-create-segment.rst @@ -0,0 +1,64 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################## +Creating Segments in |PINlong| +############################## + +.. meta:: + :description: How to update an app segment in Amazon pinpoint. + :keywords: AWS for Java SDK code examples, amazon pinpoint segment + +A user segment represents a subset of your users that's based on shared characteristics, such as +how recently a user opened your app or which device they use. The following example demonstrates +how to define a segment of users. + +Create a Segment +================ + +Create a new segment in |PINlong| by defining dimensions of the segment in a +:aws-java-class:`SegmentDimensions ` object. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateSegment.java + :lines: 18-30 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateSegment.java + :lines: 50, 58-74 + :dedent: 8 + :language: java + +Next set the :aws-java-class:`SegmentDimensions ` +object in a :aws-java-class:`WriteSegmentRequest +`, which in turn is used to create a +:aws-java-class:`CreateSegmentRequest ` object. +Then pass the CreateSegmentRequest object to the +|pinpointclient|'s :methodname:`createSegment` method. + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/CreateSegment.java + :lines: 76-82 + :dedent: 8 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + +More Information +================ + +* :pin-ug:`Amazon Pinpoint Segments ` in the |pin-ug| +* :pin-dg:`Creating Segments ` in the |pin-dg| +* :pin-api:`Segments ` in the |pin-api| +* :pin-api:`Segment ` in the |pin-api| diff --git a/doc_source/examples-pinpoint-update-channel.rst b/doc_source/examples-pinpoint-update-channel.rst new file mode 100644 index 0000000..c27a545 --- /dev/null +++ b/doc_source/examples-pinpoint-update-channel.rst @@ -0,0 +1,60 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################## +Updating Channels in |PINlong| +############################## + +.. meta:: + :description: How to update an app channel in Amazon pinpoint. + :keywords: AWS for Java SDK code examples, amazon pinpoint channel + +A channel defines the types of platforms to which you can deliver messages. +This example shows how to use the APNs channel to send a message. + +Update a Channel +================ + +Enable a channel in |PINlong| by providing an app ID and a request object of the channel type +you want to update. This example updates the APNs channel, which requires the +:aws-java-class:`APNSChannelRequest ` object. +Set these in the :aws-java-class:`UpdateApnsChannelRequest ` +and pass that object to the +|pinpointclient|'s :methodname:`updateApnsChannel` method. + +**Imports** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/UpdateChannel.java + :lines: 18-25 + :language: java + +**Code** + +.. literalinclude:: example_code/pinpoint/src/main/java/com/example/pinpoint/UpdateChannel.java + :lines: 66-72 + :dedent: 2 + :language: java + +See the :sdk-examples-java-pinpoint:`complete example ` on GitHub. + + +More Information +================ + +* :pin-ug:`Amazon Pinpoint Channels ` in the |pin-ug| +* :pin-api:`ADM Channel ` in the |pin-api| +* :pin-api:`APNs Channel ` in the |pin-api| +* :pin-api:`APNs Sandbox Channel ` in the |pin-api| +* :pin-api:`APNs VoIP Channel ` in the |pin-api| +* :pin-api:`APNs VoIP Sandbox Channel ` in the |pin-api| +* :pin-api:`Baidu Channel ` in the |pin-api| +* :pin-api:`Email Channel ` in the |pin-api| +* :pin-api:`GCM Channel ` in the |pin-api| +* :pin-api:`SMS Channel ` in the |pin-api| diff --git a/doc_source/examples-pinpoint.rst b/doc_source/examples-pinpoint.rst new file mode 100644 index 0000000..a377c49 --- /dev/null +++ b/doc_source/examples-pinpoint.rst @@ -0,0 +1,31 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +####################################### +|PINlong| Examples Using the |sdk-java| +####################################### + +.. meta:: + :description: Programming Amazon Pinpoint using the AWS SDK for Java + :keywords: AWS SDK for Java code examples + +This section provides examples of programming |PINLong|_ using the |sdk-java|_. + +.. include:: includes/complete-examples-note.txt + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + examples-pinpoint-create-app + examples-pinpoint-create-endpoint + examples-pinpoint-create-segment + examples-pinpoint-create-campaign + examples-pinpoint-update-channel diff --git a/doc_source/examples-s3-access-permissions.rst b/doc_source/examples-s3-access-permissions.rst new file mode 100644 index 0000000..892996d --- /dev/null +++ b/doc_source/examples-s3-access-permissions.rst @@ -0,0 +1,137 @@ +.. 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. + +######################################################## +Managing |S3| Access Permissions for Buckets and Objects +######################################################## + +.. meta:: + :description: How to retrieve or set the access control list for an Amazon S3 bucket. + :keywords: AWS for Java SDK code examples, bucket access permissions + +You can use access control lists (ACLs) for |s3| buckets and objects for fine-grained control over +your |s3| resources. + +.. include:: includes/examples-note.txt + + +Get the Access Control List for a Bucket +======================================== + +To get the current ACL for a bucket, call the |s3client|'s :methodname:`getBucketAcl` method, +passing it the *bucket name* to query. This method returns an :aws-java-class:`AccessControlList +` object. To get each access grant in the list, call its +:methodname:`getGrantsAsList` method, which will return a standard Java list of +:aws-java-class:`Grant ` objects. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/GetAcl.java + :lines: 16-21 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/GetAcl.java + :lines: 35-46 + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +Set the Access Control List for a Bucket +======================================== + +To add or modify permissions to an ACL for a bucket, call the |s3client|'s +:methodname:`setBucketAcl` method. It takes an :aws-java-class:`AccessControlList +` object that contains a list of grantees and access levels to +set. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetAcl.java + :lines: 15-21 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetAcl.java + :lines: 35-48 + :dedent: 8 + :language: java + +.. note:: You can provide the grantee's unique identifier directly using the + :aws-java-class:`Grantee ` class, or use the + :aws-java-class:`EmailAddressGrantee ` class to set the + grantee by email, as we've done here. + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +Get the Access Control List for an Object +========================================= + +To get the current ACL for an object, call the |s3client|'s :methodname:`getObjectAcl` method, +passing it the *bucket name* and *object name* to query. Like :methodname:`getBucketAcl`, this +method returns an :aws-java-class:`AccessControlList ` object +that you can use to examine each :aws-java-class:`Grant `. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/GetAcl.java + :lines: 16-21 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/GetAcl.java + :lines: 54-65 + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +Set the Access Control List for an Object +========================================= + +To add or modify permissions to an ACL for an object, call the |s3client|'s +:methodname:`setObjectAcl` method. It takes an :aws-java-class:`AccessControlList +` object that contains a list of grantees and access levels to +set. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetAcl.java + :lines: 15-21 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetAcl.java + :lines: 56-69 + :dedent: 4 + :language: java + +.. note:: You can provide the grantee's unique identifier directly using the + :aws-java-class:`Grantee ` class, or use the + :aws-java-class:`EmailAddressGrantee ` class to set the + grantee by email, as we've done here. + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + +More Information +================ + +* :s3-api:`GET Bucket acl ` in the |s3-api| +* :s3-api:`PUT Bucket acl ` in the |s3-api| +* :s3-api:`GET Object acl ` in the |s3-api| +* :s3-api:`PUT Object acl ` in the |s3-api| diff --git a/doc_source/examples-s3-bucket-policies.rst b/doc_source/examples-s3-bucket-policies.rst new file mode 100644 index 0000000..f8b8e0c --- /dev/null +++ b/doc_source/examples-s3-bucket-policies.rst @@ -0,0 +1,148 @@ +.. 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. + +##################################################### +Managing Access to |S3| Buckets Using Bucket Policies +##################################################### + +.. meta:: + :description: How to set, get, and delete a policy for an Amazon S3 bucket. + :keywords: AWS for Java SDK code examples, bucket policies + + +You can set, get, or delete a *bucket policy* to manage access to your |S3| buckets. + +.. _set-s3-bucket-policy: + +Set a Bucket Policy +=================== + +You can set the bucket policy for a particular S3 bucket by: + +* Calling the |s3client| client's :methodname:`setBucketPolicy` and providing it with a + :aws-java-class:`SetBucketPolicyRequest ` +* Setting the policy directly by using the :methodname:`setBucketPolicy` overload that takes + a bucket name and policy text (in JSON format) + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetBucketPolicy.java + :lines: 16-18 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetBucketPolicy.java + :dedent: 8 + :lines: 81-86 + :language: java + + +.. _use-s3-bucket-policy-class: + +Use the Policy Class to Generate or Validate a Policy +----------------------------------------------------- + +When providing a bucket policy to :methodname:`setBucketPolicy`, you can do the following: + +* Specify the policy directly as a string of JSON-formatted text +* Build the policy using the :aws-java-class:`Policy ` class + +By using the :classname:`Policy` class, you don't have to be concerned about correctly formatting +your text string. To get the JSON policy text from the :classname:`Policy` class, use its +:methodname:`toJson` method. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetBucketPolicy.java + :lines: 19-24 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetBucketPolicy.java + :dedent: 8 + :lines: 70-77 + :language: java + +The :classname:`Policy` class also provides a :methodname:`fromJson` method that can attempt to +build a policy using a passed-in JSON string. The method validates it to ensure that the text +can be transformed into a valid policy structure, and will fail with an :code-java:`IllegalArgumentException` +if the policy text is invalid. + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/SetBucketPolicy.java + :dedent: 8 + :lines: 55-63 + :language: java + +You can use this technique to prevalidate a policy that you read in from a file or other means. + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _get-s3-bucket-policy: + +Get a Bucket Policy +=================== + +To retrieve the policy for an |S3| bucket, call the |s3client| client's +:methodname:`getBucketPolicy` method, passing it the name of the bucket to get the policy from. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/GetBucketPolicy.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/GetBucketPolicy.java + :dedent: 6 + :lines: 49-56 + :language: java + +If the named bucket doesn't exist, if you don't have access to it, or if it has no bucket policy, +an :classname:`AmazonServiceException` is thrown. + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _delete-s3-bucket-policy: + +Delete a Bucket Policy +====================== + +To delete a bucket policy, call the |s3client| client's :methodname:`deleteBucketPolicy`, +providing it with the bucket name. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucketPolicy.java + :lines: 16-18 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucketPolicy.java + :dedent: 6 + :lines: 48-54 + :language: java + +This method succeeds even if the bucket doesn't already have a policy. If you specify a bucket +name that doesn't exist or if you don't have access to the bucket, an :classname:`AmazonServiceException` +is thrown. + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + +More Info +========= + +* :s3-dg:`Access Policy Language Overview ` in the |S3-dg| +* :s3-dg:`Bucket Policy Examples ` in the |S3-dg| diff --git a/doc_source/examples-s3-buckets.rst b/doc_source/examples-s3-buckets.rst new file mode 100644 index 0000000..91afff7 --- /dev/null +++ b/doc_source/examples-s3-buckets.rst @@ -0,0 +1,162 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +############################################ +Creating, Listing, and Deleting |S3| Buckets +############################################ + +.. meta:: + :description: How to create, list, or delete a bucket using the AWS SDK for Java. + :keywords: Amazon S3, AWS SDK for Java, create bucket, list bucket, delete + bucket, delete versioned bucket + +Every object (file) in |S3| must reside within a *bucket*, which represents a collection (container) +of objects. Each bucket is known by a *key* (name), which must be unique. For detailed information +about buckets and their configuration, see :s3-dg:`Working with Amazon S3 Buckets ` in +the |s3-dg|. + +.. include:: common/s3-note-incomplete-upload-policy.txt + +.. include:: includes/examples-note.txt + +.. _create-bucket: + +Create a Bucket +=============== + +Use the |s3client| client's :methodname:`createBucket` method. The new :aws-java-class:`Bucket +` is returned. The :methodname:`createBucket` method will raise an +exception if the bucket already exists. + +.. tip:: To check whether a bucket already exists before attempting to create one with the same + name, call the :methodname:`doesBucketExist` method. It will return :code-java:`true` if the + bucket exists, and :code-java:`false` otherwise. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/CreateBucket.java + :lines: 16-22 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/CreateBucket.java + :lines: 46-56 + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + +.. _list-buckets: + +List Buckets +============ + +Use the |s3client| client's :methodname:`listBucket` method. If successful, a list of +:aws-java-class:`Bucket ` is returned. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/ListBuckets.java + :lines: 16-21 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/ListBuckets.java + :lines: 32-36 + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + +.. _delete-bucket: + +Delete a Bucket +=============== + +Before you can delete an |S3| bucket, you must ensure that the bucket is empty or an error +will result. If you have a :S3-dg:`versioned bucket `, you must also delete any +versioned objects associated with the bucket. + +.. note:: The :sdk-examples-java-s3:`complete example ` includes each of these + steps in order, providing a complete solution for deleting an |S3| bucket and its contents. + +.. contents:: + :local: + +Remove Objects from an Unversioned Bucket Before Deleting It +------------------------------------------------------------ + +Use the |s3client| client's +:methodname:`listObjects` method to retrieve the list of objects and :methodname:`deleteObject` to +delete each one. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java + :lines: 16-22 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java + :lines: 50-66 + :dedent: 12 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +Remove Objects from a Versioned Bucket Before Deleting It +--------------------------------------------------------- + +If you're using a :S3-dg:`versioned bucket `, you also need to remove any stored +versions of the objects in the bucket before the bucket can be deleted. + +Using a pattern similar to the one used when removing objects within a bucket, remove versioned +objects by using the |s3client| client's :methodname:`listVersions` method to list any versioned +objects, and then :methodname:`deleteVersion` to delete each one. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java + :lines: 16-22 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java + :lines: 68-86 + :dedent: 12 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + +Delete an Empty Bucket +---------------------- + +Once you remove the objects from a bucket (including any versioned objects), you can delete the +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: 16-22 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java + :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 new file mode 100644 index 0000000..2cff970 --- /dev/null +++ b/doc_source/examples-s3-objects.rst @@ -0,0 +1,192 @@ +.. 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. + +##################################### +Performing Operations on |S3| Objects +##################################### + +.. meta:: + :description: How to list, upload, download, copy, rename, move or delete objects in an Amazon + S3 bucket using the AWS SDK for Java. + :keywords: AWS SDK for Java code example + + +An |S3| object represents a *file* or collection of data. Every object must reside within a +:doc:`bucket `. + +.. include:: includes/examples-note.txt + +.. contents:: + :local: + :depth: 1 + + +.. _upload-object: + +Upload an Object +================ + +Use the |s3client| client's :methodname:`putObject` method, supplying a bucket name, key +name, and file to upload. *The bucket must exist, or an error will result*. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/PutObject.java + :lines: 15-18 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/PutObject.java + :lines: 46-53 + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + +.. _list-objects: + +List Objects +============ + +To get a list of objects within a bucket, use the |s3client| client's :methodname:`listObjects` +method, supplying the name of a bucket. + +The :methodname:`listObjects` method returns an :aws-java-class:`ObjectListing +` object that provides information about the objects in the bucket. +To list the object names (keys), use the :methodname:`getObjectSummaries` method to get a List of +:aws-java-class:`S3ObjectSummary ` objects, each of which represents a +single object in the bucket. Then call its :methodname:`getKey` method to retrieve the object's +name. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/ListObjects.java + :lines: 16-20 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/ListObjects.java + :lines: 44-50 + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + +.. _download-object: + +Download an Object +================== + +Use the |s3client| client's :methodname:`getObject` method, passing it the name of a bucket and +object to download. If successful, the method returns an :aws-java-class:`S3Object +`. *The specified bucket and object key must exist, or an error will +result*. + +You can get the object's contents by calling :methodname:`getObjectContent` on the +:classname:`S3Object`. This returns an :aws-java-class:`S3ObjectInputStream +` that behaves as a standard Java :classname:`InputStream` +object. + +The following example downloads an object from S3 and saves its contents to a file (using the same +name as the object's key). + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/GetObject.java + :lines: 15-23 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/GetObject.java + :lines: 50-71 + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + +.. _copy-object: + +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 name. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/CopyObject.java + :lines: 15-17 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/CopyObject.java + :lines: 48-64 + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + +.. note:: You can use :methodname:`copyObject` with :ref:`deleteObject ` to **move** + or **rename** an object, by first copying the object to a new name (you can use the same bucket + as both the source and destination) and then deleting the object from its old location. + + +.. _delete-object: + +Delete an Object +================ + +Use the |s3client| client's :methodname:`deleteObject` method, passing it the name of a bucket and +object to delete. *The specified bucket and object key must exist, or an error will result*. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteObject.java + :lines: 15-17 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteObject.java + :lines: 47-53 + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _delete-objects: + +Delete Multiple Objects at Once +=============================== + +Using the |s3client| client's :methodname:`deleteObjects` method, you can delete multiple objects +from the same bucket by passing their names to the :aws-java-class:`DeleteObjectRequest +` :methodname:`withKeys` method. + +**Imports** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteObjects.java + :lines: 15-18 + :language: java + +**Code** + +.. literalinclude:: example_code/s3/src/main/java/aws/example/s3/DeleteObjects.java + :lines: 52-60 + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. diff --git a/doc_source/examples-s3-transfermanager.rst b/doc_source/examples-s3-transfermanager.rst new file mode 100644 index 0000000..a3e62e7 --- /dev/null +++ b/doc_source/examples-s3-transfermanager.rst @@ -0,0 +1,384 @@ +.. 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. + +######################################### +Using TransferManager for |S3| Operations +######################################### + +.. meta:: + :description: How to use the AWS SDK for Java's TransferManager class to upload, download, and + copy files and directories using Amazon S3. + :keywords: AWS SDK for Java code examples, TransferManager, Amazon S3 transfer operations + +You can use the |sdk-java| |xfermgr| class to reliably transfer files from the local environment to |S3| +and +to copy objects from one S3 location to another. :classname:`TransferManager` can get the progress of +a transfer and pause or resume uploads and downloads. + +.. include:: common/s3-note-incomplete-upload-policy.txt + +.. include:: includes/examples-note.txt + + +.. _transfermanager-uploading: + +Upload Files and Directories +============================ + +|xfermgr| can upload files, file lists, and directories to any |S3| buckets that you've +:ref:`previously created `. + +.. contents:: + :local: + :depth: 1 + + +.. _transfermanager-upload-file: + +Upload a Single File +-------------------- + +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:: s3.java1.s3_xfer_mgr_upload.import.txt + :language: java + +**Code** + +.. uploadFile() method in the example code... + +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.single.txt + :dedent: 8 + :language: java + +The :methodname:`upload` method returns *immediately*, providing an :code-java:`Upload` object to use +to check the transfer state or to wait for it to complete. + +.. include:: includes/transfermanager-complete-get-status-note.txt + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _transfermanager-upload-file-list: + +Upload a List of Files +---------------------- + +To upload multiple files in one operation, call the |xfermgr| :methodname:`uploadFileList` method, +providing the following: + +* An |S3| bucket name +* A *key prefix* to prepend to the names of the created objects (the path within the + bucket in which to place the objects) +* A :javase-ref:`File ` object that represents the relative directory from which to create + file paths +* A :javase-ref:`List ` object containing a set of + :javase-ref:`File ` objects to upload + +**Imports** + +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.import.txt + :language: java + +**Code** + +.. uploadFileList() method in the example code... + +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.list_of_files.txt + :dedent: 8 + :language: java + +.. include:: includes/transfermanager-complete-get-status-note.txt + +.. include:: includes/transfermanager-multifileupload-notes.txt + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _transfermanager-upload-directory: + +Upload a Directory +------------------ + +You can use |xfermgr|'s :methodname:`uploadDirectory` method to upload an entire directory of files, with +the option to copy files in subdirectories recursively. You provide an |S3| bucket +name, an S3 key prefix, a :javase-ref:`File ` object representing the local directory +to copy, and a :code-java:`boolean` value indicating whether you want to copy subdirectories +recursively (*true* or *false*). + +**Imports** + +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.import.txt + :language: java + +**Code** + +.. uploadDir() method in the example code... + +.. literalinclude:: s3.java1.s3_xfer_mgr_upload.directory.txt + :dedent: 8 + :language: java + +.. include:: includes/transfermanager-complete-get-status-note.txt + +.. include:: includes/transfermanager-multifileupload-notes.txt + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _transfermanager-downloading: + +Download Files or Directories +============================= + +Use the |xfermgr| class to download either a single file (|S3| object) or a directory (an |S3| bucket +name followed by an object prefix) from |S3|. + +.. contents:: + :local: + :depth: 1 + + +.. _transfermanager-download-file: + +Download a Single File +---------------------- + +Use the |xfermgr|'s :methodname:`download` method, providing the +|S3| bucket name containing the object you want to download, the key (object) name, and a +:javase-ref:`File ` object that represents the file to create on your local system. + +**Imports** + +.. literalinclude:: s3.java1.s3_xfer_mgr_download.import.txt + :language: java + +**Code** + +.. downloadFile() method in the example code... + +.. literalinclude:: s3.java1.s3_xfer_mgr_download.single.txt + :dedent: 8 + :language: java + +.. include:: includes/transfermanager-complete-get-status-note.txt + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _tranfermanager-download-directory: + +Download a Directory +-------------------- + +To download a set of files that share a common key prefix (analagous to a directory on a +file system) from |S3|, use the |xfermgr| :methodname:`downloadDirectory` method. The method takes the +|S3| bucket name containing the objects you want to download, the object prefix shared by all of the objects, +and a :javase-ref:`File ` object that represents the directory to download the files +into on your local system. If the named directory doesn't exist yet, it will be created. + +**Imports** + +.. literalinclude:: s3.java1.s3_xfer_mgr_download.import.txt + :language: java + +**Code** + +.. downloadFile() method in the example code... + +.. literalinclude:: s3.java1.s3_xfer_mgr_download.directory.txt + :dedent: 8 + :language: java + +.. include:: includes/transfermanager-complete-get-status-note.txt + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _transfermanager-copy-object: + +Copy Objects +============ + +To copy an object from one S3 bucket to another, use the |xfermgr| :methodname:`copy` method. + +**Imports** + +.. literalinclude:: s3.java1.s3_xfer_mgr_copy.import.txt + :language: java + +**Code** + +.. copyObjectSimple() method in the example code... + +.. literalinclude:: s3.java1.s3_xfer_mgr_copy.copy_object.txt + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _transfermanager-wait-for-completion: + +Wait for a Transfer to Complete +=============================== + +If your application (or thread) can block until the transfer completes, you can use the +:aws-java-class:`Transfer ` interface's +:methodname:`waitForCompletion` method to block until the transfer is complete or an exception +occurs. + +.. the waitForCompletion() function in XferMgrProgress.java + +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.wait_for_transfer.txt + :dedent: 8 + :language: java + +.. Already said that the method blocks til complete + +You get progress of transfers if you poll for +events *before* calling :methodname:`waitForCompletion`, implement a polling mechanism on a separate +thread, or receive progress updates asynchronously using a +:aws-java-class:`ProgressListener `. + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _transfermanager-get-status-and-progress: + +Get Transfer Status and Progress +================================ + +Each of the classes returned by the |xfermgr| :methodname:`upload*`, :methodname:`download*`, and +:methodname:`copy` methods returns an instance of one of the following classes, depending on whether +it's a single-file or multiple-file operation. + +.. list-table:: + :header-rows: 1 + + * - Class + - Returned by + + * - :aws-java-class:`Copy ` + - :methodname:`copy` + + * - :aws-java-class:`Download ` + - :methodname:`download` + + * - :aws-java-class:`MultipleFileDownload ` + - :methodname:`downloadDirectory` + + * - :aws-java-class:`Upload ` + - :methodname:`upload` + + * - :aws-java-class:`MultipleFileUpload ` + - :methodname:`uploadFileList`, :methodname:`uploadDirectory` + +All of these classes implement the :aws-java-class:`Transfer ` +interface. :code-java:`Transfer` provides useful methods to get the progress of a transfer, pause +or resume +the transfer, and get the transfer's current or final status. + +.. contents:: + :local: + :depth: 1 + +.. _transfermanager-get-progress-polling: + +Poll the Current Progress of a Transfer +--------------------------------------- + +This loop prints the progress of a transfer, examines its current progress while running and, when complete, +prints its final state. + +**Imports** + +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.import.txt + :language: java + +**Code** + +.. the showTransferProgress() function in XferMgrProgress.java + +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.poll.txt + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _transfermanager-progress-listener: + +Get Transfer Progress with a ProgressListener +--------------------------------------------- + +You can attach a :aws-java-class:`ProgressListener ` to any transfer by +using the :aws-java-class:`Transfer ` interface's +:methodname:`addProgressListener` method. + +A :aws-java-class:`ProgressListener ` requires only one method, +:methodname:`progressChanged`, which takes a :aws-java-class:`ProgressEvent ` +object. You can use the object to get the total bytes of the operation by calling its +:methodname:`getBytes` method, and the number of bytes transferred so far by calling +:methodname:`getBytesTransferred`. + +**Imports** + +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.import.txt + :language: java + +**Code** + +.. the uploadFileWithListener() function in XferMgrProgress.java + +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.progress_listener.txt + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _transfermanager-get-subtransfer-progress: + +Get the Progress of Subtransfers +-------------------------------- + +The :aws-java-class:`MultipleFileUpload ` class can return +information about its subtransfers by calling its :methodname:`getSubTransfers` method. It returns +an unmodifiable :javase-ref:`Collection ` of :aws-java-class:`Upload +` objects that provide the individual transfer status and progress of each +subtransfer. + +**Imports** + +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.import.txt + :language: java + +**Code** + +.. the showMultiUploadProgress() function in XferMgrProgress.java + +.. literalinclude:: s3.java1.s3_xfer_mgr_progress.substranferes.txt + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +.. _transfermanager-see-also: + +More Info +========= + +* :s3-dg:`Object Keys ` in the |s3-dg| diff --git a/doc_source/examples-s3-website-configuration.rst b/doc_source/examples-s3-website-configuration.rst new file mode 100644 index 0000000..2b31a3c --- /dev/null +++ b/doc_source/examples-s3-website-configuration.rst @@ -0,0 +1,104 @@ +.. 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. + +####################################### +Configuring an |s3| Bucket as a Website +####################################### + +.. meta:: + :description: How to set, retrieve, or delete an S3 bucket's website configuration. + :keywords: AWS for Java SDK code examples, s3, website, website configuration + +You can configure an |s3| bucket to behave as a website. To do this, you need to set its website +configuration. + +.. include:: includes/examples-note.txt + +Set a Bucket's Website Configuration +==================================== + +To set an |s3| bucket's website configuration, call the |s3client|'s +:methodname:`setWebsiteConfiguration` method with the bucket name to set the configuration for, and +a :aws-java-class:`BucketWebsiteConfiguration ` object +containing the bucket's website configuration. + +Setting an index document is *required*; all other parameters are optional. + +**Imports** + +.. literalinclude:: s3.java1.s3_set_website_config.import.txt + :language: java + +**Code** + +.. literalinclude:: s3.java1.s3_set_website_config.main.txt + :dedent: 8 + :language: java + +.. note:: Setting a website configuration does not modify the access permissions for your bucket. + To make your files visible on the web, you will also need to set a *bucket policy* that allows + public read access to the files in the bucket. For more information, see + :doc:`examples-s3-bucket-policies`. + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +Get a Bucket's Website Configuration +==================================== + +To get an |s3| bucket's website configuration, call the |s3client|'s +:methodname:`getWebsiteConfiguration` method with the name of the bucket to retrieve the +configuration for. + +The configuration will be returned as a :aws-java-class:`BucketWebsiteConfiguration +` object. If there is no website configuration for the +bucket, then :code-java:`null` will be returned. + +**Imports** + +.. literalinclude:: s3.java1.s3_get_website_config.import.txt + :language: java + +**Code** + +.. literalinclude:: s3.java1.s3_get_website_config.main.txt + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +Delete a Bucket's Website Configuration +======================================= + +To delete an |s3| bucket's website configuration, call the |s3client|'s +:methodname:`deleteWebsiteConfiguration` method with the name of the bucket to delete the +configuration from. + +**Imports** + +.. literalinclude:: s3.java1.s3_delete_website_config.import.txt + :language: java + +**Code** + +.. literalinclude:: s3.java1.s3_delete_website_config.main.txt + :dedent: 8 + :language: java + +See the :sdk-examples-java-s3:`complete example ` on GitHub. + + +More Information +================ + +* :s3-api:`PUT Bucket website ` in the |s3-api| +* :s3-api:`GET Bucket website ` in the |s3-api| +* :s3-api:`DELETE Bucket website ` in the |s3-api| diff --git a/doc_source/examples-s3.rst b/doc_source/examples-s3.rst new file mode 100644 index 0000000..1569a2e --- /dev/null +++ b/doc_source/examples-s3.rst @@ -0,0 +1,34 @@ +.. 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. + +################################## +|S3| Examples Using the |sdk-java| +################################## + +.. meta:: + :description: Programming Amazon S3 using the AWS SDK for Java + :keywords: AWS SDK for Java code examples + + +This section provides examples of programming |S3|_ using the |sdk-java|_. + +.. include:: includes/complete-examples-note.txt + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + examples-s3-buckets + examples-s3-objects + examples-s3-access-permissions + examples-s3-bucket-policies + examples-s3-transfermanager + examples-s3-website-configuration + examples-crypto diff --git a/doc_source/examples-sqs-dead-letter-queues.rst b/doc_source/examples-sqs-dead-letter-queues.rst new file mode 100644 index 0000000..702dde3 --- /dev/null +++ b/doc_source/examples-sqs-dead-letter-queues.rst @@ -0,0 +1,87 @@ +.. 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. + +################################# +Using Dead Letter Queues in |SQS| +################################# + +.. meta:: + :description: How to enable long polling for Amazon SQS message queues. + :keywords: AWS SDK for Java code examples, SQS, long polling, queue management + +|SQS| provides support for *dead letter queues*. A dead letter queue is a queue that other (source) +queues can target for messages that can't be processed successfully. You can set aside and isolate +these messages in the dead letter queue to determine why their processing did not succeed. + +.. _sqs-dead-letter-queue-create-dl-queue: + +Creating a Dead Letter Queue +============================ + +A dead letter queue is created the same way as a regular queue, but it has the following +restrictions: + +* A dead letter queue must be the same type of queue (FIFO or standard) as the source queue. +* A dead letter queue must be created using the same AWS account and region as the source queue. + +Here we create two identical |SQS| queues, one of which will serve as the dead letter queue: + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/DeadLetterQueues.java + :lines: 16-18 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/DeadLetterQueues.java + :lines: 36-54 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +.. _sqs-dead-letter-queue-set-redrive-policy: + +Designating a Dead Letter Queue for a Source Queue +================================================== + +To designate a dead letter queue, you must first create a *redrive policy*, and then set the policy +in the queue's attributes. A redrive policy is specified in JSON, and specifies the ARN of the dead +letter queue and the maximum number of times the message can be received and not processed before +it's sent to the dead letter queue. + +To set the redrive policy for your source queue, call the |sqsclient| class' +:methodname:`setQueueAttributes` method with a :aws-java-class:`SetQueueAttributesRequest +` object for which you've set the ``RedrivePolicy`` +attribute with your JSON redrive policy. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/DeadLetterQueues.java + :lines: 19-21 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/DeadLetterQueues.java + :lines: 57-76 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +More Info +========= + +* :sqs-dg:`Using Amazon SQS Dead Letter Queues ` in the |sqs-dg| +* :sqs-api:`SetQueueAttributes` in the |sqs-api| diff --git a/doc_source/examples-sqs-long-polling.rst b/doc_source/examples-sqs-long-polling.rst new file mode 100644 index 0000000..f3b6dfe --- /dev/null +++ b/doc_source/examples-sqs-long-polling.rst @@ -0,0 +1,113 @@ +.. 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. + +############################################## +Enabling Long Polling for |SQS| Message Queues +############################################## + +.. meta:: + :description: How to enable long polling for Amazon SQS message queues. + :keywords: AWS SDK for Java code examples, SQS, long polling, queue management + +|SQS| uses *short polling* by default, querying only a subset of the servers—based on a weighted +random distribution—to determine whether any messages are available for inclusion in the response. + +Long polling helps reduce your cost of using |SQS| by reducing the number of empty responses when +there are no messages available to return in reply to a ReceiveMessage request sent to an |SQS| +queue and eliminating false empty responses. + +.. note:: You can set a long polling frequency from *1–20 seconds*. + +.. _sqs-long-polling-create-queue: + +Enabling Long Polling when Creating a Queue +=========================================== + +To enable long polling when creating an |SQS| queue, set the ``ReceiveMessageWaitTimeSeconds`` +attribute on the :aws-java-class:`CreateQueueRequest ` object +before calling the |sqsclient| class' :methodname:`createQueue` method. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java + :lines: 40-53 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +.. _sqs-long-polling-existing-queue: + +Enabling Long Polling on an Existing Queue +========================================== + +In addition to enabling long polling when creating a queue, you can also enable it on an existing +queue by setting ``ReceiveMessageWaitTimeSeconds`` on the :aws-java-class:`SetQueueAttributesRequest +` before calling the |sqsclient| class' +:methodname:`setQueueAttributes` method. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java + :lines: 20 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java + :lines: 56-59 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +.. _sqs-long-polling-receive-message: + +Enabling Long Polling on Message Receipt +======================================== + +You can enable long polling when receiving a message by setting the wait time in seconds on the +:aws-java-class:`ReceiveMessageRequest ` that +you supply to the |sqsclient| class' :methodname:`receiveMessage` method. + +.. note:: You should make sure that the AWS client's request timeout is larger than the maximum long + poll time (20s) so that your :methodname:`receiveMessage` requests don't time out while waiting + for the next poll event! + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java + :lines: 21 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java + :lines: 62-65 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + +More Info +========= + +* :sqs-dg:`Amazon SQS Long Polling ` in the |sqs-dg| +* :sqs-api:`CreateQueue` in the |sqs-api| +* :sqs-api:`ReceiveMessage` in the |sqs-api| +* :sqs-api:`SetQueueAttributes` in the |sqs-api| diff --git a/doc_source/examples-sqs-message-queues.rst b/doc_source/examples-sqs-message-queues.rst new file mode 100644 index 0000000..f426f18 --- /dev/null +++ b/doc_source/examples-sqs-message-queues.rst @@ -0,0 +1,153 @@ +.. 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. + +################################# +Working with |SQS| Message Queues +################################# + +.. meta:: + :description: How to create, list, delete, and get an Amazon SQS queue's URL. + :keywords: AWS SDK for Java code example, queue operations + +A *message queue* is the logical container used for sending messages reliably in |sqs|. There are +two types of queues: *standard* and *first-in, first-out* (FIFO). To learn more about queues and the +differences between these types, see the |sqs-dg|_. + +This topic describes how to create, list, delete, and get the URL of an |sqs| queue by using the +|sdk-java|. + + +.. _sqs-create-queue: + +Create a Queue +============== + +Use the |sqsclient| client's :methodname:`createQueue` method, providing a +:aws-java-class:`CreateQueueRequest ` object that describes +the queue parameters. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 16-19 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 31, 34-44 + :dedent: 8 + :language: java + +You can use the simplified form of :methodname:`createQueue`, which needs only a queue name, to +create a standard queue. + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 54 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +.. _sqs-list-queues: + +Listing Queues +============== + +To list the |SQS| queues for your account, call the |sqsclient| client's :methodname:`listQueues` +method. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 16-17, 21 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 31, 57-61 + :dedent: 8 + :language: java + +Using the :methodname:`listQueues` overload without any parameters returns *all queues*. You can +filter the returned results by passing it a :code-java:`ListQueuesRequest` object. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 16-17, 20 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 31, 64-69 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +.. _sqs-get-queue-url: + +Get the URL for a Queue +======================= + +Call the |sqsclient| client's :methodname:`getQueueUrl` method. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 16-17 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 31, 47 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +.. _sqs-delete-queue: + +Delete a Queue +============== + +Provide the queue's :ref:`URL ` to the |sqsclient| client's +:methodname:`deleteQueue` method. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 16-17 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java + :lines: 31, 50 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + +More Info +========= + +* :sqs-dg:`How Amazon SQS Queues Work ` in the |sqs-dg| +* :sqs-api:`CreateQueue` in the |sqs-api| +* :sqs-api:`GetQueueUrl` in the |sqs-api| +* :sqs-api:`ListQueues` in the |sqs-api| +* :sqs-api:`DeleteQueues` in the |sqs-api| diff --git a/doc_source/examples-sqs-messages.rst b/doc_source/examples-sqs-messages.rst new file mode 100644 index 0000000..d4427c9 --- /dev/null +++ b/doc_source/examples-sqs-messages.rst @@ -0,0 +1,126 @@ +.. 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. + + +############################################### +Sending, Receiving, and Deleting |SQS| Messages +############################################### + +.. meta:: + :description: How to send, receive and delete Amazon SQS messages. + :keywords: AWS SDK for Java code examples, Amazon SQS, send message, receive message, delete + message + +This topic describes how to send, receive and delete |SQS| messages. Messages are always delivered +using an :doc:`SQS Queue `. + + +.. _sqs-message-send: + +Send a Message +============== + +Add a single message to an |SQS| queue by calling the |sqsclient| client's +:methodname:`sendMessage` method. Provide a :aws-java-class:`SendMessageRequest +` object that contains the queue's :ref:`URL +`, message body, and optional delay value (in seconds). + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java + :lines: 16-17, 23 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java + :lines: 45-49 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + +.. _sqs-messages-send-multiple: + +Send Multiple Messages at Once +------------------------------ + +You can send more than one message in a single request. To send multiple messages, use the +|sqsclient| client's :methodname:`sendMessageBatch` method, which takes a +:aws-java-class:`SendMessageBatchRequest ` containing +the queue URL and a list of messages (each one a :aws-java-class:`SendMessageBatchRequestEntry +`) to send. You can also set an optional delay +value per message. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java + :lines: 21-22 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java + :lines: 53-61 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +.. _sqs-messages-receive: + +Receive Messages +================ + +Retrieve any messages that are currently in the queue by calling the |sqsclient| client's +:methodname:`receiveMessage` method, passing it the queue's URL. Messages are returned as a list of +:aws-java-class:`Message ` objects. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java + :lines: 17-18, 21 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java + :lines: 64 + :dedent: 8 + :language: java + +.. _sqs-messages-delete: + +Delete Messages after Receipt +============================= + +After receiving a message and processing its contents, delete the message from the queue by sending +the message's receipt handle and queue URL to the |sqsclient| client's +:methodname:`deleteMessage` method. + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java + :lines: 67-69 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +More Info +========= + +* :sqs-dg:`How Amazon SQS Queues Work ` in the |sqs-dg| +* :sqs-api:`SendMessage` in the |sqs-api| +* :sqs-api:`SendMessageBatch` in the |sqs-api| +* :sqs-api:`ReceiveMessage` in the |sqs-api| +* :sqs-api:`DeleteMessage` in the |sqs-api| diff --git a/doc_source/examples-sqs-visibility-timeout.rst b/doc_source/examples-sqs-visibility-timeout.rst new file mode 100644 index 0000000..12f70ce --- /dev/null +++ b/doc_source/examples-sqs-visibility-timeout.rst @@ -0,0 +1,87 @@ +.. 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. + +################################### +Setting Visibility Timeout in |SQS| +################################### + +.. meta:: + :description: How to set visibility timeout for Amazon SQS queues with the AWS SDK for Java. + :keywords: AWS SDK for Java code examples, Amazon SQS, visibility timeout + +When a message is received in |SQS|, it remains on the queue until it's deleted in order to ensure +receipt. A message that was received, but not deleted, will be available in subsequent requests +after a given *visibility timeout* to help prevent the message from being received more than once +before it can be processed and deleted. + +.. note:: When using :sqs-dg:`standard queues `, visibility timeout isn't a + guarantee against receiving a message twice. If you are using a standard queue, be sure that your + code can handle the case where the same message has been delivered more than once. + +.. _sqs-visibility-timeout-receipt: + +Setting the Message Visibility Timeout for a Single Message +=========================================================== + +When you have received a message, you can modify its visibility timeout by passing its receipt +handle in a :aws-java-class:`ChangeMessageVisibilityRequest +` that you pass to the |sqsclient| class' +:methodname:`changeMessageVisibility` method. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/VisibilityTimeout.java + :lines: 16-17 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/VisibilityTimeout.java + :lines: 31-39 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +Setting the Message Visibility Timeout for Multiple Messages at Once +==================================================================== + +To set the message visibility timeout for multiple messages at once, create a list of +:aws-java-class:`ChangeMessageVisibilityBatchRequestEntry +` objects, each containing a unique ID +string and a receipt handle. Then, pass the list to the |sqs| client class' +:methodname:`changeMessageVisibilityBatch` method. + +**Imports** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/VisibilityTimeout.java + :lines: 16-18, 21-22 + :language: java + +**Code** + +.. literalinclude:: example_code/sqs/src/main/java/aws/example/sqs/VisibilityTimeout.java + :lines: 46-67 + :dedent: 8 + :language: java + +See the :sdk-examples-java-sqs:`complete example ` on GitHub. + + +More Info +========= + +* :sqs-dg:`Visibility Timeout ` in the |sqs-dg| +* :sqs-api:`SetQueueAttributes` in the |sqs-api| +* :sqs-api:`GetQueueAttributes` in the |sqs-api| +* :sqs-api:`ReceiveMessage` in the |sqs-api| +* :sqs-api:`ChangeMessageVisibility` in the |sqs-api| +* :sqs-api:`ChangeMessageVisibilityBatch` in the |sqs-api| diff --git a/doc_source/examples-sqs.rst b/doc_source/examples-sqs.rst new file mode 100644 index 0000000..780e0d3 --- /dev/null +++ b/doc_source/examples-sqs.rst @@ -0,0 +1,32 @@ +.. 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. + +################################### +|sqs| Examples Using the |sdk-java| +################################### + +.. meta:: + :description: Programming Amazon SQS using the AWS SDK for Java + :keywords: AWS SDK for Java code examples + +This section provides examples of programming |sqs|_ using the |sdk-java|_. + +.. include:: includes/complete-examples-note.txt + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + examples-sqs-message-queues + examples-sqs-messages + examples-sqs-long-polling + examples-sqs-visibility-timeout + examples-sqs-dead-letter-queues + diff --git a/doc_source/examples/examples-note.txt b/doc_source/examples/examples-note.txt deleted file mode 100644 index 163a238..0000000 --- a/doc_source/examples/examples-note.txt +++ /dev/null @@ -1,3 +0,0 @@ -.. note:: These code snippets assume that you understand the material in :doc:`basics` and have - configured default AWS credentials using the information in :doc:`setup-credentials`. - diff --git a/doc_source/examples/s3.rst b/doc_source/examples/s3.rst deleted file mode 100644 index 3fba228..0000000 --- a/doc_source/examples/s3.rst +++ /dev/null @@ -1,18 +0,0 @@ -#### -|S3| -#### - -This section provides examples of programming |S3|_ using the |sdk-java|_. - -.. note:: Only the code that is necessary to demonstrate each technique is supplied here, but - :sdk-doc-examples:`complete example code is available on GitHub `, where you can download a - single source file or you can clone the repository locally to get all examples, build and run - them. - -.. toctree:: - :titlesonly: - :maxdepth: 1 - - s3/buckets - s3/objects - diff --git a/doc_source/examples/s3/buckets.rst b/doc_source/examples/s3/buckets.rst deleted file mode 100644 index 3c7097b..0000000 --- a/doc_source/examples/s3/buckets.rst +++ /dev/null @@ -1,78 +0,0 @@ -###################################### -Creating, Listing and Deleting Buckets -###################################### - -Every object (file) in |S3| must reside within a *bucket*, which represents a collection (container) -of objects. Each bucket is known by a *key* (name), which must be unique. For detailed information -about buckets and their configuration, see :s3-dg:`Working with Amazon S3 Buckets ` in -the the |s3-dg|. - -.. include:: ../examples-note.txt - -.. contents:: - :local: - :depth: 1 - -.. _create-bucket: - -Create a bucket -=============== - -Use the |s3client| client's :methodname:`createBucket` method. The new :java-api:`Bucket -` is returned. - -**Imports:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/CreateBucket.java - :lines: 15-17 - -**Code:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/CreateBucket.java - :lines: 43-50 - :dedent: 8 - -See the :sdk-examples-java:`complete example `. - -.. _list-buckets: - -List buckets -============ - -Use the |s3client| client's :methodname:`listBucket` method. If successful, a List of -:java-api:`Bucket ` objects will be returned. - -**Imports:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/ListBuckets.java - :lines: 16-18 - -**Code:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/ListBuckets.java - :lines: 31-37 - :dedent: 8 - -See the :sdk-examples-java:`complete example `. - -.. _delete-bucket: - -Delete a bucket -=============== - -Use the |s3client| client's :methodname:`deleteBucket` method. *The bucket must be empty, or an -error will result*. - -**Imports:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java - :lines: 15-17 - -**Code:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java - :lines: 45-52 - :dedent: 8 - -See the :sdk-examples-java:`complete example `. - diff --git a/doc_source/examples/s3/objects.rst b/doc_source/examples/s3/objects.rst deleted file mode 100644 index fa462bd..0000000 --- a/doc_source/examples/s3/objects.rst +++ /dev/null @@ -1,163 +0,0 @@ -##################### -Operations on Objects -##################### - -An |S3| object represents a *file*, or collection of data. Every object must reside within a -:doc:`bucket `. - -.. include:: ../examples-note.txt - -.. contents:: - :local: - :depth: 1 - - -.. _upload-object: - -Upload an object -================ - -Use the |s3client| client's :methodname:`putObject` method, supplying it with a bucket name, key -name, and file to upload. *The bucket must exist, or an error will result*. - -**Imports:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/PutObject.java - :lines: 15-17 - -**Code:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/PutObject.java - :lines: 47-54 - :dedent: 8 - -See the :sdk-examples-java:`complete example `. - -.. _list-objects: - -List objects -============ - -To get a list of objects within a bucket, use the |s3client| client's :methodname:`listObjects` -method, supplying it with the name of a bucket. - -The :methodname:`listObjects` method returns an :java-api:`ObjectListing -` object that provides information about the objects in the bucket. -To list the object names (keys), use the :methodname:`getObjectSummaries` method to get a List of -:java-api:`S3ObjectSummary ` objects, each of which represents a -single object in the bucket, then call its :methodname:`getKey` method to retrieve the object's -name. - -**Imports:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/ListObjects.java - :lines: 16-20 - -**Code:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/ListObjects.java - :lines: 46-52 - :dedent: 8 - -See the :sdk-examples-java:`complete example `. - -.. _download-object: - -Download an object -================== - -Use the |s3client| client's :methodname:`getObject` method, passing it the name of a bucket and -object to download. If successful, the method will return an :java-api:`S3Object -`. *The specified bucket and object key must exist, or an error will -result*. - -You can get the object's contents by calling :methodname:`getObjectContent` on the -:classname:`S3Object`. This returns an :java-api:`S3ObjectInputStream -` that behaves as a standard Java :classname:`InputStream` -object. - -The following example downloads an object from S3 and saves its contents to a file (using the same -name as the object's key): - -**Imports:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/GetObject.java - :lines: 15-23 - -**Code:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/GetObject.java - :lines: 51-75 - :dedent: 8 - -See the :sdk-examples-java:`complete example `. - -.. _copy-object: - -Copying, moving or renaming 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. - -**Imports:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/CopyObject.java - :lines: 15-17 - -**Code:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/CopyObject.java - :lines: 45-54 - :dedent: 8 - -See the :sdk-examples-java:`complete example `. - -You can use :methodname:`copyObject` with :ref:`deleteObject ` to **move** or -**rename** an object, by first copying the object to a new name (you can use the same bucket as both -the source and destination) and then deleting the object from its old location. - -.. _delete-object: - -Delete an object -================ - -Use the |s3client| client's :methodname:`deleteObject` method, passing it the name of a bucket and -object to delete. *The specified bucket and object key must exist, or an error will result*. - -**Imports:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteObject.java - :lines: 15-17 - -**Code:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteObject.java - :lines: 48-55 - :dedent: 8 - -See the :sdk-examples-java:`complete example `. - -.. _delete-objects: - -Deleting multiple objects at once -================================= - -Using the |s3client| client's :methodname:`deleteObjects` method, you can delete multiple objects -from the same bucket by passing their names to the :java-api:`DeleteObjectRequest -` :methodname:`withKeys` method. - -**Imports:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteObjects.java - :lines: 15-18 - -**Code:** - -.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteObjects.java - :lines: 53-62 - :dedent: 8 - -See the :sdk-examples-java:`complete example `. - diff --git a/doc_source/generating-sdk-metrics.rst b/doc_source/generating-sdk-metrics.rst new file mode 100755 index 0000000..3c25c58 --- /dev/null +++ b/doc_source/generating-sdk-metrics.rst @@ -0,0 +1,97 @@ +.. 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. + +.. |CSMlong| replace:: AWS SDK Metrics for Enterprise Support +.. |CSM| replace:: SDK Metrics + + +################################### +Enabling Metrics for the |sdk-java| +################################### + +The |sdk-java| can generate metrics for visualization and monitoring with |cw|_ that measure: + +* your application’s performance when accessing AWS +* the performance of your JVMs when used with AWS +* runtime environment details such as heap memory, number of threads, and opened file descriptors + +.. 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-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:: + + -Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties + +You need to specify the path to your credential file so that the SDK can upload the gathered +datapoints to |cw| for later analysis. + +.. note:: If you are accessing AWS from an |ec2| instance using the |ec2| instance metadata service, + you don’t need to specify a credential file. In this case, you need only specify:: + + -Dcom.amazonaws.sdk.enableDefaultMetrics + +All metrics captured by the SDK for Java are under the namespace **AWSSDK/Java**, and are uploaded +to the |cw| default region (*us-east-1*). To change the region, specify it by using the +``cloudwatchRegion`` attribute in the system property. For example, to set the |cw| region to +*us-west-2*, use:: + + -Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties,cloudwatchRegion=us-west-2 + +Once you enable the feature, every time there is a service request to AWS from the |sdk-java|, +metric data points will be generated, queued for statistical summary, and uploaded asynchronously to +|cw| about once every minute. Once metrics have been uploaded, you can visualize them using the +|console|_ and set alarms on potential problems such as memory leakage, file descriptor leakage, and +so on. + +Available Metric Types +====================== + +The default set of metrics is divided into three major categories: + +AWS Request Metrics + Covers areas such as the latency of the HTTP request/response, number of requests, exceptions, + and retries. + + .. image:: images/RequestMetric-131111.png + +AWS Service Metrics + Include AWS service-specific data, such as the throughput and byte count for S3 uploads and + downloads. + + .. image:: images/ServiceMetric-131111.png + +Machine Metrics + Cover the runtime environment, including heap memory, number of threads, and open file + descriptors. + + .. image:: images/MachineMetric-131111.png + + If you want to exclude Machine Metrics, add ``excludeMachineMetrics`` to the system property:: + + -Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties,excludeMachineMetrics + +More Information +================ + +* See the :aws-java-class:`amazonaws/metrics package summary ` for a full + list of the predefined core metric types. + +* Learn about working with |cw| using the |sdk-java| in :doc:`examples-cloudwatch`. + +* Learn more about performance tuning in + :blog:`Tuning the AWS SDK for Java to Improve Resiliency ` + blog post. diff --git a/doc_source/getting-started.rst b/doc_source/getting-started.rst old mode 100644 new mode 100755 index d1b67f9..738611c --- a/doc_source/getting-started.rst +++ b/doc_source/getting-started.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -23,4 +23,4 @@ This section provides information about how to install, set up, and use the |sdk setup-credentials setup-project-maven setup-project-gradle - + sdk-metrics diff --git a/doc_source/how-to-ec2.rst b/doc_source/how-to-ec2.rst index 48caa7c..01b4ee4 100644 --- a/doc_source/how-to-ec2.rst +++ b/doc_source/how-to-ec2.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -14,12 +14,6 @@ Tutorial: Starting an EC2 Instance This tutorial demonstrates how to use the AWS SDK for Java to start an EC2 instance. -Prerequisites -============= - -Before you begin, be sure that you have created an AWS account and that you have set up your AWS -credentials. For more information, see :doc:`getting-started`. - .. toctree:: :maxdepth: 1 @@ -27,3 +21,8 @@ credentials. For more information, see :doc:`getting-started`. create-key-pair run-instance +Prerequisites +============= + +Before you begin, be sure that you have created an AWS account and that you have set up your AWS +credentials. For more information, see :doc:`getting-started`. diff --git a/doc_source/images/MachineMetric-131111.png b/doc_source/images/MachineMetric-131111.png new file mode 100644 index 0000000..6fd6c3a Binary files /dev/null and b/doc_source/images/MachineMetric-131111.png differ diff --git a/doc_source/images/RequestMetric-131111.png b/doc_source/images/RequestMetric-131111.png new file mode 100644 index 0000000..aae9d5a Binary files /dev/null and b/doc_source/images/RequestMetric-131111.png differ diff --git a/doc_source/images/ServiceMetric-131111.png b/doc_source/images/ServiceMetric-131111.png new file mode 100644 index 0000000..8a8e598 Binary files /dev/null and b/doc_source/images/ServiceMetric-131111.png differ diff --git a/doc_source/images/create-s3-role-1.png b/doc_source/images/create-s3-role-1.png deleted file mode 100644 index 15e9b2e..0000000 Binary files a/doc_source/images/create-s3-role-1.png and /dev/null differ diff --git a/doc_source/images/create-s3-role-2.png b/doc_source/images/create-s3-role-2.png deleted file mode 100644 index d5fed07..0000000 Binary files a/doc_source/images/create-s3-role-2.png and /dev/null differ diff --git a/doc_source/images/create-s3-role-3.png b/doc_source/images/create-s3-role-3.png deleted file mode 100644 index 15ebcd1..0000000 Binary files a/doc_source/images/create-s3-role-3.png and /dev/null differ diff --git a/doc_source/images/create-s3-role-4.png b/doc_source/images/create-s3-role-4.png deleted file mode 100644 index b968103..0000000 Binary files a/doc_source/images/create-s3-role-4.png and /dev/null differ diff --git a/doc_source/images/create-s3-role-5.png b/doc_source/images/create-s3-role-5.png deleted file mode 100644 index 6fa2016..0000000 Binary files a/doc_source/images/create-s3-role-5.png and /dev/null differ diff --git a/doc_source/images/java-dg-console-ec2-finalize-ami.png b/doc_source/images/java-dg-console-ec2-finalize-ami.png deleted file mode 100644 index edf1c83..0000000 Binary files a/doc_source/images/java-dg-console-ec2-finalize-ami.png and /dev/null differ diff --git a/doc_source/images/java-dg-console-ec2-launch.png b/doc_source/images/java-dg-console-ec2-launch.png deleted file mode 100644 index 522ed60..0000000 Binary files a/doc_source/images/java-dg-console-ec2-launch.png and /dev/null differ diff --git a/doc_source/images/java-dg-console-ec2-select-ami.png b/doc_source/images/java-dg-console-ec2-select-ami.png deleted file mode 100644 index 6b7f713..0000000 Binary files a/doc_source/images/java-dg-console-ec2-select-ami.png and /dev/null differ diff --git a/doc_source/images/java-dg-console-ec2-select-role.png b/doc_source/images/java-dg-console-ec2-select-role.png deleted file mode 100644 index 028d1d0..0000000 Binary files a/doc_source/images/java-dg-console-ec2-select-role.png and /dev/null differ diff --git a/doc_source/images/java-dg-console-iam-role-create.png b/doc_source/images/java-dg-console-iam-role-create.png deleted file mode 100644 index d9a61f3..0000000 Binary files a/doc_source/images/java-dg-console-iam-role-create.png and /dev/null differ diff --git a/doc_source/images/java-dg-console-iam-role-finish.png b/doc_source/images/java-dg-console-iam-role-finish.png deleted file mode 100644 index a225d64..0000000 Binary files a/doc_source/images/java-dg-console-iam-role-finish.png and /dev/null differ diff --git a/doc_source/images/java-dg-console-iam-role-name.png b/doc_source/images/java-dg-console-iam-role-name.png deleted file mode 100644 index dd6e675..0000000 Binary files a/doc_source/images/java-dg-console-iam-role-name.png and /dev/null differ diff --git a/doc_source/images/java-dg-console-iam-role-policy-doc.png b/doc_source/images/java-dg-console-iam-role-policy-doc.png deleted file mode 100644 index 6a07c7d..0000000 Binary files a/doc_source/images/java-dg-console-iam-role-policy-doc.png and /dev/null differ diff --git a/doc_source/images/java-dg-console-iam-role-policy-template.png b/doc_source/images/java-dg-console-iam-role-policy-template.png deleted file mode 100644 index 6ad2310..0000000 Binary files a/doc_source/images/java-dg-console-iam-role-policy-template.png and /dev/null differ diff --git a/doc_source/images/java-dg-ec2-instance-pub-dns.png b/doc_source/images/java-dg-ec2-instance-pub-dns.png deleted file mode 100644 index 3f98a1e..0000000 Binary files a/doc_source/images/java-dg-ec2-instance-pub-dns.png and /dev/null differ diff --git a/doc_source/images/java-dg-eclipse-create-project.png b/doc_source/images/java-dg-eclipse-create-project.png deleted file mode 100644 index 68258f6..0000000 Binary files a/doc_source/images/java-dg-eclipse-create-project.png and /dev/null differ diff --git a/doc_source/images/java-dg-eclipse-credentials.png b/doc_source/images/java-dg-eclipse-credentials.png deleted file mode 100644 index dba95d6..0000000 Binary files a/doc_source/images/java-dg-eclipse-credentials.png and /dev/null differ diff --git a/doc_source/images/java-dg-eclipse-new-java-class.png b/doc_source/images/java-dg-eclipse-new-java-class.png deleted file mode 100644 index d07f506..0000000 Binary files a/doc_source/images/java-dg-eclipse-new-java-class.png and /dev/null differ diff --git a/doc_source/images/java-dg-eclipse-package-explorer.png b/doc_source/images/java-dg-eclipse-package-explorer.png deleted file mode 100644 index 794d121..0000000 Binary files a/doc_source/images/java-dg-eclipse-package-explorer.png and /dev/null differ diff --git a/doc_source/images/java-dg-eclipse-preferences.png b/doc_source/images/java-dg-eclipse-preferences.png deleted file mode 100644 index 0b0792a..0000000 Binary files a/doc_source/images/java-dg-eclipse-preferences.png and /dev/null differ diff --git a/doc_source/images/java-spot-recent-ami-1.png b/doc_source/images/java-spot-recent-ami-1.png index e385338..b0f8a3e 100644 Binary files a/doc_source/images/java-spot-recent-ami-1.png and b/doc_source/images/java-spot-recent-ami-1.png differ diff --git a/doc_source/images/java-spot-recent-ami-2.png b/doc_source/images/java-spot-recent-ami-2.png index fa080b1..d2af161 100644 Binary files a/doc_source/images/java-spot-recent-ami-2.png and b/doc_source/images/java-spot-recent-ami-2.png differ diff --git a/doc_source/images/sdk-java-commit-history.png b/doc_source/images/sdk-java-commit-history.png deleted file mode 100644 index 3f9aa2f..0000000 Binary files a/doc_source/images/sdk-java-commit-history.png and /dev/null differ diff --git a/doc_source/includes/complete-examples-note.txt b/doc_source/includes/complete-examples-note.txt new file mode 100644 index 0000000..fbc491a --- /dev/null +++ b/doc_source/includes/complete-examples-note.txt @@ -0,0 +1,14 @@ +.. 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. + +.. note:: The examples include only the code needed to demonstrate each technique. The + :sdk-doc-examples:`complete example code is available on GitHub `. From there, you can download a + single source file or clone the repository locally to get all the examples to build and run. + diff --git a/doc_source/prog-services-ddb.rst b/doc_source/includes/examples-note.txt similarity index 68% rename from doc_source/prog-services-ddb.rst rename to doc_source/includes/examples-note.txt index fea6d20..3f12239 100644 --- a/doc_source/prog-services-ddb.rst +++ b/doc_source/includes/examples-note.txt @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,14 +8,6 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -##### -|DDB| -##### +.. note:: These code examples assume that you understand the material in :doc:`basics` and have + configured default AWS credentials using the information in :doc:`setup-credentials`. -This section provides examples of programming |DDB|_ with the |sdk-java|. - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - java-dg-tomcat-session-manager diff --git a/doc_source/includes/transfermanager-complete-get-status-note.txt b/doc_source/includes/transfermanager-complete-get-status-note.txt new file mode 100644 index 0000000..45986d5 --- /dev/null +++ b/doc_source/includes/transfermanager-complete-get-status-note.txt @@ -0,0 +1,18 @@ +.. 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. + +See :ref:`transfermanager-wait-for-completion` for information about using +:methodname:`waitForCompletion` to successfully complete a transfer before calling |xfermgr|'s +:methodname:`shutdownNow` method. While waiting for the transfer to complete, you can poll or listen +for updates about its status and progress. See :ref:`transfermanager-get-status-and-progress` for +more information. + + + diff --git a/doc_source/includes/transfermanager-multifileupload-notes.txt b/doc_source/includes/transfermanager-multifileupload-notes.txt new file mode 100644 index 0000000..0816464 --- /dev/null +++ b/doc_source/includes/transfermanager-multifileupload-notes.txt @@ -0,0 +1,19 @@ +.. 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. + +The :aws-java-class:`MultipleFileUpload ` object returned +by :methodname:`uploadFileList` can be used to query the transfer state or progress. See +:ref:`transfermanager-get-progress-polling` and :ref:`transfermanager-progress-listener` for more +information. + +You can also use :classname:`MultipleFileUpload`'s :methodname:`getSubTransfers` method to get the +individual :classname:`Upload` objects for each file being transferred. For more information, see +:ref:`transfermanager-get-subtransfer-progress`. + diff --git a/doc_source/index.rst b/doc_source/index.rst index 4bcfc3c..59814c8 100644 --- a/doc_source/index.rst +++ b/doc_source/index.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,6 +12,10 @@ |sdk-java| ########## +.. meta:: + :description: Describes the various features of the SDK and how to use them. + :keywords: java, sdk, aws + .. toctree:: :maxdepth: 1 :titlesonly: @@ -19,6 +23,9 @@ welcome getting-started basics - prog-services - advanced + Code Examples + Security document-history + +.. include:: about-aws.txt + diff --git a/doc_source/infrastructure-security.rst b/doc_source/infrastructure-security.rst new file mode 100644 index 0000000..10e994e --- /dev/null +++ b/doc_source/infrastructure-security.rst @@ -0,0 +1,12 @@ +Infrastructure Security for this AWS Product or Service +======================================================= + +This AWS product or service follows the `shared responsibility +model `__ +through the specific Amazon Web Services (AWS) services it supports. For +AWS service security information, see the `AWS service security +documentation +page `__ +and `AWS services that are in scope of AWS compliance efforts by +compliance +program `__. diff --git a/doc_source/java-dg-access-control.rst b/doc_source/java-dg-access-control.rst index 74255a7..f07454c 100644 --- a/doc_source/java-dg-access-control.rst +++ b/doc_source/java-dg-access-control.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,40 +12,34 @@ Access Control Policies ####################### -AWS access control policies allow you to specify fine-grained access controls on your AWS resources. -You can allow or deny access to your AWS resources based on: +.. meta:: + :description: How to specify access control policies using the AWS SDK for Java, with examples + for Amazon S3, Amazon SQS, and Amazon SNS. -* what :emphasis:`resource` is being accessed. +AWS *access control policies* enable you to specify fine-grained access controls on your AWS +resources. An access control policy consists of a collection of *statements*, which take the form: -* who is accessing the resource (i.e., the principal). + *Account A* has permission to perform *action B* on *resource C* where *condition D* applies. -* what action is being taken on the resource. +Where: -* a variety of other conditions including date restrictions, IP address restrictions, etc. +* *A* is the *principal* |ndash| The AWS account that is making a request to access or modify one + of your AWS resources. -Access control policies are a collection of statements. Each statement takes the form: "A has -permission to do B to C where D applies". +* *B* is the *action* |ndash| The way in which your AWS resource is being accessed or modified, + such as sending a message to an |SQS| queue, or storing an object in an |S3| bucket. -:emphasis:`A is the principal` - The AWS account that is making a request to access or modify one of your AWS resources. +* *C* is the *resource* |ndash| The AWS entity that the principal wants to access, such as an + |SQS| queue, or an object stored in |S3|. -:emphasis:`B is the action` - The way in which your AWS resource is being accessed or modified, such as sending a message to - an Amazon SQS queue, or storing an object in an Amazon S3 bucket. +* *D* is a *set of conditions* |ndash| The optional constraints that specify when to allow or deny + access for the principal to access your resource. Many expressive conditions are available, some + specific to each service. For example, you can use date conditions to allow access to your + resources only after or before a specific time. -:emphasis:`C is the resource` - Your AWS entity that the principal wants to access, such as an Amazon SQS queue, or an object - stored in Amazon S3. -:emphasis:`D is the set of conditions` - The optional constraints that specify when to allow or deny access for the principal to access - your resource. Many expressive conditions are available, some specific to each service. For - example, you can use date conditions to allow access to your resources only after or before a - specific time. - - -Amazon S3 Example -================= +|S3| Example +============ The following example demonstrates a policy that allows anyone access to read all the objects in a bucket, but restricts access to uploading objects to that bucket to two specific AWS accounts (in @@ -69,18 +63,13 @@ addition to the bucket owner's account). s3.setBucketPolicy(myBucketName, policy.toJson()); -Amazon SQS Example -================== +|SQS| Example +============= -One common use of policies is to authorize an Amazon SQS queue to receive messages from an Amazon -SNS topic. +One common use of policies is to authorize an |SQS| queue to receive messages from an |SNS| topic. .. code-block:: java - /* - * This policy allows an SNS topic to send messages to an SQS queue. - * You can find your SNS topic's ARN through the SNS getTopicAttributes operation. - */ Policy policy = new Policy().withStatements( new Statement(Effect.Allow) .withPrincipals(Principal.AllUsers) @@ -94,21 +83,15 @@ SNS topic. sqs.setQueueAttributes(new SetQueueAttributesRequest(myQueueUrl, queueAttributes)); -Amazon SNS Example -================== +|SNS| Example +============= -Some services offer additional conditions that can be used in policies. Amazon SNS provides -conditions for allowing or denying subscriptions to SNS topics based on the protocol (e.g., email, -HTTP, HTTPS, SQS) and endpoint (e.g., email address, URL, SQS ARN) of the request to subscribe to a -topic. +Some services offer additional conditions that can be used in policies. |SNS| provides conditions +for allowing or denying subscriptions to SNS topics based on the protocol (e.g., email, HTTP, HTTPS, +|SQS|) and endpoint (e.g., email address, URL, |SQS| ARN) of the request to subscribe to a topic. .. code-block:: java - /* - * This SNS condition allows you to restrict subscriptions to an Amazon SNS topic - * based on the requested endpoint (email address, SQS queue ARN, etc.) used when - * someone tries to subscribe to your SNS topic. - */ Condition endpointCondition = SNSConditionFactory.newEndpointCondition("*@mycompany.com"); diff --git a/doc_source/java-dg-exceptions.rst b/doc_source/java-dg-exceptions.rst index dbcecf2..1e27af6 100644 --- a/doc_source/java-dg-exceptions.rst +++ b/doc_source/java-dg-exceptions.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,14 +12,18 @@ Exception Handling ################## -Understanding how and when the AWS SDK for Java throws exceptions is important in order to build +.. meta:: + :description: How to handle exceptions thrown by the AWS SDK for Java. + :keywords: + +Understanding how and when the |sdk-java| throws exceptions is important to building high-quality applications using the SDK. The following sections describe the different cases of exceptions that are thrown by the SDK and how to handle them appropriately. Why Unchecked Exceptions? ========================= -The AWS Java SDK uses runtime (or unchecked) exceptions instead of checked exceptions for a few +The |sdk-java| uses runtime (or unchecked) exceptions instead of checked exceptions for these reasons: * To allow developers fine-grained control over the errors they want to handle without forcing them @@ -30,7 +34,7 @@ reasons: In general, checked exceptions work well on small scales, but can become troublesome as applications grow and become more complex. -For more information about the use of checked and unchecked exceptions, see the following articles: +For more information about the use of checked and unchecked exceptions, see: * `Unchecked Exceptions—The Controversy `_ @@ -38,21 +42,22 @@ For more information about the use of checked and unchecked exceptions, see the * `The Trouble with Checked Exceptions `_ * `Java's checked exceptions were a mistake (and here's what I would like to do about it) - `_ + `_ AmazonServiceException (and Subclasses) ======================================== -:java-api:`AmazonServiceException` is the most common exception that you'll experience when using +:aws-java-class:`AmazonServiceException` is the most common exception that you'll experience when using the |sdk-java|. This exception represents an error response from an AWS service. For example, if you try to terminate an |EC2| instance that doesn't exist, EC2 will return an error response and all the -details of that error response will be included in the thrown :classname:`AmazonServiceException`. -For some cases, a subclass of :classname:`AmazonServiceException` will be thrown to allow developers -fine grained control over handling error cases through catch blocks. +details of that error response will be included in the :classname:`AmazonServiceException` that's thrown. +For some cases, a subclass of :classname:`AmazonServiceException` is thrown to allow developers +fine-grained control over handling error cases through catch blocks. When you encounter an :classname:`AmazonServiceException`, you know that your request was successfully -sent to the AWS service, but could not be successfully processed either because of errors in the +sent to the AWS service but couldn't be successfully processed. This can be because of errors in +the request's parameters or because of issues on the service side. :classname:`AmazonServiceException` provides you with information such as: @@ -66,18 +71,18 @@ request's parameters or because of issues on the service side. * AWS request ID for the failed request :classname:`AmazonServiceException` also includes information about whether the failed request was -the caller's fault (i.e., a request with illegal values) or the AWS service's fault (i.e., an +the caller's fault (a request with illegal values) or the AWS service's fault (an internal service error). AmazonClientException ===================== -:java-api:`AmazonClientException` indicates that a problem occurred inside the Java client code, +:aws-java-class:`AmazonClientException` indicates that a problem occurred inside the Java client code, either while trying to send a request to AWS or while trying to parse a response from AWS. -:classname:`AmazonClientException` exceptions are generally more severe than -:classname:`AmazonServiceException` exceptions and indicate a major problem that is preventing the -client from being able to make service calls to AWS services. For example, the AWS Java SDK will -throw an :classname:`AmazonClientException` if no network connection is available when you try to +An :classname:`AmazonClientException` is generally more severe than an +:classname:`AmazonServiceException`, and indicates a major problem that is preventing the +client from making service calls to AWS services. For example, the |sdk-java| +throws an :classname:`AmazonClientException` if no network connection is available when you try to call an operation on one of the clients. diff --git a/doc_source/java-dg-jvm-ttl.rst b/doc_source/java-dg-jvm-ttl.rst index ce1d72b..273436a 100644 --- a/doc_source/java-dg-jvm-ttl.rst +++ b/doc_source/java-dg-jvm-ttl.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,27 +12,30 @@ Setting the JVM TTL for DNS Name Lookups ######################################## -The Java virtual machine (JVM) caches DNS name lookups; when the JVM resolves a hostname to an IP -address, it will cache the IP address for a specified period of time, known as the *time-to-live* -(TTL). +.. meta:: + :description: How to set Java virtual machine (JVM) for DNS name lookups using the AWS SDK for + Java. + +The Java virtual machine (JVM) caches DNS name lookups. When the JVM resolves a hostname to an IP +address, it caches the IP address for a specified period of time, known as the *time-to-live* (TTL). Because AWS resources use DNS name entries that occasionally change, we recommend that you configure your JVM with a TTL value of no more than 60 seconds. This ensures that when a resource's IP address changes, your application will be able to receive and use the resource's new IP address by -re-querying the DNS. +requerying the DNS. On some Java configurations, the JVM default TTL is set so that it will *never* refresh DNS entries until the JVM is restarted. Thus, if the IP address for an AWS resource changes while your application is still running, it won't be able to use that resource until you *manually restart* the -JVM and the cached IP information is refreshed. In this case, it is vitally important to set the -JVM's TTL so that it will periodically refresh its cached IP information. +JVM and the cached IP information is refreshed. In this case, it's crucial to set the JVM's TTL so +that it will periodically refresh its cached IP information. .. note:: The default TTL can vary according to the version of your JVM and whether a `security manager `_ is - installed. Many JVMs provide a default TTL less than 60s. If you are using such a JVM and not - using a security manager, then you can ignore the remainder of this topic. + installed. Many JVMs provide a default TTL less than 60 seconds. If you're using such a JVM and + not using a security manager, you can ignore the remainder of this topic. -How to set the JVM TTL +How to Set the JVM TTL ====================== To modify the JVM's TTL, set the `networkaddress.cache.ttl diff --git a/doc_source/java-dg-logging.rst b/doc_source/java-dg-logging.rst index 9202d11..67784b7 100644 --- a/doc_source/java-dg-logging.rst +++ b/doc_source/java-dg-logging.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,34 +12,44 @@ Logging |sdk-java| Calls ######################## +.. meta:: + :description: How to use Apache Log4j with the AWS SDK for Java. + :keywords: + The |sdk-java| is instrumented with `Apache Commons Logging `_, which is an abstraction layer that -enables the use of any one of a number of logging systems at runtime. Supported logging systems -include the Java Logging Framework and Apache Log4j, among others. This topic explains how to use -Log4j. You can learn more about Log4j on the `Log4j `_ page at -the `Apache website `_. You can use the SDK's logging functionality without +enables the use of any one of several logging systems at runtime. + +Supported logging systems include the Java Logging Framework and Apache Log4j, among others. This +topic shows you how to use Log4j. You can use the SDK's logging functionality without making any changes to your application code. +To learn more about `Log4j `_, +see the `Apache website `_. + .. note:: This topic focuses on Log4j 1.x. Log4j2 doesn't directly support Apache Commons Logging, but - provides an adapter that directs logging calls automatically to Log4j2 using the Apache Commons - Logging interface. For more information, see: `Commons Logging Bridge - `_ in the Log4j2 documentation. + provides an adapter that directs logging calls automatically to Log4j2 using the Apache Commons + Logging interface. For more information, see `Commons Logging Bridge + `_ in the Log4j2 documentation. + +Download the Log4J JAR +====================== -In order to use Log4j with the SDK, you need to download the Log4j jar from the Apache website. The -jar is not included in the SDK. Copy the jar file to a location that is on your classpath. +To use Log4j with the SDK, you need to download the Log4j JAR from the Apache website. The SDK doesn't +include the JAR. Copy the JAR file to a location that is on your classpath. Log4j uses a configuration file, log4j.properties. Example configuration files are shown below. Copy -this configuration file to a directory on your classpath. The Log4j jar and the log4j.properties -file do not have to be in the same directory. +this configuration file to a directory on your classpath. The Log4j JAR and the log4j.properties +file don't have to be in the same directory. The log4j.properties configuration file specifies properties such as `logging level `_, where logging output is -sent (such as `to a file or to the console +sent (for example, `to a file or to the console `_), and the `format of the output `_. The logging level is the granularity of output that the logger generates. Log4j supports the concept of multiple logging :emphasis:`hierarchies`. The logging level is set independently for each hierarchy. The following -two logging hierarchies are available in the SDK. +two logging hierarchies are available in the |sdk-java|: * log4j.logger.com.amazonaws @@ -50,10 +60,11 @@ two logging hierarchies are available in the SDK. Setting the Classpath ===================== -Both the Log4j jar and the log4j.properties file must be located on your classpath. If you are using -`Apache Ant `_, set the classpath in the :code:`path` element in your -Ant file. Here is an example path element from the Ant file for the Amazon S3 example included with -the SDK: +Both the Log4j JAR and the log4j.properties file must be located on your classpath. If +you're using `Apache Ant `_, set the classpath in the :code:`path` element in your +Ant file. The following example shows a path element from the Ant file for the +|S3| `example `_ included +with the SDK. .. code-block:: xml @@ -63,7 +74,7 @@ the SDK: -If you are using the Eclipse IDE, you can set the classpath by opening the menu and navigating to +If you're using the Eclipse IDE, you can set the classpath by opening the menu and navigating to :guilabel:`Project` | :guilabel:`Properties` | :guilabel:`Java Build Path`. @@ -72,13 +83,13 @@ If you are using the Eclipse IDE, you can set the classpath by opening the menu Service-Specific Errors and Warnings ==================================== -We recommend that you always leave the "com.amazonaws" logger hierarchy set to "WARN" in order to -catch any important messages from the client libraries. For example, if the Amazon S3 client detects +We recommend that you always leave the "com.amazonaws" logger hierarchy set to "WARN" to +catch any important messages from the client libraries. For example, if the |S3| client detects that your application hasn't properly closed an :code:`InputStream` and could be leaking resources, -it will report it through a warning message to the logs. This will also ensure that messages are -logged if the client has any problems handling requests or responses. +the S3 client reports it through a warning message to the logs. This also ensures that messages +are logged if the client has any problems handling requests or responses. -The following log4j.properties file sets the :code:`rootLogger` to WARN, which will cause warning +The following log4j.properties file sets the :code:`rootLogger` to WARN, which causes warning and error messages from all loggers in the "com.amazonaws" hierarchy to be included. Alternatively, you can explicitly set the com.amazonaws logger to WARN. @@ -115,7 +126,7 @@ request IDs. # a summary of requests/responses with AWS request IDs log4j.logger.com.amazonaws.request=DEBUG -Here is an example of the log output: +Here is an example of the log output. .. code-block:: none @@ -145,15 +156,16 @@ Here is an example of the log output: Verbose Wire Logging ==================== -In some cases, it may be useful to see the exact requests and responses being sent and received by -the AWS SDK for Java. This logging should not be enabled in production systems since writing out -large requests (e.g., a file being uploaded to Amazon S3) or responses can significantly slow down +In some cases, it can be useful to see the exact requests and responses that the |sdk-java| +sends and receives. You shouldn't enable this logging in production systems because writing +out +large requests (e.g., a file being uploaded to |S3|) or responses can significantly slow down an application. If you really need access to this information, you can temporarily enable it through the Apache HttpClient 4 logger. Enabling the DEBUG level on the :code:`apache.http.wire` logger enables logging for all request and response data. The following log4j.properties file turns on full wire logging in Apache HttpClient 4 and should -only be turned on temporarily since it can have a significant performance impact on your +only be turned on temporarily because it can have a significant performance impact on your application. .. code-block:: properties @@ -168,3 +180,36 @@ application. log4j.logger.org.apache.http.wire=DEBUG +.. _sdk-latency-logging: + +Latency Metrics Logging +======================= + +If you are troubleshooting and want to see metrics such as which process is taking the most time +or whether server or client side has the greater latency, the latency logger can be helpful. +Set the :code:`com.amazonaws.latency` logger to DEBUG to enable this logger. + +.. note:: + + This logger is only available if SDK metrics is enabled. + To learn more about the SDK metrics package, see :doc:`generating-sdk-metrics`. + +.. code-block:: properties + + log4j.rootLogger=WARN, A1 + log4j.appender.A1=org.apache.log4j.ConsoleAppender + log4j.appender.A1.layout=org.apache.log4j.PatternLayout + log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n + log4j.logger.com.amazonaws.latency=DEBUG + +Here is an example of the log output. + +.. code-block:: none + + com.amazonaws.latency - ServiceName=[Amazon S3], StatusCode=[200], + ServiceEndpoint=[https://list-objects-integ-test-test.s3.amazonaws.com], + RequestType=[ListObjectsV2Request], AWSRequestID=[REQUESTID], HttpClientPoolPendingCount=0, + RetryCapacityConsumed=0, HttpClientPoolAvailableCount=0, RequestCount=1, + HttpClientPoolLeasedCount=0, ResponseProcessingTime=[52.154], ClientExecuteTime=[487.041], + HttpClientSendRequestTime=[192.931], HttpRequestTime=[431.652], RequestSigningTime=[0.357], + CredentialsRequestTime=[0.011, 0.001], HttpClientReceiveResponseTime=[146.272] diff --git a/doc_source/java-dg-region-selection.rst b/doc_source/java-dg-region-selection.rst index 861533e..e6a1ae0 100644 --- a/doc_source/java-dg-region-selection.rst +++ b/doc_source/java-dg-region-selection.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 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,30 +12,32 @@ AWS Region Selection #################### -Regions enable you to access AWS services that reside physically in a specific geographic area. This +.. meta:: + :description: How to check service availability and choose an AWS Region and specific endpoints. + :keywords: + +Regions enable you to access AWS services that physically reside in a specific geographic area. This can be useful both for redundancy and to keep your data and applications running close to where you and your users will access them. -.. contents:: - :depth: 1 - :local: .. _region-selection-query-service: Checking for Service Availability in an AWS Region ================================================== -To see if a particular AWS service is available in a region, use the isServiceSupported method on -the region that you'd like to use. For example: +To see if a particular AWS service is available in a region, use the +:methodname:`isServiceSupported` method on the region that you'd like to use. -.. code-block:: java +:: Region.getRegion(Regions.US_WEST_2) - .isServiceSupported(AmazonDynamoDB.ENDPOINT_PREFIX); + .isServiceSupported(AmazonDynamoDB.ENDPOINT_PREFIX); -See the :java-api:`Regions ` class documentation to see which regions can be -specified, and use the endpoint prefix of the service to query. Each service's endpoint prefix is defined in the service -interface. For example, Amazon DynamoDB's endpoint prefix is defined in :java-api:`AmazonDynamoDB `. +See the :aws-java-class:`Regions ` class documentation for the regions you can specify, +and use the endpoint prefix of the service to query. Each service's endpoint prefix is +defined in the service interface. For example, the |DDB| endpoint prefix is defined in +:aws-java-class:`AmazonDynamoDB `. .. _region-selection-choose-region: @@ -44,70 +46,119 @@ Choosing a Region ================= Beginning with version 1.4 of the |sdk-java|, you can specify a region name and the SDK will -automatically choose an appropriate endpoint for you. If you want to choose the endpoint yourself, +automatically choose an appropriate endpoint for you. To choose the endpoint yourself, see :ref:`region-selection-choose-endpoint`. -To explicitly set a region, it is recommended to use the :java-api:`Regions ` enum -which is a enumeration of all publicly available regions. To create a client with a region from -the enum use the following code. +To explicitly set a region, we recommend that you use the :aws-java-class:`Regions ` +enum. This is an enumeration of all publicly available regions. To create a client with a region +from the enum, use the following code. -.. code-block:: java +:: AmazonEC2 ec2 = AmazonEC2ClientBuilder.standard() .withRegion(Regions.US_WEST_2) .build(); -If the region you are attempting to use is not in the Regions enum, you can also set the region -with just the name of the region. For example: +If the region you are attempting to use isn't in the :classname:`Regions` enum, you can set the +region using a *string* that represents the name of the region. -.. code-block:: java +:: AmazonEC2 ec2 = AmazonEC2ClientBuilder.standard() .withRegion("us-west-2") .build(); -Note that once a client has been built with the builder it is immutable and the region cannot be -changed. If you are working with multiple AWS Regions for the same service then you should create -multiple clients. +.. note:: After you build a client with the builder, it's *immutable* and the region *cannot + be changed*. If you are working with multiple AWS Regions for the same service, you should + create multiple clients |mdash| one per region. + .. _region-selection-choose-endpoint: Choosing a Specific Endpoint ============================ -Each AWS client can be configured to use a specific endpoint by calling the setEndpoint method. +Each AWS client can be configured to use a *specific endpoint* within a region by calling the +:methodname:`withEndpointConfiguration` method when creating the client. + +For example, to configure the |S3| client to use the |euwest1-name|, use the following code. -For example, to configure the |EC2| client to use the |euwest1-name|, use the following code: +:: -.. code-block:: java + AmazonS3 s3 = AmazonS3ClientBuilder.standard() + .withEndpointConfiguration(new EndpointConfiguration( + "https://s3.eu-west-1.amazonaws.com/", + "eu-west-1")) + .withCredentials(CREDENTIALS_PROVIDER) + .build(); - AmazonEC2 ec2 = new AmazonEC2(myCredentials); - ec2.setEndpoint("https://ec2.eu-west-1.amazonaws.com/"); -Go to |regions-and-endpoints|_ for the current list of regions and their corresponding endpoints for +See |regions-and-endpoints|_ for the current list of regions and their corresponding endpoints for all AWS services. +Automatically Determine the AWS Region from the Environment +============================================================= + +.. important:: This section applies only when using a :doc:`client builder ` to + access AWS services. AWS clients created by using the client constructor will not automatically + determine region from the environment and will, instead, use the *default* SDK region + (|region-sdk-default|). + +When running on |EC2| or |LAM|, you might want to configure clients to use the same region +that your code is running on. This decouples your code from the environment it's running in and +makes it easier to deploy your application to multiple regions for lower latency or redundancy. + +*You must use client builders to have the SDK automatically detect the region your code is running +in.* + +To use the default credential/region provider chain to determine the region from the environment, +use the client builder's :methodname:`defaultClient` method. + +:: + + AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient(); + +This is the same as using :methodname:`standard` followed by :methodname:`build`. + +:: + + AmazonEC2 ec2 = AmazonEC2ClientBuilder.standard() + .build(); + +If you don't explicitly set a region using the :methodname:`withRegion` methods, the SDK +consults the default region provider chain to try and determine the region to use. + + +Default Region Provider Chain +----------------------------- + +**The following is the region lookup process:** + +#. Any explicit region set by using :methodname:`withRegion` or :methodname:`setRegion` on the builder + itself takes precedence over anything else. + +#. The :envvar:`AWS_REGION` environment variable is checked. If it's set, that region is + used to configure the client. + + .. note:: This environment variable is set by the |LAM| container. + +#. The SDK checks the AWS shared configuration file (usually located at :file:`~/.aws/config`). If + the :paramname:`region` property is present, the SDK uses it. + + * The :envvar:`AWS_CONFIG_FILE` environment variable can be used to customize the location of the + shared config file. -Determining Region from Environment -=================================== + * The :envvar:`AWS_PROFILE` environment variable or the :paramname:`aws.profile` system property + can be used to customize the profile that is loaded by the SDK. -When running on Amazon EC2 or AWS Lambda, it's often desirable to configure clients with the same -region that your code is running on. This decouples your code from the environment it's running in -and makes it easier to deploy your application to multiple regions for lower latency or redundancy. +#. The SDK attempts to use the |EC2| instance metadata service to determine the region of the + currently running |EC2| instance. -To have the SDK automatically detect the region your code is running in, you can use the client builders. -If you don't explicitly set a region via the withRegion methods, then the SDK will consult a default -region provider chain to try and determine the region to use. +#. If the SDK still hasn't found a region by this point, client creation fails with an + exception. -The region lookup process is as follows - #. First, the AWS_REGION environment variable is checked. If it's set that region will be used to configure the client. If not we move on. - * Note that this environment variable is set by the AWS Lambda container - #. Next the SDK will look at the AWS shared config file (usually located at ~/.aws/config). If the `region` property the SDK will use it. - * The AWS_CONFIG_FILE environment variable can be used to customize the location of the shared config file. - * The AWS_PROFILE environment variable or the aws.profile system property can be used to customize which profile is loaded by the SDK. - #. Finally, if the SDK still hasn't found a region to use it will attempt to call the EC2 instance metadata service to determine the region of the current running EC2 instance. - * If the application is not running on EC2 then the region lookup will fail and an exception will be thrown. +When developing AWS applications, a common approach is to use the *shared configuration file* +(described in :ref:`credentials-default`) to set the region for local development, and rely on the default region +provider chain to determine the region when running on AWS infrastructure. This greatly simplifies +client creation and keeps your application portable. -A common approach to developing AWS applications is to use the shared config file to set the region for local -development and rely on the default region provider chain to determine the region when running on AWS -infrastructure. This greatly simplifies client creation and keeps your application portable. diff --git a/doc_source/java-dg-roles.rst b/doc_source/java-dg-roles.rst index 0421551..82f1fec 100644 --- a/doc_source/java-dg-roles.rst +++ b/doc_source/java-dg-roles.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,21 +8,18 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -############################################################## -Using IAM Roles to Grant Access to AWS Resources on Amazon EC2 -############################################################## +########################################################### +Using |IAM| Roles to Grant Access to AWS Resources on |EC2| +########################################################### All requests to Amazon Web Services (AWS) must be cryptographically signed using credentials issued by AWS. You can use :emphasis:`IAM roles` to conveniently grant secure access to AWS resources from -your EC2 instances. +your |EC2| instances. -This topic provides information about how to use IAM roles with Java SDK applications running on -EC2. For more information about IAM instances, see :ec2-ug:`IAM Roles for Amazon EC2 +This topic provides information about how to use |IAM| roles with Java SDK applications running on +|EC2|. For more information about |IAM| instances, see :ec2-ug:`IAM Roles for Amazon EC2 ` in the |EC2-ug|. -.. contents:: - :local: - :depth: 1 .. _default-provider-chain: @@ -32,32 +29,38 @@ 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). +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 - associated with the IAM role for the EC2 instance. +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. -The final 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 InstanceProfileCredentialsProvider instance directly to the client -constructor to get instance profile credentials without proceeding through the entire default -provider chain. For example: +5. In the :emphasis:`instance profile credentials`, which exist within the instance metadata + associated with the IAM role for the EC2 instance. + +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 +instance profile credentials without proceeding through the entire default provider chain. + +For example: .. code-block:: java - AmazonS3 s3Client = AmazonS3ClientBuilder.standard() - .withCredentials(new InstanceProfileCredentialsProvider()) - .build(); + AmazonS3 s3 = AmazonS3ClientBuilder.standard() + .withCredentials(new InstanceProfileCredentialsProvider(false)) + .build(); -When using this approach, the SDK will retrieve temporary AWS credentials that have the same -permissions as those associated with the IAM role associated with the EC2 instance in its instance -profile. Although these credentials are temporary and would eventually expire, -InstanceProfileCredentialsProvider will periodically refresh them for you so that the obtained -credentials continue to allow access to AWS. +When using this approach, the SDK retrieves temporary AWS credentials that have the same +permissions as those associated with the |IAM| role associated with the |EC2| instance in its +instance profile. Although these credentials are temporary and would eventually expire, +:classname:`InstanceProfileCredentialsProvider` periodically refreshes them for you so that the +obtained credentials continue to allow access to AWS. .. important:: The automatic credentials refresh happens :emphasis:`only` when you use the default client constructor, which creates its own :code:`InstanceProfileCredentialsProvider` as part of @@ -66,7 +69,7 @@ credentials continue to allow access to AWS. profile credentials, you are responsible for checking for and refreshing expired credentials. If the client constructor can't find credentials using the credentials provider chain, it will throw -an AmazonClientException. +an :aws-java-class:`AmazonClientException `. .. _roles-walkthrough: @@ -77,9 +80,6 @@ Walkthrough: Using IAM roles for EC2 instances The following walkthrough shows you how to retrieve an object from |S3| using an |IAM| role to manage access. -.. contents:: - :depth: 1 - :local: .. _java-dg-create-the-role: @@ -88,22 +88,22 @@ Create an |IAM| Role Create an IAM role that grants read-only access to |S3|. -**To create the IAM role** +.. topic:: To create the IAM role -1. Open the IAM console. + #. Open the :console:`IAM console `. -2. In the navigation pane, click :guilabel:`Roles`, and then click :guilabel:`Create New Role`. + #. In the navigation pane, select :guilabel:`Roles`, then :guilabel:`Create New Role`. -3. Enter a name for the role, and then click :guilabel:`Next Step`. Remember this name, as you'll - need it when you launch your EC2 instance. + #. Enter a name for the role, then select :guilabel:`Next Step`. Remember this name, since + you'll need it when you launch your |EC2| instance. -4. On the :guilabel:`Select Role Type` page, under :guilabel:`AWS Service Roles`, select - :guilabel:`Amazon EC2`. + #. On the :guilabel:`Select Role Type` page, under :guilabel:`AWS Service Roles`, select + :guilabel:`Amazon EC2`. -5. On the :guilabel:`Set Permissions` page, under :guilabel:`Select Policy Template`, select - :guilabel:`Amazon S3 Read Only Access`. Click :guilabel:`Next Step`. + #. On the :guilabel:`Set Permissions` page, under :guilabel:`Select Policy Template`, select + :guilabel:`Amazon S3 Read Only Access`, then :guilabel:`Next Step`. -6. On the :guilabel:`Review` page, click :guilabel:`Create Role`. + #. On the :guilabel:`Review` page, select :guilabel:`Create Role`. .. _java-dg-launch-ec2-instance-with-instance-profile: @@ -111,16 +111,19 @@ Create an IAM role that grants read-only access to |S3|. Launch an EC2 Instance and Specify Your IAM Role ------------------------------------------------ -You can launch an EC2 instance with an IAM role using the |EC2| console or the |sdk-java|. +You can launch an |EC2| instance with an |IAM| role using the |EC2| console or the |sdk-java|. -* To launch an EC2 instance using the console, follow the directions in :ec2-ug:`Launch an EC2 - Instance ` in the |EC2-ug|. When you reach the :guilabel:`Review - Instance Launch` page, click :guilabel:`Edit instance details`. In :guilabel:`IAM role`, specify - the IAM role that you created previously. Complete the procedure as directed. Notice that you'll - need to create or use an existing security group and key pair in order to connect to the - instance. +* To launch an |EC2| instance using the console, follow the directions in :ec2-ug:`Getting Started + with Amazon EC2 Linux Instances ` in the |EC2-ug|. -* To launch an EC2 instance with an IAM role using the |sdk-java|, see :doc:`run-instance`. + When you reach the :guilabel:`Review Instance Launch` page, select :guilabel:`Edit instance + details`. In :guilabel:`IAM role`, choose the |IAM| role that you created previously. Complete the + procedure as directed. + + .. note:: You'll need to create or use an existing security group and key pair to connect to the + instance. + +* To launch an |EC2| instance with an |IAM| role using the |sdk-java|, see :doc:`run-instance`. .. _java-dg-remove-the-credentials: @@ -136,9 +139,10 @@ Next, copy the |sdk-java| libraries into your newly-created directory. If you do .. code-block:: sh - cp -r ~/Downloads/aws-java-sdk-{1.7.5}/lib . cp -r ~/Downloads/aws-java-sdk-{1.7.5}/third-party . + cp -r ~/Downloads/aws-java-sdk-{1.7.5}/lib . + cp -r ~/Downloads/aws-java-sdk-{1.7.5}/third-party . -Open a new file, call it :file:`GetS3Ojbect.java`, and add the following code: +Open a new file, call it :file:`GetS3Object.java`, and add the following code: .. literalinclude:: snippets/GetS3ObjectApp/GetS3Object.java :language: java @@ -174,12 +178,8 @@ Therefore, unless you have your AWS credentials specified already, the code will Transfer the Compiled Program to Your EC2 Instance -------------------------------------------------- -Transfer the program to your EC2 instance using secure copy (scp), along with the |sdk-java| -libraries. The sequence of commands looks something like the following. Depending on the Linux -distribution that you used, the user name might be "ec2-user", "root", or "ubuntu". To get the -public DNS name of your instance, select it in the |EC2| console, and then look for -:guilabel:`Public DNS` in the :guilabel:`Description` tab (for example, -ec2-198-51-100-1.compute-1.amazonaws.com). +Transfer the program to your |EC2| instance using secure copy (:command:`scp`), along with the +|sdk-java| libraries. The sequence of commands looks something like the following. .. code-block:: sh @@ -188,20 +188,33 @@ ec2-198-51-100-1.compute-1.amazonaws.com). scp -r -p -i {my-key-pair}.pem lib ec2-user@{public_dns}:lib scp -r -p -i {my-key-pair}.pem third-party ec2-user@{public_dns}:third-party -In the preceding commands, :code:`GetS3Object.class` is your compiled program, :code:`build.xml` is -the ant file used to build and run your program, and the :code:`lib` and :code:`third-party` -directories are the corresponding library folders from the |sdk-java|. +.. note:: Depending on the Linux distribution that you used, the *user name* might be "ec2-user", + "root", or "ubuntu". To get the public DNS name of your instance, open the :console:`EC2 + console ` and look for the :guilabel:`Public DNS` value in the :guilabel:`Description` tab + (for example, :code:`ec2-198-51-100-1.compute-1.amazonaws.com`). -The :code:`-r` switch indicates that :literal:`scp` should do a recursive copy of all of the -contents of the library and third-party directories from the |sdk-java|. +In the preceding commands: -The :code:`-p` switch indicates that :literal:`scp` should preserve the permissions of the source -files when it copies them to the destination. If you are copying the files from Windows, you might -need to fix the permissions on your instance using the following command: +* :code:`GetS3Object.class` is your compiled program -.. code-block:: sh +* :code:`build.xml` is the ant file used to build and run your program - chmod -R u+rwx GetS3Object.class build.xml lib third-party +* the :code:`lib` and :code:`third-party` directories are the corresponding library folders from the + |sdk-java|. + +* The :code:`-r` switch indicates that :literal:`scp` should do a recursive copy of all of the + contents of the :file:`library` and :file:`third-party` directories in the |sdk-java| + distribution. + +* The :code:`-p` switch indicates that :literal:`scp` should preserve the permissions of the source + files when it copies them to the destination. + + .. tip:: The :code:`-p` switch works only on |unixes|. If you are copying files from Windows, you + may need to fix the file permissions on your instance using the following command: + + .. code-block:: sh + + chmod -R u+rwx GetS3Object.class build.xml lib third-party .. _java-dg-run-the-program: @@ -209,21 +222,19 @@ need to fix the permissions on your instance using the following command: Run the Sample Program on the EC2 Instance ------------------------------------------ -To run the program, connect to your EC2 instance. For more information, see :ec2-ug:`Connect to Your -Linux Instance ` in the |EC2-ug|. +To run the program, connect to your |EC2| instance. For more information, see :ec2-ug:`Connect to +Your Linux Instance ` in the |EC2-ug|. -If ant is not installed on your instance, you can install it using the `yum -`_ installer as follows: +If :command:`ant` is not available on your instance, install it using the following command: .. code-block:: sh - sudo yum install ant + sudo yum install ant -Run the program using :code:`ant` as follows: +Then, run the program using :code:`ant` as follows: .. code-block:: sh - ant run + ant run The program will write the contents of your |S3| object to your command window. - diff --git a/doc_source/java-dg-samples.rst b/doc_source/java-dg-samples.rst index d24b8d8..343550d 100644 --- a/doc_source/java-dg-samples.rst +++ b/doc_source/java-dg-samples.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,90 +8,87 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -################ -SDK Code Samples -################ +####################### +Code Samples included with the SDK +####################### -The |sdk-java| comes packaged with a number of code samples that demonstrate many of the features of -the SDK in buildable, runnable programs that you can study or modify to implement your own AWS +The |sdk-java| comes packaged with code samples that demonstrate many of the features of +the SDK in buildable, runnable programs. You can study or modify these to implement your own AWS solutions using the |sdk-java|. -.. contents:: - :depth: 1 - :local: -How to get the samples +How to Get the Samples ====================== The |sdk-java| code samples are provided in the `samples` directory of the SDK. If you downloaded -and installed the SDK using the information in :doc:`setup-install`, then you already have the +and installed the SDK using the information in :doc:`setup-install`, you already have the samples on your system. -You can also view the latest samples on the |sdk-java|'s GitHub repository, in the `src/samples -`_ directory. +You can also view the latest samples on the |sdk-java| GitHub repository, in the +:github:`src/samples ` directory. .. _samples-cmdline: -Building and running the samples using the command line +Building and Running the Samples Using the Command Line ======================================================= The samples include `Ant `_ build scripts so that you can easily build and run them from the command line. Each sample also contains a README file in HTML format that contains information specific to each sample. -.. tip:: If you are browsing the sample code on GitHub, click the :guilabel:`Raw` button in the source - code display when viewing the README.html file for a sample. In raw mode, the HTML will render +.. tip:: If you're browsing the sample code on GitHub, click the :guilabel:`Raw` button in the source + code display when viewing the sample's README.html file. In raw mode, the HTML will render as intended in your browser. Prerequisites ------------- -Before running any of the |sdk-java| samples, you will need to set your AWS credentials in the -environment or with the AWS CLI as specified in :doc:`setup-credentials`. The samples use the default -credential provider chain whenever possible, so by setting your credentials this way, you can avoid +Before running any of the |sdk-java| samples, you need to set your AWS credentials in the +environment or with the AWS CLI, as specified in :doc:`setup-credentials`. The samples use the default +credential provider chain whenever possible. So by setting your credentials in this way, you can avoid the risky practice of inserting your AWS credentials in files within the source code directory (where they may inadvertently be checked in and shared publicly). -Running the samples +Running the Samples ------------------- -**To run a sample from the command line** +.. topic:: To run a sample from the command line -1. Change to the directory containing the sample's code. For example, if you are in the root - directory of the AWS SDK download and want to run the :file:`AwsConsoleApp` sample, you would - type: + #. Change to the directory containing the sample's code. For example, if you're in the root + directory of the AWS SDK download and want to run the :file:`AwsConsoleApp` sample, you would + type: - .. code-block:: none + .. code-block:: none - cd samples/AwsConsoleApp + cd samples/AwsConsoleApp -2. Build and run the sample with Ant. The default build target performs both actions, so you can - just enter: + #. Build and run the sample with Ant. The default build target performs both actions, so you can + just enter: - .. code-block:: none + .. code-block:: none - ant + ant - The sample prints information to standard output |mdash| for example: +The sample prints information to standard output |mdash| for example: - .. code-block:: none +.. code-block:: none - =========================================== + =========================================== - Welcome to the AWS Java SDK! + Welcome to the AWS Java SDK! - =========================================== - You have access to 4 Availability Zones. + =========================================== + You have access to 4 Availability Zones. - You have 0 Amazon EC2 instance(s) running. + You have 0 Amazon EC2 instance(s) running. - You have 13 Amazon SimpleDB domain(s) containing a total of 62 items. + You have 13 Amazon SimpleDB domain(s) containing a total of 62 items. - You have 23 Amazon S3 bucket(s), containing 44 objects with a total size of 154767691 bytes. + You have 23 Amazon S3 bucket(s), containing 44 objects with a total size of 154767691 bytes. -Building and Running the Samples using the Eclipse IDE +Building and Running the Samples Using the Eclipse IDE ====================================================== If you use the |tke|, you can also start a new project in Eclipse based on the |sdk-java| or add the @@ -101,46 +98,49 @@ Prerequisites ------------- After installing the |tke|, we recommend configuring the Toolkit with your security credentials. -You can do this anytime by selecting :guilabel:`Preferences` from the :guilabel:`Window` menu in -Eclipse, and then selecting the :guilabel:`AWS Toolkit` section. +You can do this anytime by choosing :guilabel:`Preferences` from the :guilabel:`Window` menu in +Eclipse, and then choosing the :guilabel:`AWS Toolkit` section. -Running the samples +Running the Samples ------------------- -**To run a sample using the AWS Toolkit for Eclipse** +.. topic:: To run a sample using the AWS Toolkit for Eclipse -1. Open Eclipse. + #. Open Eclipse. -2. Create a new AWS Java project. In Eclipse, on the :guilabel:`File` menu, point to - :guilabel:`New`, and then click :guilabel:`Project`. The :guilabel:`New Project` wizard opens. + #. Create a new AWS Java project. In Eclipse, on the :guilabel:`File` menu, choose + :guilabel:`New`, and then click :guilabel:`Project`. The :guilabel:`New Project` wizard + opens. -3. Expand the :guilabel:`AWS` category, then select :guilabel:`AWS Java Project`. + #. Expand the :guilabel:`AWS` category, then choose :guilabel:`AWS Java Project`. -4. Click :guilabel:`Next`. The project settings page is displayed. + #. Choose :guilabel:`Next`. The project settings page is displayed. -5. Enter a name in the :guilabel:`Project Name` box. The AWS SDK for Java Samples group displays - the samples available in the SDK, as described previously. + #. Enter a name in the :guilabel:`Project Name` box. The AWS SDK for Java Samples group displays + the samples available in the SDK, as described previously. -6. Select the samples you want to include in your project by selecting each check box. + #. Select the samples you want to include in your project by selecting each check box. -7. Enter your AWS credentials. If you've already configured the |tke| with your credentials, this - is automatically filled in. + #. Enter your AWS credentials. If you've already configured the |tke| with your credentials, + this is automatically filled in. -8. Click :guilabel:`Finish`. The project is created and added to the :guilabel:`Project Explorer`. + #. Choose :guilabel:`Finish`. The project is created and added to the :guilabel:`Project + Explorer`. -**To run the project** -1. Select the sample :file:`.java` file you want to run. For example, for the |S3| sample, select - :file:`S3Sample.java`. +.. topic:: To run the project -2. Select :guilabel:`Run` from the :guilabel:`Run` menu. + #. Choose the sample :file:`.java` file you want to run. For example, for the |S3| sample, choose + :file:`S3Sample.java`. -**To add the SDK to an existing project** + #. Choose :guilabel:`Run` from the :guilabel:`Run` menu. -1. Right-click the project in :guilabel:`Project Explorer`, point to :guilabel:`Build Path`, and - then click :guilabel:`Add Libraries`. -2. Select :guilabel:`AWS Java SDK`, and then click :guilabel:`Next` and follow the remaining - on-screen instructions. +.. topic:: To add the SDK to an existing project + #. Right-click the project in :guilabel:`Project Explorer`, point to :guilabel:`Build Path`, and + then choose :guilabel:`Add Libraries`. + + #. Choose :guilabel:`AWS Java SDK`, choose :guilabel:`Next`, and then follow the remaining + on-screen instructions. diff --git a/doc_source/java-dg-tomcat-session-manager.rst b/doc_source/java-dg-tomcat-session-manager.rst deleted file mode 100644 index b0ffd60..0000000 --- a/doc_source/java-dg-tomcat-session-manager.rst +++ /dev/null @@ -1,203 +0,0 @@ -.. Copyright 2010-2016 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. - -###################################### -Manage Tomcat Session State with |DDB| -###################################### - -Tomcat applications often store session-state data in memory. However, this approach doesn't scale -well; once the application grows beyond a single web server, the session state must be shared -between servers. A common solution is to set up a dedicated session-state server with MySQL. This -approach also has drawbacks: you must administer another server, the session-state server is a -single pointer of failure, and the MySQL server itself can cause performance problems. - -DynamoDB, a NoSQL database store from Amazon Web Services (AWS), avoids these drawbacks by providing -an effective solution for sharing session state across web servers. - -.. _java-dg-tomcat-sess-download: - -Downloading the Session Manager -=============================== - -You can download the session manager from the `aws/aws-dynamodb-session-tomcat -`_ project on GitHub. That project also hosts -the session manager source code if you want to contribute to the project by sending us pull requests -or opening issues. - - -.. _java-dg-tomcat-sess-config-provider: - -Configure the Session-State Provider -==================================== - -To use the |DDB| session-state provider, you need to 1) configure the Tomcat server to use the -provider, and 2) set the security credentials of the provider so that it can access AWS. - -.. _java-dg-tomcat-sess-config-for-ddb: - -Configuring a Tomcat Server to Use |DDB| as the Session-State Server --------------------------------------------------------------------- - -Copy :file:`AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar` to the :code:`lib` directory of your -Tomcat installation. :file:`AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar` is a complete, -standalone jar, containing all the code and dependencies to run the |DDB| Tomcat Session Manager. - -Edit your server's :file:`context.xml` file to specify -:emphasis:`com.amazonaws.services.dynamodb.sessionmanager.DynamoDBSessionManager` as your session -manager. - -.. code-block:: java - - - - WEB-INF/web.xml - - - - -.. _java-dg-tomcat-sess-config-creds: - -Configuring Your AWS Security Credentials ------------------------------------------ - -You can specify AWS security credentials for the session manager in multiple ways, and they are -loaded in the following order of precedence: - -1. The :code:`AwsAccessKey` and :code:`AwsSecretKey` attributes of the :code:`Manager` element - explicitly provide credentials. - -2. The :code:`AwsCredentialsFile` attribute on the :code:`Manager` element specifies a properties - file from which to load credentials. - -If no credentials are specified through the :code:`Manager` element, -:code:`DefaultAWSCredentialsProviderChain` will keep searching for credentials in the following -order: - -1. Environment Variables |ndash| :code:`AWS_ACCESS_KEY_ID` and :code:`AWS_SECRET_ACCESS_KEY` - -2. Java System Properties |ndash| :code:`aws.accessKeyId` and :code:`aws.secretKey` - -3. Instance profile credentials delivered through the |EC2| instance metadata service (IMDS). - - -.. _java-dg-tomcat-sess-config-elb: - -Configuring with |EB| ---------------------- - -If you're using the session manager in |EB|, you need to ensure your project has a -:file:`.ebextensions` directory at the top level of your output artifact structure. In that -directory, place the following files: - -* The :file:`AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar` file. - -* A :file:`context.xml` file as described previously to configure the session manager. - -* A config file that copies the jar into Tomcat's lib directory and applies the overridden - :file:`context.xml` file. - -For more information about customizing |EB| environments, see :eb-dg:`AWS Elastic Beanstalk -Environment Configuration ` in the |EB-dg|. - -If you deploy to |EB| with the |tke|, then the session manager is set up for you if you go through -the :guilabel:`New AWS Java Web Project` wizard and select |DDB| for session management. The |tke| -configures all the needed files, and puts them in the :file:`.ebextensions` directory inside the -:file:`WebContent` directory of your project. If you have problems finding this directory, make sure -you aren't hiding files that begin with a period. - - - -.. _java-dg-tomcat-sess-manage-with-ddb: - -Manage Tomcat Session State with |DDB| -====================================== - -If the Tomcat server is running on an |EC2| instance that is configured to use |IAM| roles for EC2 -Instances, you do not need to specify any credentials in the :file:`context.xml` file; in this case, -the |sdk-java| uses |IAM| roles credentials obtained through the instance metadata service (IMDS). - -When your application starts, it looks for an |DDB| table called, by default, -:guilabel:`Tomcat_SessionState`. The table should have a string hash key named "sessionId" -(case-sensitive), no range key, and the desired values for :code:`ReadCapacityUnits` and -:code:`WriteCapacityUnits`. - -We recommend that you create this table before first running your application. If you don't create -the table, however, the extension creates it during initialization. See the :file:`context.xml` -options in the next section for a list of attributes that configure how the session-state table is -created when it doesn't exist. - -.. tip:: For information about working with |DDB| tables and provisioned throughput, see the - |DDB-dg|_. - -Once the application is configured and the table is created, you can use sessions with any other -session provider. - - -.. _java-dg-tomcat-sess-option: - -Options Specified in context.xml -================================ - -Below are the configuration attributes that you can use in the :code:`Manager` element of your -:file:`context.xml` file: - -* :emphasis:`AwsAccessKey` |ndash| Access key ID to use. - -* :emphasis:`AwsSecretKey` |ndash| Secret key to use. - -* :emphasis:`AwsCredentialsFile` |ndash| A properties file containing :code:`accessKey` and - :code:`secretKey` properties with your AWS security credentials. - -* :emphasis:`Table` |ndash| Optional string attribute. The name of the table used to store session - data. The default is :guilabel:`Tomcat_SessionState`. - -* :emphasis:`RegionId` |ndash| Optional string attribute. The AWS region in which to use |DDB|. - For a list of available AWS regions, see Regions and Endpoints in the :emphasis:`Amazon Web - Services General Reference`. - -* :emphasis:`Endpoint` |ndash| Optional string attribute; if present, this option overrides any - value set for the :code:`Region` option. The regional endpoint of the |DDB| service to use. For - a list of available AWS regions, see Regions and Endpoints in the :emphasis:`Amazon Web Services - General Reference`. - -* :emphasis:`ReadCapacityUnits` |ndash| Optional int attribute. The read capacity units to use if - the session manager creates the table. The default is 10. - -* :emphasis:`WriteCapacityUnits` |ndash| Optional int attribute. The write capacity units to use - if the session manager creates the table. The default is 5. - -* :emphasis:`CreateIfNotExist` |ndash| Optional Boolean attribute. The :code:`CreateIfNotExist` - attribute controls whether the session manager autocreates the table if it doesn't exist. The - default is true. If this flag is set to false and the table doesn't exist, an exception is - thrown during Tomcat startup. - - -.. _java-dg-tomcat-sess-troubleshooting: - -Troubleshooting -=============== - -If you encounter issues with the session manager, the first place to look is in -:file:`catalina.out`. If you have access to the Tomcat installation, you can go directly to this log -file and look for any error messages from the session manager. If you're using |EB|, you can view -the environment logs with the |console| or the |tke|. - - -.. _java-dg-tomcat-limits: - -Limitations -=========== - -The session manager does not support session locking. Therefore, applications that use many -concurrent AJAX calls to manipulate session data may not be appropriate for use with the session -manager, due to race conditions on session data writes and saves back to the data store. - - diff --git a/doc_source/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-ec2.rst b/doc_source/prog-services-ec2.rst index b6948c3..8a2f7a9 100644 --- a/doc_source/prog-services-ec2.rst +++ b/doc_source/prog-services-ec2.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,9 +8,14 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -##### -|EC2| -##### +################################### +|EC2| Examples Using the |sdk-java| +################################### + +.. meta:: + :description: Programming Amazon EC2 using the AWS SDK for Java + :keywords: AWS SDK for Java code examples + This section provides examples of programming |EC2|_ with the |sdk-java|. @@ -22,3 +27,9 @@ This section provides examples of programming |EC2|_ with the |sdk-java|. java-dg-roles tutorial-spot-instances-java tutorial-spot-adv-java + examples-ec2-instances + examples-ec2-elastic-ip + examples-ec2-regions-zones + examples-ec2-key-pairs + examples-ec2-security-groups + diff --git a/doc_source/prog-services-sts.rst b/doc_source/prog-services-sts.rst index e14cb2a..f82ecb5 100644 --- a/doc_source/prog-services-sts.rst +++ b/doc_source/prog-services-sts.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 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 @@ -17,17 +17,17 @@ access AWS services. There are three steps involved in using |STS|: -1. Activate a region (optional). +#. Activate a region (optional). -2. Retrieve temporary security credentials from |STS|. +#. Retrieve temporary security credentials from |STS|. -3. Use the credentials to access AWS resources. +#. Use the credentials to access AWS resources. -.. note:: Activating a region is :emphasis:`optional`; by default, temporary security credentials are - obtained from the global endpoint :emphasis:`sts.amazonaws.com`. However, to reduce latency and - to enable you to build redundancy into your requests by using additional endpoints if an |STS| - request to the first endpoint fails, you can activate regions that are geographically closer to - your services or applications that use the credentials. +.. note:: Activating a region is :emphasis:`optional`; by default, temporary security credentials + are obtained from the global endpoint :emphasis:`sts.amazonaws.com`. However, to reduce latency + and to enable you to build redundancy into your requests by using additional endpoints if an + |STS| request to the first endpoint fails, you can activate regions that are geographically + closer to your services or applications that use the credentials. .. _optional-activate-and-use-an-sts-region: @@ -37,21 +37,21 @@ There are three steps involved in using |STS|: To activate a region for use with |STS|, use the AWS Management Console to select and activate the region. -**To activate additional STS regions** +.. topic:: To activate additional STS regions -1. Sign in as an IAM user with permissions to perform IAM administration tasks :code:`"iam:*"` for - the account for which you want to activate AWS STS in a new region. + #. Sign in as an IAM user with permissions to perform IAM administration tasks :code:`"iam:*"` + for the account for which you want to activate AWS STS in a new region. -2. Open the IAM console and in the navigation pane click :guilabel:`Account Settings`. + #. Open the IAM console and in the navigation pane click :guilabel:`Account Settings`. -3. Expand the :guilabel:`STS Regions` list, find the region that you want to use, and then click - :guilabel:`Activate`. + #. Expand the :guilabel:`STS Regions` list, find the region that you want to use, and then click + :guilabel:`Activate`. After this, you can direct calls to the STS endpoint that is associated with that region. -.. note:: For more information about activating STS regions and for a list of the available AWS STS - endpoints, see `Activating AWS STS in a New Region - `_ in the |STS-ug|. +.. note:: For more information about activating STS regions and for a list of the available AWS STS + endpoints, see :iam-ug:`Activating and Deactivating AWS STS in an AWS Region + ` in the |IAM-ug|. .. _retrieving-an-sts-token: @@ -59,68 +59,58 @@ After this, you can direct calls to the STS endpoint that is associated with tha Retrieve temporary security credentials from |STS| ================================================== -**To retrieve temporary security credentials using the AWS SDK for Java** +.. topic:: To retrieve temporary security credentials using the AWS SDK for Java -1. Create an :java-api:`AWSSecurityTokenServiceClient` object: + #. Create an :aws-java-class:`AWSSecurityTokenServiceClient + ` object: - .. code-block:: java + .. 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 - 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. + 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. -2. :emphasis:`Optional`; requires that you have activated the region) Set the endpoint for the STS - client: + #. Create a :aws-java-class:`GetSessionTokenRequest + ` object, and optionally set the + duration in seconds for which the temporary credentials are valid: - .. code-block:: java + .. code-block:: java - sts_client.setEndpoint("sts-endpoint.amazonaws.com"); + GetSessionTokenRequest session_token_request = new GetSessionTokenRequest(); + session_token_request.setDurationSeconds(7200); // optional. - where :emphasis:`sts-endpoint` represents the STS endpoint for your region. + The duration of temporary credentials can range from 900 seconds (15 minutes) to 129600 + seconds (36 hours) for IAM users. If a duration isn't specified, then 43200 seconds (12 + hours) is used by default. - .. 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. + For a root AWS account, the valid range of temporary credentials is from 900 to 3600 seconds + (1 hour), with a default value of 3600 seconds if no duration is specified. -3. Create a :java-api:`GetSessionTokenRequest ` object, and - optionally set the duration in seconds for which the temporary credentials are valid: + .. important:: It is :emphasis:`strongly recommended`, from a security standpoint, that you + :emphasis:`use IAM users` instead of the root account for AWS access. For more + information, see IAM Best Practices in the |iam-ug|. - .. code-block:: java + #. Call :aws-java-ref:`getSessionToken + ` + on the STS client to get a session token, using the :classname:`GetSessionTokenRequest` + object: - GetSessionTokenRequest session_token_request = new GetSessionTokenRequest(); - session_token_request.setDurationSeconds(7200); // optional. + .. code-block:: java - The duration of temporary credentials can range from 900 seconds (15 minutes) to 129600 seconds - (36 hours) for IAM users. If a duration isn't specified, then 43200 seconds (12 hours) is used - by default. + GetSessionTokenResult session_token_result = + sts_client.getSessionToken(session_token_request); - For a root AWS account, the valid range of temporary credentials is from 900 to 3600 seconds (1 - hour), with a default value of 3600 seconds if no duration is specified. + #. Get session credentials using the result of the call to :methodname:`getSessionToken`: - .. important:: It is :emphasis:`strongly recommended`, from a security standpoint, that you - :emphasis:`use IAM users` instead of the root account for AWS access. For more information, see - IAM Best Practices in the |iam-ug|. + .. code-block:: java -4. Call :java-api:`getSessionToken - ` - on the STS client to get a session token, using the :classname:`GetSessionTokenRequest` object: + Credentials session_creds = session_token_result.getCredentials(); - .. code-block:: java - - GetSessionTokenResult session_token_result = - sts_client.getSessionToken(session_token_request); - -5. Get session credentials using the result of the call to :methodname:`getSessionToken`: - - .. code-block:: java - - Credentials session_creds = session_token_result.getCredentials(); - - The session credentials provide access only for the duration that was specified by the - :classname:`GetSessionTokenRequest` object. Once the credentials expire, you will need to call - :methodname:`getSessionToken` again to obtain a new session token for continued access to AWS. +The session credentials provide access only for the duration that was specified by the +:classname:`GetSessionTokenRequest` object. Once the credentials expire, you will need to call +:methodname:`getSessionToken` again to obtain a new session token for continued access to AWS. .. _use-the-token-to-access-aws-resources: @@ -134,8 +124,8 @@ to use its resources, using the technique described in :ref:`credentials-explici For example, to create an S3 client using temporary service credentials: .. literalinclude:: snippets/sts_basic_session_creds.java - :language: java - :lines: 14- + :language: java + :lines: 14- You can now use the :classname:`AmazonS3` object to make Amazon S3 requests. @@ -145,13 +135,15 @@ For more information ==================== For more information about how to use temporary security credentials to access AWS resources, visit -the following sections in the |STS-ug|: +the following sections in the |IAM-ug|: -* `Creating Temporary Security Credentials `_ +* :iam-ug:`Requesting Temporary Security Credentials ` -* `Controlling Permissions for Temporary Security Credentials `_ +* :iam-ug:`Controlling Permissions for Temporary Security Credentials + ` -* `Requesting AWS Resources Using Temporary Security Credentials `_ +* :iam-ug:`Using Temporary Security Credentials to Request Access to AWS Resources + ` -* `Activating STS in a New Region `_ +* :iam-ug:`Activating and Deactivating AWS STS in an AWS Region ` diff --git a/doc_source/prog-services-swf-list-domains.rst b/doc_source/prog-services-swf-list-domains.rst index 9b1065d..65f2f4b 100644 --- a/doc_source/prog-services-swf-list-domains.rst +++ b/doc_source/prog-services-swf-list-domains.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -14,27 +14,27 @@ Listing Domains You can list the |SWF|_ domains associated with your account and AWS region by registration type. -**To list Amazon SWF domains** +.. topic:: To list |SWF| domains -1. Create a :java-api:`ListDomainsRequest ` - object, and specify the registration status of the domains that you're interested in |mdash| - this is required. + #. Create a :aws-java-class:`ListDomainsRequest + ` object, and specify the registration + status of the domains that you're interested in |mdash| this is required. -2. Call :java-ref:`AmazonSimpleWorkflowClient.listDomains - ` - with the :emphasis:`ListDomainRequest` object. Results are provided in a :java-api:`DomainInfos - ` object. + #. Call :aws-java-ref:`AmazonSimpleWorkflowClient.listDomains + ` + with the :emphasis:`ListDomainRequest` object. Results are provided in a + :aws-java-class:`DomainInfos ` object. -3. Call :java-ref:`getDomainInfos - ` on the returned object to - get a list of :java-api:`DomainInfo ` objects. + #. Call :aws-java-ref:`getDomainInfos + ` on the returned object to + get a list of :aws-java-class:`DomainInfo ` objects. -4. Call :java-ref:`getName ` on each - :emphasis:`DomainInfo` object to get its name. + #. Call :aws-java-ref:`getName ` on + each :emphasis:`DomainInfo` object to get its name. The following code demonstrates this procedure: .. literalinclude:: snippets/CreateSwfDomain-list_swf_domains.java - :language: java - :lines: 14- + :language: java + :lines: 14- diff --git a/doc_source/prog-services-swf-register-domain.rst b/doc_source/prog-services-swf-register-domain.rst index 85b3831..9e7f157 100644 --- a/doc_source/prog-services-swf-register-domain.rst +++ b/doc_source/prog-services-swf-register-domain.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -14,19 +14,20 @@ Registering Domains Every workflow and activity in |SWF|_ needs a :emphasis:`domain` to run in. -**To register an Amazon SWF domain** +.. topic:: To register an |SWF| domain -1. Create a new :java-api:`RegisterDomainRequest - ` object, providing it with at least the - domain name and workflow execution retention period (these parameters are both required). + #. Create a new :aws-java-class:`RegisterDomainRequest + ` object, providing it with at least + the domain name and workflow execution retention period (these parameters are both + required). -2. Call the :java-ref:`AmazonSimpleWorkflowClient.registerDomain - ` - method with the :emphasis:`RegisterDomainRequest` object. + #. Call the :aws-java-ref:`AmazonSimpleWorkflowClient.registerDomain + ` + method with the :emphasis:`RegisterDomainRequest` object. -3. Catch the :java-api:`DomainAlreadyExistsException - ` if the domain you're requesting - already exists (in which case, no action is usually required). + #. Catch the :aws-java-class:`DomainAlreadyExistsException + ` if the domain you're + requesting already exists (in which case, no action is usually required). The following code demonstrates this procedure: diff --git a/doc_source/prog-services-swf.rst b/doc_source/prog-services-swf.rst index 9691236..04e4dc6 100644 --- a/doc_source/prog-services-swf.rst +++ b/doc_source/prog-services-swf.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,9 +8,9 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -##### -|SWF| -##### +################################### +|SWF| Examples Using the |sdk-java| +################################### |SWF|_ is a workflow-management service that helps developers build and scale distributed workflows that can have parallel or sequential steps consisting of activities, child workflows or diff --git a/doc_source/prog-services.rst b/doc_source/prog-services.rst index ade0620..995b1b3 100644 --- a/doc_source/prog-services.rst +++ b/doc_source/prog-services.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 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 @@ -8,11 +8,25 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -###################### -Tutorials and Examples -###################### +######################## +|sdk-java| Code Examples +######################## + +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 -This section provides tutorials and examples of using the |sdk-java| with AWS service clients. .. tip:: See :ref:`additional-resources` for more examples and additional resources available for |sdk-java| developers! @@ -20,11 +34,14 @@ This section provides tutorials and examples of using the |sdk-java| with AWS se .. toctree:: :maxdepth: 1 :titlesonly: - :glob: - - java-dg-samples - prog-services-ddb - prog-services-ec2 - prog-services-sts - prog-services-swf - examples/s3 + + 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 + Amazon SWF Examples + Code Samples included with the SDK diff --git a/doc_source/run-instance.rst b/doc_source/run-instance.rst index 790cf4a..2938e60 100644 --- a/doc_source/run-instance.rst +++ b/doc_source/run-instance.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -16,59 +16,60 @@ Use the following procedure to launch one or more identically configured EC2 ins Amazon Machine Image (AMI). After you create your EC2 instances, you can check their status. After your EC2 instances are running, you can connect to them. -**To launch an Amazon EC2 instance** +.. topic:: To launch an |EC2| instance -1. Create and initialize a :java-api:`RunInstancesRequest ` - instance. Make sure that the AMI, key pair, and security group that you specify exist in the - region that you specified when you created the client object. + #. Create and initialize a :aws-java-class:`RunInstancesRequest + ` instance. Make sure that the AMI, key pair, and + security group that you specify exist in the region that you specified when you created the + client object. - .. code-block:: java + .. code-block:: java - RunInstancesRequest runInstancesRequest = - new RunInstancesRequest(); + RunInstancesRequest runInstancesRequest = + new RunInstancesRequest(); - runInstancesRequest.withImageId("ami-4b814f22") - .withInstanceType("m1.small") - .withMinCount(1) - .withMaxCount(1) - .withKeyName("my-key-pair") - .withSecurityGroups("my-security-group"); + runInstancesRequest.withImageId("ami-a9d09ed1") + .withInstanceType(InstanceType.T1Micro) + .withMinCount(1) + .withMaxCount(1) + .withKeyName("my-key-pair") + .withSecurityGroups("my-security-group"); - :java-ref:`withImageId ` - The ID of the AMI. For a list of public AMIs provided by Amazon, see Amazon Machine Images. + :aws-java-ref:`withImageId ` + The ID of the AMI. To learn how to find public AMIs provided by Amazon or + create your own, see :ec2-ug:`Amazon Machine Image (AMI) `. - :java-ref:`withInstanceType ` - An instance type that is compatible with the specified AMI. For more information, see - :ec2-ug:`Instance Types ` in the |EC2-ug|. + :aws-java-ref:`withInstanceType ` + An instance type that is compatible with the specified AMI. For more information, see + :ec2-ug:`Instance Types ` in the |EC2-ug|. - :java-ref:`withMinCount ` - The minimum number of EC2 instances to launch. If this is more instances than |EC2| can - launch in the target Availability Zone, |EC2| launches no instances. + :aws-java-ref:`withMinCount ` + The minimum number of EC2 instances to launch. If this is more instances than |EC2| can + launch in the target Availability Zone, |EC2| launches no instances. - :java-ref:`withMaxCount ` - The maximum number of EC2 instances to launch. If this is more instances than |EC2| can - launch in the target Availability Zone, |EC2| launches the largest possible number of - instances above :code:`MinCount`. You can launch between 1 and the maximum number of - instances you're allowed for the instance type. For more information, see How many instances - can I run in Amazon EC2 in the |EC2| General FAQ. + :aws-java-ref:`withMaxCount ` + The maximum number of EC2 instances to launch. If this is more instances than |EC2| can + launch in the target Availability Zone, |EC2| launches the largest possible number of + instances above :code:`MinCount`. You can launch between 1 and the maximum number of + instances you're allowed for the instance type. For more information, see How many + instances can I run in Amazon EC2 in the |EC2| General FAQ. - :java-ref:`withKeyName ` - The name of the EC2 key pair. If you launch an instance without specifying a key pair, you - can't connect to it. For more information, see :doc:`create-key-pair`. + :aws-java-ref:`withKeyName ` + The name of the EC2 key pair. If you launch an instance without specifying a key pair, you + can't connect to it. For more information, see :doc:`create-key-pair`. - :java-ref:`withSecurityGroups ` - One or more security groups. For more information, see :doc:`create-security-group`. + :aws-java-ref:`withSecurityGroups ` + One or more security groups. For more information, see :doc:`create-security-group`. -2. Launch the instances by passing the request object to the :java-ref:`runInstances - ` - method. The method returns a :java-api:`RunInstancesResult - ` object, as follows: + #. Launch the instances by passing the request object to the :aws-java-ref:`runInstances + ` + method. The method returns a :aws-java-class:`RunInstancesResult + ` object, as follows: - .. code-block:: java + .. code-block:: java - RunInstancesResult runInstancesResult = - amazonEC2Client.runInstances(runInstancesRequest); + RunInstancesResult result = amazonEC2Client.runInstances( + runInstancesRequest); After your instance is running, you can connect to it using your key pair. For more information, see :ec2-ug:`Connect to Your Linux Instance `. in the |EC2-ug|. - diff --git a/doc_source/s3-encryption-migration.rst b/doc_source/s3-encryption-migration.rst new file mode 100644 index 0000000..0b09cac --- /dev/null +++ b/doc_source/s3-encryption-migration.rst @@ -0,0 +1,277 @@ +.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +################################ +|S3| Encryption Client Migration +################################ + +.. meta:: + :description: How to migrate your applications from v1 to v2 of the AWS S3 client-side encryption + service client + :keywords: AWS for Java SDK, migrate, migration, CSE, encryption, key, KMS, S3, + AmazonS3EncryptionClientV2, AmazonS3EncryptionClient + + +This topic shows you how to migrate your applications from Version 1 (V1) of the |S3long| (|S3|) +encryption client to Version 2 (V2) and ensure application availability throughout the migration +process. + +.. _s3-cse-prereq: + +Prerequisites +============= + +|S3| client-side encryption requires the following: + +* Java 8 or later installed in your application environment. The |sdk-java| works with the + `Oracle Java SE Development Kit `_ + and with distributions of Open Java Development Kit (OpenJDK) such as + `Amazon Corretto `_, + `Red Hat OpenJDK `_, + and `AdoptOpenJDK `_. + +* The `Bouncy Castle Crypto package `_. You can + place the Bouncy Castle .jar file on the classpath of your application environment, or add a + dependency on the artifactId :code:`bcprov-ext-jdk15on` (with the groupId of + :code:`org.bouncycastle`) to your Maven :file:`pom.xml` file. + +.. _s3-cse-overview: + +Migration Overview +================== + +This migration happens in two phases: + +1. **Update existing clients to read new formats.** Update your application to use version 1.11.837 + or later of the AWS SDK for Java and redeploy the application. This enables the |S3| client-side + encryption service clients in your application to decrypt objects created by V2 service clients. + If your application uses multiple AWS SDKs, you must update each SDK separately. + +2. **Migrate encryption and decryption clients to V2.** Once all of your V1 encryption clients can + read V2 encryption formats, update the |S3| client-side encryption and decryption clients in your + application code to use their V2 equivalents. + +.. _s3-cse-update-project: + +Update Existing Clients to Read New Formats +=========================================== + +The V2 encryption client uses encryption algorithms that older versions of the AWS SDK for Java do +not support. + +The first step in the migration is to update your V1 encryption clients to use version 1.11.837 or +later of the |sdk-java|. (We recommend that you update to the latest release version, which you can +find in the +`Java API Reference version 1.x `_.) To do +so, update the dependency in your project configuration. After your project configuration is +updated, rebuild your project and redeploy it. + +Once you have completed these steps, your application’s V1 encryption clients will be able to read +objects written by V2 encryption clients. + +Update the Dependency in Your Project Configuration +--------------------------------------------------- + +Modify your project configuration file (for example, pom.xml or build.gradle) to use version +1.11.837 or later of the AWS SDK for Java. Then, rebuild your project and redeploy it. + +Completing this step before deploying new application code helps to ensure that encryption +and decryption operations remain consistent across your fleet during the migration process. + +Example Using Maven +~~~~~~~~~~~~~~~~~~~ + +Snippet from a pom.xml file: + +.. code-block:: xml + + + + + com.amazonaws + aws-java-sdk-bom + 1.11.837 + pom + import + + + + +Example Using Gradle +~~~~~~~~~~~~~~~~~~~~ + +Snippet from a build.gradle file: + +.. code-block:: json + + dependencies { + implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.837') + implementation 'com.amazonaws:aws-java-sdk-s3' + } + +.. _s3-cse-update-code: + +Migrate Encryption and Decryption Clients to V2 +=============================================== + +Once your project has been updated with the latest SDK version, you can modify your application code +to use the V2 client. To do so, first update your code to use the new service client builder. Then +provide encryption materials using a method on the builder that has been renamed, and configure your +service client further as needed. + +These code snippets demonstrate how to use client-side encryption with the AWS SDK for Java, and +provide comparisons between the V1 and V2 encryption clients. + +**V1** + +.. code-block:: java + + // minimal configuration in V1; default CryptoMode.EncryptionOnly. + EncryptionMaterialsProvider encryptionMaterialsProvider = ... + AmazonS3Encryption encryptionClient = AmazonS3EncryptionClient.encryptionBuilder() + .withEncryptionMaterials(encryptionMaterialsProvider) + .build(); + +**V2** + +.. code-block:: java + + // minimal configuration in V2; default CryptoMode.StrictAuthenticatedEncryption. + EncryptionMaterialsProvider encryptionMaterialsProvider = ... + AmazonS3EncryptionV2 encryptionClient = AmazonS3EncryptionClientV2.encryptionBuilder() + .withEncryptionMaterialsProvider(encryptionMaterialsProvider) + .withCryptoConfiguration(new CryptoConfigurationV2() + // The following setting allows the client to read V1 encrypted objects + .withCryptoMode(CryptoMode.AuthenticatedEncryption) + ) + .build(); + +The above example sets the :code:`cryptoMode` to :code:`AuthenticatedEncryption`. This is a setting +that allows a V2 encryption client to read objects that have been written by a V1 encryption +client. If your client does not need the capability to read objects written by a V1 client, then we +recommend using the default setting of :code:`StrictAuthenticatedEncryption` instead. + +Construct a V2 Encryption Client +-------------------------------- + +The V2 encryption client can be constructed by calling +*AmazonS3EncryptionClientV2.encryptionBuilder().* + +You can replace all of your existing V1 encryption clients with V2 encryption clients. A V2 +encryption client will always be able to read any object that has been written by a V1 encryption +client as long as you permit it to do so by configuring the V2 encryption client to use the +:code:`AuthenticatedEncryption` :code:`cryptoMode`. + +Creating a new V2 encryption client is very similar to how you create a V1 encryption client. +However, there are a few differences: + +* You will use a :code:`CryptoConfigurationV2` object to configure the client instead of a + :code:`CryptoConfiguration` object. This parameter is required. +* The default :code:`cryptoMode` setting for the V2 encryption client is + :code:`StrictAuthenticatedEncryption`. For the V1 encryption client it is :code:`EncryptionOnly`. +* The method *withEncryptionMaterials()* on the encryption client builder has been renamed to + *withEncryptionMaterialsProvider()*. This is merely a cosmetic change that more accurately + reflects the argument type. You must use the new method when you configure your service client. + +.. note:: When decrypting with AES-GCM, read the entire object to the end before you start using the + decrypted data. This is to verify that the object has not been modified since it was encrypted. + + +Use Encryption Materials Providers +---------------------------------- + +You can continue to use the same encryption materials providers and encryption materials objects +you are already using with the V1 encryption client. These classes are responsible for providing the +keys the encryption client uses to secure your data. They can be used interchangeably with both the +V2 and the V1 encryption client. + +Configure the V2 Encryption Client +---------------------------------- + +The V2 encryption client is configured with a :code:`CryptoConfigurationV2` object. This object can be +constructed by calling its default constructor and then modifying its properties as required from +the defaults. + +The default values for :code:`CryptoConfigurationV2` are: + +* :code:`cryptoMode` = :code:`CryptoMode.StrictAuthenticatedEncryption` +* :code:`storageMode` = :code:`CryptoStorageMode.ObjectMetadata` +* :code:`secureRandom` = instance of :code:`SecureRandom` +* :code:`rangeGetMode` = :code:`CryptoRangeGetMode.DISABLED` +* :code:`unsafeUndecryptableObjectPassthrough` = :code:`false` + +Note that `EncryptionOnly` is not a supported :code:`cryptoMode` in the V2 encryption client. The V2 +encryption client will always encrypt content using authenticated encryption, and protects content +encrypting keys (CEKs) using V2 :code:`KeyWrap` objects. + +The following example demonstrates how to specify the crypto configuration in V1, and how to +instantiate a *CryptoConfigurationV2* object to pass to the V2 encryption client builder. + +**V1** + +.. code-block:: java + + CryptoConfiguration cryptoConfiguration = new CryptoConfiguration() + .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption); + +**V2** + +.. code-block:: java + + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption); + +.. _additional-examples: + +Additional Examples +=================== + +The following examples demonstrate how to address specific use cases related to a migration from V1 +to V2. + +Configure a Service Client to Read Objects Created by the V1 Encryption Client +------------------------------------------------------------------------------ + +To read objects that were previously written using a V1 encryption client, set the +:code:`cryptoMode` to :code:`AuthenticatedEncryption`. The following code snippet demonstrates how +to construct a configuration object with this setting. + +.. code-block:: java + + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withCryptoMode(CryptoMode.AuthenticatedEncryption); + +Configure a Service Client to Get Byte Ranges of Objects +-------------------------------------------------------- + +To be able to :code:`get` a range of bytes from an encrypted S3 object, enable the new configuration +setting :code:`rangeGetMode`. This setting is disabled on the V2 encryption client by default. Note +that even when enabled, a ranged :code:`get` only works on objects that have been encrypted using +algorithms supported by the :code:`cryptoMode` setting of the client. For more information, see +:aws-java-class:`CryptoRangeGetMode ` in the AWS SDK for Java +API Reference. + +If you plan to use the |S3| TransferManager to perform multipart downloads of encrypted |S3| objects +using the V2 encryption client, then you must first enable the :code:`rangeGetMode` setting on the +V2 encryption client. + +The following code snippet demonstrates how to configure the V2 client for performing a ranged +:code:`get`. + +.. code-block:: java + + // Allows range gets using AES/CTR, for V2 encrypted objects only + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withRangeGetMode(CryptoRangeGetMode.ALL); + + // Allows range gets using AES/CTR and AES/CBC, for V1 and V2 objects + CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2() + .withCryptoMode(CryptoMode.AuthenticatedEncryption) + .withRangeGetMode(CryptoRangeGetMode.ALL); diff --git a/doc_source/sdk-metrics.rst b/doc_source/sdk-metrics.rst new file mode 100755 index 0000000..ef87fca --- /dev/null +++ b/doc_source/sdk-metrics.rst @@ -0,0 +1,352 @@ +.. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +.. |language| replace:: Java +.. |sdk| replace:: |sdk-java| + +#################### +Enabling |SDKMlong| +#################### + +|SDKMlong| (|SDKM|\) enables Enterprise customers to collect metrics from |AWS| SDKs on their hosts and clients shared with +|AWS| Enterprise Support. |SDKM| provides information that helps speed up detection and diagnosis of issues occurring in connections +to AWS services for AWS Enterprise Support customers. + +As telemetry is collected on each host, it is relayed via UDP to 127.0.0.1 (aka localhost), where the |CW| agent aggregates the data and sends it +to the |SDKM| service. Therefore, to receive metrics, the |CW| agent is required to be added to your instance. + +The following steps to set up |SDKM| pertain to an |EC2| instance running Amazon Linux for a client application that is using the |sdk|. +|SDKM| is also available for your production environments if you enable it while configuring the |sdk|. + +To utilize |SDKM|, run the latest version of the |CW| agent. Learn how to +:CW-dg:`Configure the CloudWatch Agent for SDK Metrics` in the |CW-dg|. + +To set up |SDKM| with the |sdk|, follow these instructions: + +#. Create an application with an |sdk| client to use an AWS service. +#. Host your project on an |EC2| instance or in your local environment. +#. Install and use the latest 1.x version of the |sdk|. +#. Install and configure an |CW| agent on an EC2 instance or in your local environment. +#. Authorize |SDKM| to collect and send metrics. +#. :ref:`csm-enable-agent`. + +For more information, see the following: + +* :ref:`csm-update-agent` +* :ref:`csm-disable-agent` + + +.. _csm-enable-agent: + +Enable |SDKM| for the |sdk| +=========================== + +By default, |SDKM| is turned off, and the port is set to 31000. The following are the default parameters. + +.. code-block:: ini + + //default values + [ + 'enabled' => false, + 'port' => 31000, + ] + +Enabling |SDKM| is independent of configuring your credentials to use an AWS service. + +You can enable |SDKM| using one of 4 options. + +* :ref:`csm-enable-agent-environ` +* :ref:`csm-enable-agent-code` +* :ref:`csm-enable-agent-java-prop` +* :ref:`csm-enable-agent-shared-config` + +.. _csm-enable-agent-environ: + +Option 1: Set Environment Variables +----------------------------------- + +If :code:`AWS_CSM_ENABLED` is not set, the SDK first checks the profile specified in +the environment variable under :code:`AWS_PROFILE` to determine if |SDKM| is enabled. +By default this is set to ``false``. + +To turn on |SDKM|, add the following to your environmental variables. + +.. code-block:: ini + + export AWS_CSM_ENABLED=true + +:ref:`Other configuration settings` are available. + +Note: Enabling |SDKM| does not configure your credentials to use an AWS service. + +.. _csm-enable-agent-code: + +Option 2: Set |SDKM| in Code +---------------------------- + +The |language| implementation allows you to set |SDKM| configurations within code when building +a service client. +The values set in code override any configurations set in the other options described below. + +.. code-block:: java + + CsmConfiguration csmConfig = new CsmConfiguration(true, MY_PORT, MY_CLIENT_ID); + AmazonDynamoDB dynamodb = AmazonDynamoDBClientBuilder.standard() + .withClientSideMonitoringConfigurationProvider(new StaticCsmConfigurationProvider(csmConfig)) + .build(); + +.. _csm-enable-agent-java-prop: + +Option 3: Set Java System Property +---------------------------------- + +If no |SDKM| configuration is found in the environment variables, +the SDK looks at certain Java system properties. + +To turn on |SDKM|, pass the following system property flag when you execute your application. + +.. code-block:: ini + + -Dcom.amazonaws.sdk.csm.enabled="true" + +You can also set the value programmatically using the Properties object. + +.. code-block:: java + + Properties props = System.getProperties(); + props.setProperty("com.amazonaws.sdk.csm.enabled", "true"); + +:ref:`Other configuration settings` are available. + +Note: Enabling |SDKM| does not configure your credentials to use an AWS service. + +.. _csm-enable-agent-shared-config: + +Option 4: AWS Shared Config File +-------------------------------- + +If no |SDKM| configuration is found in the environment variables or the Java system properties, +the SDK looks for your default AWS profile field. If :code:`AWS_DEFAULT_PROFILE` is set to +something other than default, update that profile. +To enable |SDKM|, add :code:`csm_enabled` to the shared config file located at :file:`~/.aws/config`. + +.. code-block:: ini + + [default] + csm_enabled = true + + [profile aws_csm] + csm_enabled = true + +:ref:`Other configuration settings` are available. + +Note: Enabling |SDKM| is independent from configuring your credentials to use an AWS service. You can use a different profile to authenticate. + +.. _csm-update-agent: + +Update a |CW| Agent +=================== + +To make changes to the port, you need to set the values and then restart any AWS jobs that are currently active. + +Option 1: Set Environment Variables +----------------------------------- + +Most services use +the default port. But if your service requires a unique port ID, add `AWS_CSM_PORT=[port_number]`, to the host's environment variables. + +.. code-block:: shell + + export AWS_CSM_ENABLED=true + export AWS_CSM_PORT=1234 + +Option 2: Set Java System Property +----------------------------------- + +Most services use the default port. +But if your service requires a unique port ID, specify the `-Dcom.amazonaws.sdk.csm.port=[port_number]` +system properties flag when executing your application. + +.. code-block:: ini + + com.amazonaws.sdk.csm.enabled=true + com.amazonaws.sdk.csm.port=1234 + +Option 3: AWS Shared Config File +----------------------------------- + +Most services use the default port. But if your service requires a +unique port ID, add `csm_port = [port_number]` to `~/.aws/config`. + +.. code-block:: ini + + [default] + csm_enabled = false + csm_port = 1234 + + [profile aws_csm] + csm_enabled = false + csm_port = 1234 + +Restart |SDKM| +-------------- + +To restart a job, run the following commands. + +.. code-block:: shell + + amazon-cloudwatch-agent-ctl –a stop; + amazon-cloudwatch-agent-ctl –a start; + + +.. _csm-disable-agent: + +Disable |SDKM| +============== + +To turn off |SDKM|, set `csm_enabled` to `false` in your environment variables, or in your AWS Shared config file located at :file:`~/.aws/config`. +Then restart your |CW| agent so that the changes can take effect. + +**Environment Variables** + +.. code-block:: shell + + export AWS_CSM_ENABLED=false + + +**AWS Shared Config File** + +Remove `csm_enabled` from the profiles in your AWS Shared config file located at :file:`~/.aws/config`. + +.. note:: Environment variables override the AWS Shared config file. If |SDKM| is enabled in the environment variables, the |SDKM| remain enabled. + +.. code-block:: ini + + [default] + csm_enabled = false + + [profile aws_csm] + csm_enabled = false + +To disable |SDKM|, use the following command to stop |CW| agent. + +.. code-block:: shell + + sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a stop && + echo "Done" + +If you are using other |CW| features, restart the |CW| agent with the following command. + +.. code-block:: shell + + amazon-cloudwatch-agent-ctl –a start; + + +Restart |SDKM| +-------------- + +To restart a |SDKM|, run the following commands. + +.. code-block:: shell + + amazon-cloudwatch-agent-ctl –a stop; + amazon-cloudwatch-agent-ctl –a start; + + +Definitions for |SDKM| +====================== + +You can use the following descriptions of |SDKM| to interpret your results. In general, these metrics are available for review +with your Technical Account Manager during regular business reviews. AWS Support resources and your Technical Account Manager +should have access to SDK Metrics data to help you resolve cases, but if you discover data that is confusing or unexpected, but +doesn’t seem to be negatively impacting your applications’ performance, it is best to review that data during scheduled +business reviews. + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - CallCount + + * - Definition + - Total number of successful or failed API calls from your code to AWS services + + * - How to use it + - Use it as a baseline to correlate with other metrics like errors or throttling. + + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - ClientErrorCount + + * - Definition + - Number of API calls that fail with client errors (4xx HTTP response codes). *Examples: Throttling, Access denied, S3 bucket does not exist, and Invalid parameter value.* + + * - How to use it + - Except in certain cases related to throttling (ex. when throttling occurs due to a limit that needs to be increased) this metric can indicate something in your application that needs to be fixed. + + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - ConnectionErrorCount + + * - Definition + - Number of API calls that fail because of errors connecting to the service. These can be caused by network issues between the customer application and AWS services including load balancers, DNS failures, transit providers. In some cases, AWS issues may result in this error. + + * - How to use it + - Use this metric to determine whether issues are specific to your application or are caused by your infrastructure and/or network. High ConnectionErrorCount could also indicate short timeout values for API calls. + + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - ThrottleCount + + * - Definition + - Number of API calls that fail due to throttling by AWS services. + + * - How to use it + - Use this metric to assess if your application has reached throttle limits, as well as to determine the cause of retries and application latency. Consider distributing calls over a window instead of batching your calls. + + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - ServerErrorCount + + * - Definition + - Number of API calls that fail due to server errors (5xx HTTP response codes) from AWS Services. These are typically caused by AWS services. + + * - How to use it + - Determine cause of SDK retries or latency. This metric will not always indicate that AWS services are at fault, as some AWS teams classify latency as an HTTP 503 response. + +.. list-table:: + :widths: 1 2 + :header-rows: 1 + + * - Metric: + - EndToEndLatency + + * - Definition + - Total time for your application to make a call using the AWS SDK, inclusive of retries. In other words, regardless of whether it is successful after several attempts, or as soon as a call fails due to an unretriable error. + + * - How to use it + - Determine how AWS API calls contribute to your application’s overall latency. Higher than expected latency may be caused by issues with network, firewall, or other configuration settings, or by latency that occurs as a result of SDK retries. diff --git a/doc_source/section-client-configuration.rst b/doc_source/section-client-configuration.rst index 90e167b..70fc1e8 100644 --- a/doc_source/section-client-configuration.rst +++ b/doc_source/section-client-configuration.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,79 +8,72 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -############################### -Client Networking Configuration -############################### +###################### +Client Configuration +###################### -The |sdk-java| allows you to change the default client configuration, which is helpful when you want -to: +.. meta:: + :description: How to change proxy configuration, HTTP transport configuration, and TCP socket + buffer size hints by using the AWS SDK for Java. + +The |sdk-java| enables you to change the default client configuration, which is helpful when you +want to: * Connect to the Internet through proxy -* Change HTTP transport settings, such as connection timeout and request retries. +* Change HTTP transport settings, such as connection timeout and request retries * Specify TCP socket buffer size hints Proxy Configuration =================== -When constructing a client object, you can pass in an optional :java-api:`ClientConfiguration` +When constructing a client object, you can pass in an optional :aws-java-class:`ClientConfiguration` object to customize the client's configuration. -If you connect to the internet through a proxy server, you'll need to configure your proxy server -settings (proxy host, port and username/password) through the :classname:`ClientConfiguration` +If you connect to the Internet through a proxy server, you'll need to configure your proxy server +settings (proxy host, port, and username/password) through the :classname:`ClientConfiguration` object. HTTP Transport Configuration ============================ -You can configure several HTTP transport options by using the :java-api:`ClientConfiguration` -object. New options are occasionally added; to see the full list of options that can be retrieved or -set, see the |sdk-java| reference. - -Each of the configurable values has a default value defined by a constant. For a list of the -constant values for :classname:`ClientConfiguration`, see :java-ref:`Constant Field Values -` in the :title:`AWS SDK for Java Reference`. - -.. contents:: - :depth: 1 - :local: - -Local Address -------------- +You can configure several HTTP transport options by using the :aws-java-class:`ClientConfiguration` +object. New options are occasionally added; to see the full list of options you can retrieve or set, +see the |sdk-java-ref|. -To set the local address that the HTTP client will bind to, use :java-ref-nf:`ClientConfiguration.setLocalAddress -`. +.. note:: + Each of the configurable values has a default value defined by a constant. For a list of the + constant values for :classname:`ClientConfiguration`, see :sdk-java-ref:`Constant Field Values + ` in the |sdk-java-ref|. Maximum Connections ------------------- You can set the maximum allowed number of open HTTP connections by using the -:java-ref-nf:`ClientConfiguration.setMaxConnections ` -method. - +:aws-java-ref:`ClientConfiguration.setMaxConnections +` method. -Proxy Options -------------- - -If you use a proxy with your HTTP connections, you may need to set certain options related to HTTP -proxies: +.. important:: + Set the maximum connections to the number of concurrent transactions to avoid + connection contentions and poor performance. For the default maximum connections value, + see :sdk-java-ref:`Constant Field Values ` in the |sdk-java-ref|. Timeouts and Error Handling --------------------------- -You can set options related to timeouts and handling errors with HTTP connections: +You can set options related to timeouts and handling errors with HTTP connections. * :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,000ms. + to establish a connection before giving up. The default is 10,000 ms. - To set this value yourself, use the :java-ref-nf:`ClientConfiguration.setConnectionTimeout - ` method. + To set this value yourself, use the :aws-java-ref:`ClientConfiguration.setConnectionTimeout + ` method. * :strong:`Connection Time to Live (TTL)` @@ -90,43 +83,48 @@ You can set options related to timeouts and handling errors with HTTP connection ensure that even if you have a connection established to a server that is experiencing issues, you'll reestablish a connection to a new server within 15 minutes. - To set the HTTP connection TTL, use the :java-ref-nf:`ClientConfiguration.setConnectionTTL - ` method. + To set the HTTP connection TTL, use the :aws-java-ref:`ClientConfiguration.setConnectionTTL + ` method. * :strong:`Maximum Error Retries` - You can set the maximum retry count for retriable errors by using the - :java-ref-nf:`ClientConfiguration.setMaxErrorRetry - ` method. + The default maximum retry count for retriable errors is 3. You can set a different value + by using the :aws-java-ref:`ClientConfiguration.setMaxErrorRetry + ` method. -TCP Socket Buffer Size Hints -============================ +Local Address +------------- + +To set the local address that the HTTP client will bind to, use +:aws-java-ref:`ClientConfiguration.setLocalAddress +`. -Advanced users who want to tune low-level TCP parameters can additionally set TCP buffer size hints -through the :java-api:`ClientConfiguration` object. The majority of users will never need to tweak -these values, but they are provided for advanced users. -Optimal TCP buffer sizes for an application are highly dependent on network and OS configuration and -capabilities. For example, most modern operating systems provide auto-tuning logic for TCP buffer -sizes, which can have a big impact on performance for TCP connections that are held open long enough -for the auto-tuning to optimize buffer sizes. -Large buffer sizes (e.g., 2 MB) allow the OS to buffer more data in memory without requiring the -remote server to acknowledge receipt of that information, so can be particularly useful when the -network has high latency. -This is only a hint, and the OS may choose not to honor it. When using this option, users should -always check the operating system's configured limits and defaults. Most OS's have a maximum TCP -buffer size limit configured, and won't let you go beyond that limit unless you explicitly raise the -max TCP buffer size limit. +TCP Socket Buffer Size Hints +============================ + +Advanced users who want to tune low-level TCP parameters can additionally set TCP buffer size hints +through the :aws-java-class:`ClientConfiguration` object. The majority of users will never need to +tweak these values, but they are provided for advanced users. -Many resources available to help with configuring TCP buffer sizes and operating system specific TCP -settings, including: +Optimal TCP buffer sizes for an application are highly dependent on network and operating system +configuration and capabilities. For example, most modern operating systems provide auto-tuning logic +for TCP buffer sizes.This can have a big impact on performance for TCP connections that are held +open long enough for the auto-tuning to optimize buffer sizes. -* `TCP Tuning and Network Troubleshooting - `_ +Large buffer sizes (e.g., 2 MB) allow the operating system to buffer more data in memory without +requiring the remote server to acknowledge receipt of that information, and so can be particularly +useful when the network has high latency. -* `Host Tuning `_ +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. +Many resources are available to help with configuring TCP buffer sizes and operating system-specific +TCP settings, including the following: +* `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 4e9f2fe..7042377 100644 --- a/doc_source/setup-credentials.rst +++ b/doc_source/setup-credentials.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,9 +8,15 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -###################################### -Set up AWS Credentials for Development -###################################### +################################################# +Set up AWS Credentials and Region for Development +################################################# + +.. meta:: + :description: Set up default AWS credentials and region for development with the AWS SDK for + Java. + :keywords: AWS region, AWS credentials, setup, shared credentials file, shared config file, + environment variable To connect to any of the supported services with the |sdk-java|, you must provide AWS credentials. The AWS SDKs and CLIs use :emphasis:`provider chains` to look for AWS credentials in a number of @@ -26,10 +32,15 @@ or if you're using the Eclipse IDE for development, refer to the following topic * Set up AWS credentials within Eclipse using the |tke|_. See :tke-ug:`Set up AWS Credentials ` in the |tke-ug|_ for more information. +.. _setup-credentials-setting: + +Setting AWS Credentials +======================= + Setting your credentials for use by the |sdk-java| can be done in a number of ways, but here are the recommended approaches: -.. the following file is in the shared content... +.. The following file is in the shared content at https://github.com/awsdocs/aws-doc-shared-content .. include:: common/sdk-shared-credentials.txt @@ -37,3 +48,53 @@ Once you have set your AWS credentials using one of these methods, they will be by the |sdk-java| by using the default credential provider chain. For further information about working with AWS credentials in your Java applications, see :doc:`credentials`. + +.. _refresh-credentials: +Refreshing IMDS credentials +=========================== + +The |sdk-java| supports opt-in refreshing IMDS credentials in the background every 1 minute, regardless of the credential expiration time. +This allows you to refresh credentials more frequently and reduces the chance that not reaching IMDS impacts +the perceived AWS availability. + +.. code-block:: java + :linenos: + + 1. // Refresh credentials using a background thread, automatically every minute. This will log an error if IMDS is down during + 2. // a refresh, but your service calls will continue using the cached credentials until the credentials are refreshed + 3. // again one minute later. + 4. + 5. InstanceProfileCredentialsProvider credentials = + 6. InstanceProfileCredentialsProvider.createAsyncRefreshingProvider(true); + 7. + 8. AmazonS3Client.builder() + 9. .withCredentials(credentials) + 10. .build(); + 11. + 12. // This is new: When you are done with the credentials provider, you must close it to release the background thread. + 13. credentials.close(); + + +.. _setup-credentials-setting-region: + +Setting the AWS Region +====================== + +You should set a default AWS Region that will be used for accessing AWS services with the AWS SDK +for Java. For the best network performance, choose a region that's geographically close +to you (or to your customers). For a list of regions for each service, see |regions-and-endpoints|_ +in the |AWS-gr|. + +.. note:: If you *don't* select a region, then |region-api-default| will be used by default. + +You can use similar techniques to setting credentials to set your default AWS region: + +.. 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 d28d71b..2541b0c 100644 --- a/doc_source/setup-install.rst +++ b/doc_source/setup-install.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -12,22 +12,21 @@ Set up the |sdk-java| ##################### -.. contents:: - :local: - :depth: 1 +Describes how to use the |sdk-java| in your project. Prerequisites ============= To use the |sdk-java|, you must have: -* a suitable :ref:`Java Development Environment`. +* a suitable :ref:`Java Development Environment `. * An AWS account and access keys. For instructions, see :doc:`signup-create-iam-user`. * AWS credentials (access keys) set in your environment or using the shared (by the AWS CLI and other SDKs) credentials file. For more information, see :doc:`setup-credentials`. + .. _include-sdk: Including the SDK in your project @@ -48,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: @@ -62,23 +62,23 @@ provides you with the latest support for all AWS services. .. note:: For information about how to download and build previous versions of the SDK, see :ref:`install-prev-sdk`. -**To download and extract the latest version of the SDK** +.. topic:: To download and extract the latest version of the SDK -#. Download the SDK from |sdk-java-dl|. + #. Download the SDK from |sdk-java-dl|. -#. After downloading the SDK, extract the contents into a local directory. + #. After downloading the SDK, extract the contents into a local directory. - The SDK contains the following directories: +The SDK contains the following directories: - - **documentation** |ndash| contains the API documentation (also available on the web: - |sdk-java-ref|_). +* :file:`documentation` |ndash| contains the API documentation (also available on the web: + |sdk-java-ref|_). - - **lib** |ndash| contains the SDK :file:`.jar` files. +* :file:`lib` |ndash| contains the SDK :file:`.jar` files. - - **samples** |ndash| contains working sample code that demonstrates how to use the SDK. +* :file:`samples` |ndash| contains working sample code that demonstrates how to use the SDK. - - **third-party** |ndash| contains third-party libraries that are used by the SDK, such as - Apache commons logging, AspectJ and the Spring framework. +* :file:`third-party/lib` |ndash| contains third-party libraries that are used by the SDK, such as + Apache commons logging, AspectJ and the Spring framework. To use the SDK, add the full path to the ``lib`` and ``third-party`` directories to the dependencies in your build file, and add them to your java ``CLASSPATH`` to run your code. @@ -93,31 +93,31 @@ version of the SDK using Apache Maven (open source). Maven will download all nec build and install the SDK in one step. Visit http://maven.apache.org/ for installation instructions and more information. -**To install a previous version of the SDK** +.. topic:: To install a previous version of the SDK -#. Go to the SDK's GitHub page at: |sdk-java-github|_. + #. Go to the SDK's GitHub page at: |sdk-java-github|_. -#. Choose the tag corresponding to the version number of the SDK that you want. For example, - ``1.6.10``. + #. Choose the tag corresponding to the version number of the SDK that you want. For example, + ``1.6.10``. -#. Click the :guilabel:`Download ZIP` button to download the version of the SDK you selected. + #. Click the :guilabel:`Download ZIP` button to download the version of the SDK you selected. -#. Unzip the file to a directory on your development system. On many systems, you can use your - graphical file manager to do this, or use the ``unzip`` utility in a terminal window. + #. Unzip the file to a directory on your development system. On many systems, you can use your + graphical file manager to do this, or use the ``unzip`` utility in a terminal window. -#. In a terminal window, navigate to the directory where you unzipped the SDK source. + #. In a terminal window, navigate to the directory where you unzipped the SDK source. -#. Build and install the SDK with the following command (Maven_ required):: + #. Build and install the SDK with the following command (Maven_ required):: - mvn clean install + mvn clean install - The resulting :file:`.jar` file is built into the :file:`target` directory. + The resulting :file:`.jar` file is built into the :file:`target` directory. -#. (Optional) Build the API Reference documentation using the following command:: + #. (Optional) Build the API Reference documentation using the following command:: - mvn javadoc:javadoc + mvn javadoc:javadoc - The documentation is built into the :file:`target/site/apidocs/` directory. + The documentation is built into the :file:`target/site/apidocs/` directory. .. _java-dg-java-env: @@ -126,7 +126,7 @@ Installing a Java Development Environment ========================================= The |sdk-java| requires J2SE Development Kit *6.0 or later*. You can download the latest Java -software from http://developers.sun.com/downloads/. +software from http://www.oracle.com/technetwork/java/javase/downloads/. .. important:: Java version 1.6 (JS2E 6.0) did not have built-in support for SHA256-signed SSL certificates, which are required for all HTTPS connections with AWS after September 30, 2015. @@ -143,4 +143,3 @@ mode, even if you specify the ``-Client`` option at run time. Using the 32-bit version of the JVM with the ``-Server`` option at run time should provide comparable performance to the 64-bit JVM. - diff --git a/doc_source/setup-project-gradle.rst b/doc_source/setup-project-gradle.rst index 3d68afb..a6d4dd6 100644 --- a/doc_source/setup-project-gradle.rst +++ b/doc_source/setup-project-gradle.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 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,43 +12,163 @@ 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. -**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 -1. Add the dependency management plugin to your :file:`build.gradle` file:: - buildscript { - repositories { - mavenCentral() - } - dependencies { - classpath "io.spring.gradle:dependency-management-plugin:0.5.4.RELEASE" - } - } +To manage SDK dependencies for your Gradle_ project, import the Maven BOM for the |sdk-java| into the :file:`build.gradle` file. - apply plugin: "io.spring.dependency-management" +.. 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 `_. -2. Add the BOM to the *dependencyManagement* section of the file:: - dependencyManagement { - imports { - mavenBom 'com.amazonaws:aws-java-sdk-bom:1.10.47' - } - } +Project setup for Gradle 4.6 or higher +====================================== -3. Specify the SDK modules that you'll be using in the *dependencies* section:: +`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. - 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. +.. topic:: To configure the |sdk-java| for Gradle 4.6 or later -.. note:: For more detail about specifying SDK dependencies using the BOM, see - :doc:`setup-project-maven`. + #. 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 + + buildscript { + repositories { + mavenCentral() + } + dependencies { + 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. + + .. code-block:: groovy + + dependencyManagement { + imports { + mavenBom 'com.amazonaws:aws-java-sdk-bom:1.11.X' + } + } + + #. 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' + } + +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' + + apply plugin: 'java' + + sourceCompatibility = 1.8 + + repositories { + mavenCentral() + } + + buildscript { + repositories { + mavenCentral() + } + dependencies { + classpath "io.spring.gradle:dependency-management-plugin:1.0.9.RELEASE" + } + } + + apply plugin: "io.spring.dependency-management" + + dependencyManagement { + imports { + mavenBom 'com.amazonaws:aws-java-sdk-bom:1.11.X' + } + } + + dependencies { + compile '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 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 8a8523e..8fadd1d 100644 --- a/doc_source/setup-project-maven.rst +++ b/doc_source/setup-project-maven.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -17,9 +17,6 @@ You can use |mvnlong|_ to configure and build |sdk-java| projects, or to build t .. note:: You must have Maven installed to use the guidance in this topic. If it isn't already installed, visit http://maven.apache.org/ to download and install it. -.. contents:: - :local: - :depth: 1 Create a new Maven package ========================== @@ -33,7 +30,7 @@ To create a basic Maven package, open a terminal (command-line) window and run: -DgroupId=org.example.basicapp \ -DartifactId=myapp -Replace *com.example.basicapp* with the full package namespace of your application, and *myapp* with +Replace *org.example.basicapp* with the full package namespace of your application, and *myapp* with the name of your project (this will become the name of the directory for your project). By default, |mvn| creates a project template for you using the `quickstart @@ -62,7 +59,7 @@ Configure the SDK as a Maven dependency ======================================= To use the |sdk-java| in your project, you'll need to declare it as a dependency in your project's -:filename:`pom.xml` file. Beginning with version 1.9.0, you can import :ref:`individual components +:file:`pom.xml` file. Beginning with version 1.9.0, you can import :ref:`individual components ` or the :ref:`entire SDK `. .. _configuring-maven-individual-components: @@ -85,13 +82,18 @@ SDK you want to use: com.amazonaws aws-java-sdk-bom - 1.11.22 + 1.11.327 pom import +To view the latest version of the |sdk-java| BOM that is available on Maven Central, visit: +https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom. You can also use this page to see +which modules (dependencies) are managed by the BOM that you can include within the +:code-xml:`` section of your project's :file:`pom.xml` file. + You can now select individual modules from the SDK that you use in your application. Because you already declared the SDK version in the BOM, you don't need to specify the version number for each component. @@ -109,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: @@ -124,7 +128,7 @@ declare it in your :file:`pom.xml` like this: com.amazonaws aws-java-sdk - 1.11.22 + 1.11.327 @@ -149,4 +153,3 @@ GitHub `_, unpack it locally, and then exec Maven command:: mvn clean install - diff --git a/doc_source/signup-create-iam-user.rst b/doc_source/signup-create-iam-user.rst index 0f3f052..1a1e207 100644 --- a/doc_source/signup-create-iam-user.rst +++ b/doc_source/signup-create-iam-user.rst @@ -1,4 +1,4 @@ -.. Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (the "License"). You may not use this file except in compliance with the @@ -8,6 +8,9 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. +.. includes that start with 'common/' come from the awsdocs shared content, at + https://github.com/awsdocs/aws-doc-shared-content + ###################################### Sign Up for AWS and Create an IAM User ###################################### @@ -20,40 +23,14 @@ access credentials instead of using your root account credentials. see :iam-ug:`Overview of Identity Management: Users ` in the |IAM-ug|. -**To sign up for AWS** - -1. Open http://aws.amazon.com/ and click :guilabel:`Sign Up`. - -2. Follow the on-screen instructions. Part of the sign-up procedure involves receiving a phone call - and entering a PIN using your phone keypad. +.. include:: common/procedure-sign-up-for-aws.txt Next, create an IAM user and download (or copy) its secret access key. -**To create an IAM user** - -#. Go to the :console:`IAM console ` (you may need to sign in to AWS first). - -#. Click :guilabel:`Users` in the sidebar to view your IAM users. - -#. If you don't have any IAM users set up, click :guilabel:`Create New Users` to create one. - -#. Select the IAM user in the list that you'll use to access AWS. - -#. Open the :guilabel:`Security Credentials` tab, and click :guilabel:`Create Access Key`. - - .. note:: You can have a maximum of two active access keys for any given IAM user. If your IAM - user has two access keys already, then you'll need to delete one of them before creating a - new key. - -#. On the resulting dialog, click the :guilabel:`Download Credentials` button to download the - credential file to your computer, or click :guilabel:`Show User Security Credentials` to view - the IAM user's access key ID and secret access key (which you can copy and paste). - - .. important:: There is no way to obtain the secret access key once you close the dialog. You - can, however, delete its associated access key ID and create a new one. +.. include:: common/procedure-create-iam-user.txt -Next, you should :doc:`set your credentials ` in the AWS shared credentials file or in -the environment. +Next, you should :doc:`set your credentials ` in the AWS shared credentials file +or in the environment. .. tip:: If you use the Eclipse IDE, you should consider installing the |tke|_ and providing your credentials as described in :tke-ug:`Set up AWS Credentials ` in the |tke-ug|. diff --git a/doc_source/snippets/CreateSwfDomain-list_swf_domains.java b/doc_source/snippets/CreateSwfDomain-list_swf_domains.java index c4a54dc..cbd7ed7 100644 --- a/doc_source/snippets/CreateSwfDomain-list_swf_domains.java +++ b/doc_source/snippets/CreateSwfDomain-list_swf_domains.java @@ -1,5 +1,5 @@ /* - Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. + Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This file is licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of diff --git a/doc_source/snippets/CreateSwfDomain-register_swf_domain.java b/doc_source/snippets/CreateSwfDomain-register_swf_domain.java index 322f420..aacc2cf 100644 --- a/doc_source/snippets/CreateSwfDomain-register_swf_domain.java +++ b/doc_source/snippets/CreateSwfDomain-register_swf_domain.java @@ -1,5 +1,5 @@ /* - Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. + Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This file is licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of diff --git a/doc_source/snippets/CreateSwfDomain/CreateSwfDomain.java b/doc_source/snippets/CreateSwfDomain/CreateSwfDomain.java index 5688ac7..191e643 100644 --- a/doc_source/snippets/CreateSwfDomain/CreateSwfDomain.java +++ b/doc_source/snippets/CreateSwfDomain/CreateSwfDomain.java @@ -1,5 +1,5 @@ /* - Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. + Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. This file is licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of diff --git a/doc_source/snippets/CreateSwfDomain/build.xml b/doc_source/snippets/CreateSwfDomain/build.xml index a45ae60..bef385a 100644 --- a/doc_source/snippets/CreateSwfDomain/build.xml +++ b/doc_source/snippets/CreateSwfDomain/build.xml @@ -1,5 +1,5 @@