Merge pull request #122 from ppalaga/190806-user-guide

User guide

build-parent/pom.xml

@@ -33,7 +33,6 @@
 
     <properties>
 
-        <groovy.version>2.5.7</groovy.version>
         <xstream.version>1.4.11</xstream.version>
 
         <!-- maven-surefire-plugin -->
@@ -43,7 +42,6 @@
         <maven-checkstyle.version>7.6.1</maven-checkstyle.version>
         <jandex-maven-plugin.version>1.0.6</jandex-maven-plugin.version>
         <maven-resources-plugin.version>3.1.0</maven-resources-plugin.version>
-        <gmavenplus-plugin.version>1.7.1</gmavenplus-plugin.version>
         <docker-maven-plugin.version>0.3.0</docker-maven-plugin.version>
     </properties>
 
@@ -134,12 +132,6 @@
                             <version>${groovy.version}</version>
                             <scope>runtime</scope>
                         </dependency>
-                        <dependency>
-                            <groupId>org.codehaus.groovy</groupId>
-                            <artifactId>groovy-ant</artifactId>
-                            <version>${groovy.version}</version>
-                            <scope>runtime</scope>
-                        </dependency>
                     </dependencies>
                 </plugin>
             </plugins>

build/scripts/list-camel-quarkus-extensions.groovy

@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License 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.
+ */
+import java.util.stream.Collectors
+
+/* Keep in sync with the current file name */
+@groovy.transform.Field static final String currentScript = "list-camel-quarkus-extensions.groovy";
+final File extensionsPomPath = new File("${project.basedir}/pom.xml")
+final File componentExtensionsAdocPath = new File("${project.basedir}/../docs/modules/ROOT/pages/_partials/component-extensions.adoc")
+final File commonExtensionsAdocPath = new File("${project.basedir}/../docs/modules/ROOT/pages/_partials/common-extensions.adoc")
+
+def parser = new XmlParser()
+def pom = parser.parseText(extensionsPomPath.getText('UTF-8'))
+final Set componentExtensions = new TreeSet()
+final Set commonExtensions = new TreeSet()
+pom.modules.module.each { node ->
+    final String key = node.text().trim()
+    if (key.endsWith("core") || key.endsWith("-common")) {
+        commonExtensions.add(key)
+    } else {
+        componentExtensions.add(key)
+    }
+}
+
+void writeFile(File f, Set<String> keys) {
+    f.setText('// Generated by ' + currentScript +'\n' + keys.stream().map { k -> '* `camel-quarkus-' + k +'`\n' }.collect(Collectors.joining()), 'UTF-8')
+}
+
+writeFile(componentExtensionsAdocPath, componentExtensions)
+writeFile(commonExtensionsAdocPath, commonExtensions)

docs/modules/ROOT/nav.adoc

@@ -1 +1,3 @@
+* xref:user-guide.adoc[User guide]
 * xref:contributor-guide.adoc[Contributor guide]
+* xref:list-of-camel-quarkus-extensions.adoc[List of Camel Quarkus extensions]

docs/modules/ROOT/pages/_partials/common-extensions.adoc

@@ -0,0 +1,5 @@
+// Generated by list-camel-quarkus-extensions.groovy
+* `camel-quarkus-core`
+* `camel-quarkus-jetty-common`
+* `camel-quarkus-xml-common`
+* `camel-quarkus-xstream-common`

docs/modules/ROOT/pages/_partials/component-extensions.adoc

@@ -0,0 +1,16 @@
+// Generated by list-camel-quarkus-extensions.groovy
+* `camel-quarkus-aws-eks`
+* `camel-quarkus-aws-s3`
+* `camel-quarkus-aws-sns`
+* `camel-quarkus-aws-sqs`
+* `camel-quarkus-bean`
+* `camel-quarkus-direct`
+* `camel-quarkus-infinispan`
+* `camel-quarkus-jdbc`
+* `camel-quarkus-log`
+* `camel-quarkus-netty4-http`
+* `camel-quarkus-rest`
+* `camel-quarkus-salesforce`
+* `camel-quarkus-servlet`
+* `camel-quarkus-timer`
+* `camel-quarkus-twitter`

docs/modules/ROOT/pages/contributor-guide.adoc

@@ -7,7 +7,7 @@
 * Git
 * Docker or GraalVM with `native-image` installed for the native mode, see https://quarkus.io/guides/building-native-image-guide[Building a native executable] section of the Quarkus documentation.
 * Java 8
