docs: Started cleaning up example doc

examples/README.md

@@ -1,4 +1,36 @@
 ## aws-lambda-powertools-examples
 
 This directory holds example projects demoing different components of the Powertools for AWS Lambda (Java).
-Each example can be copied from its subdirectory and used independently of the rest of this repository.
+Each example can be copied from its subdirectory and used independently of the rest of this repository.
+
+### Working with AWS Serverless Application Model (SAM) Examples
+Many of the examples use [AWS Serverless Application Model](https://aws.amazon.com/serverless/sam/) (SAM). To get started
+with them, you can use the SAM Command Line Interface (SAM CLI) to build it and deploy an example to AWS.
+
+To use the SAM CLI, you need the following tools.
+
+* SAM CLI - [Install the SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
+* Java11 - [Install the Java 11](https://docs.aws.amazon.com/corretto/latest/corretto-11-ug/downloads-list.html)
+* Maven - [Install Maven](https://maven.apache.org/install.html)
+* Docker - [Install Docker community edition](https://hub.docker.com/search/?type=edition&offering=community)
+
+To build and deploy an example application for the first time, run the following in your shell:
+
+```bash
+# Switch to the directory containing an example for the powertools-core module
+$ cd powertools-examples-core
+
+# Build and deploy the example
+$ sam build
+$ sam deploy --guided
+```
+
+The first command will build the source of your application. The second command will package and deploy your application to AWS, with a series of prompts:
+
+* **Stack Name**: The name of the stack to deploy to CloudFormation. This should be unique to your account and region, and a good starting point would be something matching your project name.
+* **AWS Region**: The AWS region you want to deploy your app to.
+* **Confirm changes before deploy**: If set to yes, any change sets will be shown to you before execution for manual review. If set to no, the AWS SAM CLI will automatically deploy application changes.
+* **Allow SAM CLI IAM role creation**: Many AWS SAM templates, including this example, create AWS IAM roles required for the AWS Lambda function(s) included to access AWS services. By default, these are scoped down to minimum required permissions. To deploy an AWS CloudFormation stack which creates or modified IAM roles, the `CAPABILITY_IAM` value for `capabilities` must be provided. If permission isn't provided through this prompt, to deploy this example you must explicitly pass `--capabilities CAPABILITY_IAM` to the `sam deploy` command.
+* **Save arguments to samconfig.toml**: If set to yes, your choices will be saved to a configuration file inside the project, so that in the future you can just re-run `sam deploy` without parameters to deploy changes to your application.
+
+You can find your API Gateway Endpoint URL in the output values displayed after deployment.

examples/powertools-examples-core/README.md

@@ -19,31 +19,8 @@ The AWS Toolkit is an open source plug-in for popular IDEs that uses the SAM CLI
 
 ## Deploy the sample application
 
-The Serverless Application Model Command Line Interface (SAM CLI) is an extension of the AWS CLI that adds functionality for building and testing Lambda applications. It uses Docker to run your functions in an Amazon Linux environment that matches Lambda. It can also emulate your application's build environment and API.
-
-To use the SAM CLI, you need the following tools.
-
-* SAM CLI - [Install the SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
-* Java11 - [Install the Java 11](https://docs.aws.amazon.com/corretto/latest/corretto-11-ug/downloads-list.html)
-* Maven - [Install Maven](https://maven.apache.org/install.html)
-* Docker - [Install Docker community edition](https://hub.docker.com/search/?type=edition&offering=community)
-
-To build and deploy your application for the first time, run the following in your shell:
-
-```bash
-Coreutilities$ sam build
-Coreutilities$ sam deploy --guided
-```
-
-The first command will build the source of your application. The second command will package and deploy your application to AWS, with a series of prompts:
-
-* **Stack Name**: The name of the stack to deploy to CloudFormation. This should be unique to your account and region, and a good starting point would be something matching your project name.
-* **AWS Region**: The AWS region you want to deploy your app to.
-* **Confirm changes before deploy**: If set to yes, any change sets will be shown to you before execution for manual review. If set to no, the AWS SAM CLI will automatically deploy application changes.
-* **Allow SAM CLI IAM role creation**: Many AWS SAM templates, including this example, create AWS IAM roles required for the AWS Lambda function(s) included to access AWS services. By default, these are scoped down to minimum required permissions. To deploy an AWS CloudFormation stack which creates or modified IAM roles, the `CAPABILITY_IAM` value for `capabilities` must be provided. If permission isn't provided through this prompt, to deploy this example you must explicitly pass `--capabilities CAPABILITY_IAM` to the `sam deploy` command.
-* **Save arguments to samconfig.toml**: If set to yes, your choices will be saved to a configuration file inside the project, so that in the future you can just re-run `sam deploy` without parameters to deploy changes to your application.
-
-You can find your API Gateway Endpoint URL in the output values displayed after deployment.
+This sample is based on Serverless Application Model (SAM). To deploy it, check out the instructions for getting
+started with SAM in [the examples directory](../README.md)
 
 ## Use the SAM CLI to build and test locally
 

examples/powertools-examples-idempotency/README.md

@@ -1,21 +1,20 @@
 # Idempotency
 
 This project contains an example of Lambda function using the idempotency module of Powertools for AWS Lambda (Java). For more information on this module, please refer to the [documentation](https://docs.powertools.aws.dev/lambda-java/utilities/idempotency/).
+The example exposes a HTTP POST endpoint. When the user sends the address of a webpage to it, the endpoint fetches the contents of the URL and returns them to the user:
 
-## Deploy the sample application
-
-This sample is based on Serverless Application Model (SAM) and you can use the SAM Command Line Interface (SAM CLI) to build it and deploy it to AWS.
+```bash
+ curl -X POST https://[REST-API-ID].execute-api.[REGION].amazonaws.com/Prod/helloidem/ -H "Content-Type: application/json" -d '{"address": "https://checkip.amazonaws.com"}'
+```
 
-To use the SAM CLI, you need the following tools.
+this should return the contents of the webpage, for instance:
+```json
+{ "message": "hello world", "location": "123.123.123.1" }
+```
 
-* SAM CLI - [Install the SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
-* Java11 - [Install the Java 11](https://docs.aws.amazon.com/corretto/latest/corretto-11-ug/downloads-list.html)
-* Maven - [Install Maven](https://maven.apache.org/install.html)
-* Docker - [Install Docker community edition](https://hub.docker.com/search/?type=edition&offering=community)
+Check out [App.java](src/main/java/helloworld/App.java) to see how it works!
 
-To build and deploy your application for the first time, run the following in your shell:
+## Deploy the sample application
 
-```bash
-Coreutilities$ sam build
-Coreutilities$ sam deploy --guided
-```
+This sample is based on Serverless Application Model (SAM). To deploy it, check out the instructions for getting
+started with SAM in [the examples directory](../README.md)

examples/powertools-examples-idempotency/src/main/java/helloworld/App.java

@@ -43,7 +43,11 @@ public App(DynamoDbClient client) {
     }
 
     /**
-     * Try with:
+     * This is our Lambda event handler. It accepts HTTP POST  requests from API gateway and returns the contents of the given URL. Requests are made idempotent
+     * by the idempotency library, and results are cached for the default 1h expiry time.
+     *
+     * You can test the endpoint like this:
+     *
      * <pre>
      *     curl -X POST https://[REST-API-ID].execute-api.[REGION].amazonaws.com/Prod/helloidem/ -H "Content-Type: application/json" -d '{"address": "https://checkip.amazonaws.com"}'
      * </pre>
@@ -52,7 +56,7 @@ public App(DynamoDbClient client) {
      *     <li>Second call (and next ones) will retrieve from the cache (if cache is enabled, which is by default) or from the store, the handler won't be called. Until the expiration happens (by default 1 hour).</li>
      * </ul>
      */
-    @Idempotent // *** THE MAGIC IS HERE ***
+    @Idempotent
     @Logging(logEvent = true)
     public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
         Map<String, String> headers = new HashMap<>();
@@ -65,6 +69,7 @@ public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEv
         APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent()
                 .withHeaders(headers);
         try {
+            // Read the 'address' field from the JSON post body
             String address = JsonConfig.get().getObjectMapper().readTree(input.getBody()).get("address").asText();
             final String pageContents = this.getPageContents(address);
             String output = String.format("{ \"message\": \"hello world\", \"location\": \"%s\" }", pageContents);
@@ -81,8 +86,18 @@ public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEv
         }
     }
 
-    // we could also put the @Idempotent annotation here, but using it on the handler avoids executing the handler (cost reduction).
-    // Use it on other methods to handle multiple items (with SQS batch processing for example)
+
+    /**
+     * Helper to retrieve the contents of the given URL and return them as a string.
+     *
+     * We could also put the @Idempotent annotation here if we only wanted this sub-operation to be idempotent. Putting
+     * it on the handler, however, reduces total execution time and saves us time!
+     *
+     * @param address The URL to fetch
+     * @return The contents of the given URL
+     *
+     * @throws IOException
+     */
     private String getPageContents(String address) throws IOException {
         URL url = new URL(address);
         try (BufferedReader br = new BufferedReader(new InputStreamReader(url.openStream(), "UTF-8"))) {