Document the amazon-lambda-http extension ...

docs/src/main/asciidoc/amazon-lambda-http-guide.adoc

@@ -20,7 +20,7 @@ To complete this guide, you need:
 * JDK 1.8 (Azure requires JDK 1.8)
 * Apache Maven 3.5.3+
 * https://aws.amazon.com[An Amazon AWS account]
-* https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-reference.html#serverless-sam-cli[Amazon SAM CLI]
+* https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-reference.html#serverless-sam-CLI[Amazon SAM CLI]
 
 == Getting Started
 
@@ -35,4 +35,110 @@ Quarkus project, you'll need to configure your application for deployment to Ama
 the scope of this document but you can find the full guide on
 https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html[Amazon's website].
 
-For the purposes of this guide, we'll be using RESTEasy and maven.
+For the purposes of this guide, we'll be using RESTEasy and maven.  In order to deploy your REST application on AWS,
+you'll need to add two dependencies:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-amazon-lambda-http</artifactId>
+</dependency>
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-resteasy</artifactId>
+</dependency>
+----
+
+NOTE: This example assumes the project is configured to use the BOM provided by the Quarkus project.
+
+Assuming you have properly configured your project to use Quarkus, this is almost all that is necessary.  Now dev mode is available
+as one would expect with a Quarkus application but, additionally, you can use
+https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-CLI-command-reference-sam-local-start-api.html[SAM local]
+if you are more comfortable with that approach.
+
+=== Existing Projects
+
+For existing projects, the following dependency will need to be added:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-amazon-lambda-http</artifactId>
+</dependency>
+----
+
+It's likely there is already an HTTP dependency defined to serve your application.  If not, however, the following
+dependency can also be added:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-resteasy</artifactId>
+</dependency>
+----
+
+Assuming the application is already configured with a YAML template for the SAM CLI to use, you should be almost ready
+to begin using Quarkus.  One step remains, however.  Your template file should look something like
+https://github.com/awslabs/serverless-application-model/blob/master/examples/apps/hello-world/template.yaml[this].
+
+=== Updating the SAM template file
+
+In an existing AWS project, there will likely already be a YAML file for the SAM CLI to use when developing locally and
+deploying.  However others will need an initial template to work with.  To create that initial template, the following
+plugin can be run from the root of the project:
+
+[source,shell]
+----
+mvn io.quarkus:quarkus-amazon-lambda-http-maven:configure-aws-lambda
+----
+
+If there is no existing template file one will be created with the default name of `template.yaml` and the resource name
+will default to `Quarkus`.  These names might not be preferable or there might be an existing template file to work with.
+In this case, there are two properties that can configure these values:
+
+|===
+|Name |Description
+
+|amazon-lambda-http.template| The template file to use
+|amazon-lambda-http.resource| The resource to manage
+|===
+
+NOTE: Running this plugin in an existing project will attempt to update the existing configuration.  If the template
+file has a different name, the plugin will assume there is no configuration and will generate a new file.
+
+This plugin will update the `Handler` and `Runtime` values for the named resource.  Running this plugin once might be
+sufficient.  However, you might choose to always run this plugin to make sure your template file is correct.
+e.g., Should implementation details on the Quarkus side ever change, automatically updating the SAM template would
+help eliminate any breakage due to Quarkus changes.  The pom can be configured to run automatically by adding the
+following to the `plugins` section:
+
+[source,xml]
+----
+<plugin>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-amazon-lambda-http-maven</artifactId>
+    <version>${quarkus.version}</version>
+    <executions>
+        <execution>
+            <id>amazon-lambda-http</id>
+            <goals>
+                <goal>configure-aws-lambda</goal>
+            </goals>
+            <phase>compile</phase>
+        </execution>
+    </executions>
+</plugin>
+----
+
+This will bind the plugin to the `compile` phase and will ensure that the configuration is always up to date.  If this
+option is chosen some extra configuration will be required since always having to pass the properties above is not ideal.
+It is possible to store these values in `src/main/properties/application.properties` alongside all of the other Quarkus
+configuration values.  In this case, you'll need to define the following entries:
+
+*  quarkus.amazon-lambda-http.resource
+*  quarkus.amazon-lambda-http.template
+
+With these defined, the properties no longer need to be passed to maven when building the project.

extensions/amazon-lambda-http/maven/src/main/java/io/quarkus/amazon/lambda/http/AmazonLambdaHttpMojo.java

@@ -21,17 +21,17 @@ public class AmazonLambdaHttpMojo extends AbstractMojo {
     public static final String SAM_HANDLER = HttpHandler.class.getName() + "::handleRequest";
     public static final String SAM_RUNTIME = "java8";
     public static final String SAM_TEMPLATE = "quarkus.amazon-lambda-http.template";
-    public static final String SAM_RESOURCE = "quarkus.amazon-lambda-http.resource-name";
+    public static final String SAM_RESOURCE = "quarkus.amazon-lambda-http.resource";
     public static final String DEFAULT_TEMPLATE = "template.yaml";
     public static final String DEFAULT_RESOURCE = "Quarkus";
 
     @Parameter(defaultValue = "${project}")
     protected MavenProject project;
 
-    @Parameter(property = "sam.template", defaultValue = DEFAULT_TEMPLATE)
+    @Parameter(property = "amazon-lambda-http.template", defaultValue = DEFAULT_TEMPLATE)
     private String templateFile;
 
-    @Parameter(property = "sam.resource", defaultValue = DEFAULT_RESOURCE)
+    @Parameter(property = "amazon-lambda-http.resource", defaultValue = DEFAULT_RESOURCE)
     private String resourceName;
 
     @SuppressWarnings("unchecked")

integration-tests/amazon-lambda-http/src/test/java/io/quarkus/amazon/lambda.http/GenerateAmazonConfigIT.java

@@ -79,10 +79,10 @@ private void invoke(String goal, String template, String resource) throws Except
         mavenProperties.put("projectArtifactId", "acme");
         mavenProperties.put("projectVersion", "1.0-SNAPSHOT");
         if (template != null) {
-            mavenProperties.put("sam.template", template);
+            mavenProperties.put("amazon-lambda-http.template", template);
         }
         if (resource != null) {
-            mavenProperties.put("sam.resource", resource);
+            mavenProperties.put("amazon-lambda-http.resource", resource);
         }
 
         final MavenProcessInvocationResult result = new RunningInvoker(testDir, false)

integration-tests/amazon-lambda-http/src/test/resources/projects/configure-during-lifecycle/src/main/resources/application.properties

@@ -1,2 +1,2 @@
-quarkus.amazon-lambda-http.resource-name=properties-resource
+quarkus.amazon-lambda-http.resource=properties-resource
 quarkus.amazon-lambda-http.template=properties.yaml

integration-tests/amazon-lambda-http/src/test/resources/projects/configure-named-template/src/main/resources/application.properties

@@ -1,2 +1,2 @@
-quarkus.amazon-lambda.sam-template=sam.yaml
-quarkus.amazon-lambda.resource-name=named-template
+quarkus.amazon-lambda-http.template=sam.yaml
+quarkus.amazon-lambda-http.resource=named-template

integration-tests/amazon-lambda-http/src/test/resources/projects/configure-new-template/src/main/resources/application.properties

@@ -1,3 +1,2 @@
-quarkus.amazon-lambda.sam-template=sam.yaml
-quarkus.amazon-lambda.resource-name=new-template
-quarkus.amazon-lambda.update-config=true
+quarkus.amazon-lambda-http.template=sam.yaml
+quarkus.amazon-lambda-http.resource=new-template

integration-tests/amazon-lambda-http/src/test/resources/projects/configure-with-application-properties/src/main/resources/application.properties

@@ -1,2 +1,2 @@
-quarkus.amazon-lambda-http.resource-name=properties-resource
+quarkus.amazon-lambda-http.resource=properties-resource
 quarkus.amazon-lambda-http.template=properties.yaml