-* Maven 3.5.0+ (unless you use the Maven Wrapper, a.k.a. `mvnw` available in the source tree).
+* Maven 3.5.3+ (unless you use the Maven Wrapper, a.k.a. `mvnw` available in the source tree).
 
 [[how-to-build]]
 == How to build

docs/modules/ROOT/pages/list-of-camel-quarkus-extensions.adoc

@@ -0,0 +1,10 @@
+[list-of-camel-quarkus-extensions]
+= List of Apache Camel extensions for Quarkus
+
+As of Camel Quarkus {camel-quarkus-last-release} the following Camel components are supported on Quarkus:
+
+include::{partialsdir}/component-extensions.adoc[]
+
+In addition to the above extensions there are the following ancillary extensions:
+
+include::{partialsdir}/common-extensions.adoc[]

docs/modules/ROOT/pages/user-guide.adoc

@@ -0,0 +1,190 @@
+[[user-guide]]
+= User guide
+
+This guide is for developers writing Camel applications on top of Quarkus.
+
+WARNING: Camel extensions for Quarkus is a new project and this guide is a work in progress.
+https://github.com/apache/camel-quarkus/issues[Issue reports] and fixes are welcome.
+
+== Which Camel components are supported on Quarkus?
+
+The answer is very easy: those ones that have a Quarkus extension - see the
+xref:list-of-camel-quarkus-extensions.adoc[complete list].
+
+== Your first application
+
+As long as we do not have self-contained examples, we can only offer some of the Camel Quarkus integration tests as a
+replacement. Only a few manual steps are needed to turn e.g. the servlet integration test into a standalone application
+that can further serve as a base for your real world project.
+
+=== Prerequisites
+
+To transform one of our integration tests to a standalone example, you need:
+
+* A `git` client
+* An IDE
+* JDK 1.8+ with JAVA_HOME configured appropriately
+* Apache Maven 3.5.3+
+* Docker or GraalVM with `native-image` installed for the native mode, see
+  https://quarkus.io/guides/building-native-image-guide[Building a native executable] section of the Quarkus
+  documentation.
+
+=== Turn the servlet integration test into a standalone application
+
+1. Clone Camel Quarkus and checkout the latest release tag
++
+[source,shell]
+----
+git clone https://github.com/apache/camel-quarkus.git
+cd camel-quarkus
+# checkout the latest tag
+git checkout $(git describe --abbrev=0)
+----
+
+2. Copy the servlet integration test out of the Camel Quarkus source tree.
++
+[source,shell]
+----
+cd ..
+cp -r camel-quarkus/integration-tests/servlet/ .
+cd servlet
+----
+
+3. Open the `pom.xml` file in your IDE.
++
+Make sure that the parent is `org.apache.camel.quarkus:camel-quarkus-bom` and do the changes as
+sketched below:
++
+[source,xml,subs="attributes+"]
+----
+<project>
+    <parent>
+        <groupId>org.apache.camel.quarkus</groupId>
+        <artifactId>camel-quarkus-bom</artifactId>
+        <version>{camel-quarkus-last-release}</version>
+        <!-- <relativePath>../../bom/pom.xml</relativePath> --><!--1-->
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>org.my-org</groupId><!--2-->
+    <artifactId>my-app</artifactId><!--3-->
+    <version>0.0.1-SNAPSHOT</version><!--4-->
+
+    ...
+
+</project>
+----
+<1> Remove the `<relativePath>` element.
+<2> Add a `groupId` of your choice.
+<3> Change the `artifactId` to whatever you like
+<4> Add the `version`
+
+=== Explore the application code
+
+The application has just two compile dependencies:
+
+[source,xml,subs="attributes+"]
+----
+<dependency>
+    <groupId>org.apache.camel.quarkus</groupId>
+    <artifactId>camel-quarkus-servlet</artifactId>
+</dependency>
+<dependency>
+    <groupId>org.apache.camel.quarkus</groupId>
+    <artifactId>camel-quarkus-rest</artifactId>
+</dependency>
+----
+
+They are managed in `camel-quarkus-bom` that we use as the Maven parent. `camel-quarkus-bom` also manages plugins
+necessary for a typical Camel Quarkus application.
+
+There are only two classes in the application: `CamelRoute` defining the Camel routes and
+`CustomServlet`.
+
+`src/main/resources/application.properties` configure the application. E.g. the `CustomServlet` is set
+there to serve the requests for the path `/my-named-folder/*`.
+
+There are two test classes there: `CamelServletTest` is for the JVM mode while `CamelServletIT` is there for the native
+mode.
+
+The JVM mode tests are run by `maven-surefire-plugin` in the `test` Maven phase:
+
+[source,shell]
+----
+mvn clean test
+----
+
+This should take about half a minute.
+
+The native mode tests are verified by `maven-failsafe-plugin` in the `verify` phase. Pass the `native` property to
+activate the profile that runs them:
+
+[source,shell]
+----
+mvn clean verify -Dnative -Dnative-image.docker-build=true -Dnative-image.xmx=5g
+----
+
+This takes about three minutes.
+
+=== Run the application
+
+==== JVM mode
+
+`mvn package` prepares a thin `jar` for running on a stock JVM:
+
+[source,shell]
+----
+mvn clean package
+ls -lh target
+...
+-rw-r--r--. 1 ppalaga ppalaga 157K Aug  9 18:55  my-app-0.0.1-SNAPSHOT-runner.jar
+...
+----
+
+You can run it as follows:
+
+[source,shell]
+----
+java -jar target/*-runner.jar
+...
+[io.quarkus] (main) Quarkus 0.20.0 started in 0.805s. Listening on: http://[::]:8080
+----
+
+Notice the boot time under a second.
+
+The thin `jar` contains just the application code. To run it, the dependencies in `target/lib` are required too.
+
+==== Native mode
+
+To prepare a native executable using GraalVM, run the following command:
+
+[source,shell]
+----
+mvn clean package -Dnative -Dnative-image.docker-build=true -Dnative-image.xmx=5g
+ls -lh target
+...
+-rwxr-xr-x. 1 ppalaga ppalaga  32M Aug  9 18:57  my-app-0.0.1-SNAPSHOT-runner
+...
+----
+
+Note that the `runner` in the listing above has no `.jar` extension and has the `x` (executable) permission set. Thus
+it can be run directly:
+
+[source,shell]
+----
+./target/*-runner
+...
+[io.quarkus] (main) Quarkus 0.20.0 started in 0.017s. Listening on: http://[::]:8080
+...
+----
+
+Check how fast it started and check how little memory it consumes:
+
+[source,shell]
+----
+ps -o rss,command -p $(pgrep my-app)
+  RSS COMMAND
+21932 ./target/my-app-0.0.1-SNAPSHOT-runner
+----
+
+That's under 22 MB of RAM!

docs/site.yml

@@ -13,3 +13,7 @@ ui:
     snapshot: true
 output:
   dir: ./target/site
+asciidoc:
+  attributes:
+    # Changes from here need to get ported to https://github.com/apache/camel-website/blob/master/site.yml
+    camel-quarkus-last-release: 0.1.0

extensions/pom.xml

@@ -74,6 +74,40 @@
                     <templatesUriBase>file:create-extension-templates</templatesUriBase>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.codehaus.gmavenplus</groupId>
+                <artifactId>gmavenplus-plugin</artifactId>
+                <version>${gmavenplus-plugin.version}</version>
+                <inherited>false</inherited>
+                <executions>
+                    <execution>
+                        <id>list-camel-quarkus-extensions</id>
+                        <goals>
+                            <goal>execute</goal>
+                        </goals>
+                        <phase>validate</phase>
+                        <configuration>
+                            <scripts>
+                                <script>file:///${project.basedir}/../build/scripts/list-camel-quarkus-extensions.groovy</script>
+                            </scripts>
+                        </configuration>
+                    </execution>
+                </executions>
+                <dependencies>
+                    <dependency>
+                        <groupId>org.codehaus.groovy</groupId>
+                        <artifactId>groovy</artifactId>
+                        <version>${groovy.version}</version>
+                        <scope>runtime</scope>
+                    </dependency>
+                    <dependency>
+                        <groupId>org.codehaus.groovy</groupId>
+                        <artifactId>groovy-xml</artifactId>
+                        <version>${groovy.version}</version>
+                        <scope>runtime</scope>
+                    </dependency>
+                </dependencies>
+            </plugin>
         </plugins>
     </build>
 

pom.xml

@@ -54,6 +54,8 @@
         <supported-maven-versions>[3.5.3,)</supported-maven-versions>
 
         <exec-maven-plugin.version>1.6.0</exec-maven-plugin.version>
+        <gmavenplus-plugin.version>1.7.1</gmavenplus-plugin.version>
+        <groovy.version>2.5.7</groovy.version>
         <mycila-license.version>3.0</mycila-license.version>
         <maven-gpg-plugin.version>1.6</maven-gpg-plugin.version>
         <maven-deploy-plugin.version>3.0.0-M1</maven-deploy-plugin.version>