You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2019/08/10 07:44:04 UTC
[camel-quarkus] branch master updated: User guide
This is an automated email from the ASF dual-hosted git repository.
acosentino pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
The following commit(s) were added to refs/heads/master by this push:
new cb5f0c6 User guide
new 0625d8c Merge pull request #122 from ppalaga/190806-user-guide
cb5f0c6 is described below
commit cb5f0c62ab9c6203e4b05434fe7ba62c2c182aec
Author: Peter Palaga <pp...@redhat.com>
AuthorDate: Fri Aug 9 21:35:53 2019 +0200
User guide
---
build-parent/pom.xml | 8 -
build/scripts/list-camel-quarkus-extensions.groovy | 43 +++++
docs/modules/ROOT/nav.adoc | 2 +
.../ROOT/pages/_partials/common-extensions.adoc | 5 +
.../ROOT/pages/_partials/component-extensions.adoc | 16 ++
docs/modules/ROOT/pages/contributor-guide.adoc | 2 +-
.../pages/list-of-camel-quarkus-extensions.adoc | 10 ++
docs/modules/ROOT/pages/user-guide.adoc | 190 +++++++++++++++++++++
docs/site.yml | 4 +
extensions/pom.xml | 34 ++++
pom.xml | 2 +
11 files changed, 307 insertions(+), 9 deletions(-)
diff --git a/build-parent/pom.xml b/build-parent/pom.xml
index 4da0e1f..290abd5 100644
--- a/build-parent/pom.xml
+++ b/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>
diff --git a/build/scripts/list-camel-quarkus-extensions.groovy b/build/scripts/list-camel-quarkus-extensions.groovy
new file mode 100644
index 0000000..a9a896b
--- /dev/null
+++ b/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)
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index f788cf1..38e758d 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/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]
diff --git a/docs/modules/ROOT/pages/_partials/common-extensions.adoc b/docs/modules/ROOT/pages/_partials/common-extensions.adoc
new file mode 100644
index 0000000..f8015af
--- /dev/null
+++ b/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`
diff --git a/docs/modules/ROOT/pages/_partials/component-extensions.adoc b/docs/modules/ROOT/pages/_partials/component-extensions.adoc
new file mode 100644
index 0000000..026d9ea
--- /dev/null
+++ b/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`
diff --git a/docs/modules/ROOT/pages/contributor-guide.adoc b/docs/modules/ROOT/pages/contributor-guide.adoc
index 745685e..4dac995 100644
--- a/docs/modules/ROOT/pages/contributor-guide.adoc
+++ b/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
diff --git a/docs/modules/ROOT/pages/list-of-camel-quarkus-extensions.adoc b/docs/modules/ROOT/pages/list-of-camel-quarkus-extensions.adoc
new file mode 100644
index 0000000..32876b6
--- /dev/null
+++ b/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[]
diff --git a/docs/modules/ROOT/pages/user-guide.adoc b/docs/modules/ROOT/pages/user-guide.adoc
new file mode 100644
index 0000000..e79c397
--- /dev/null
+++ b/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!
diff --git a/docs/site.yml b/docs/site.yml
index 7d60ad0..694d9d5 100644
--- a/docs/site.yml
+++ b/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
diff --git a/extensions/pom.xml b/extensions/pom.xml
index 0fd7314..07abf7b 100644
--- a/extensions/pom.xml
+++ b/extensions/pom.xml
@@ -73,6 +73,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>
diff --git a/pom.xml b/pom.xml
index 173d981..53e59e9 100644
--- a/pom.xml
+++ b/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>