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

[[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

We recommend you to choose an example from our https://github.com/apache/camel-quarkus/tree/master/examples[source tree]
as a base for your real world project.

=== Prerequisites

* 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.

=== Step by step with the `rest-json` example

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 `rest-json` example out of the Camel Quarkus source tree.
+
[source,shell]
----
cd ..
cp -r camel-quarkus/examples/rest-json .
cd rest-json
----

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-platform-http</artifactId>
</dependency>
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-jackson</artifactId>
</dependency>
----

They are managed in `camel-quarkus-bom` that we use as the Maven parent. `camel-quarkus-bom` and its ancestors also
manage plugins necessary for a typical Camel Quarkus application. In case you cannot use `camel-quarkus-bom` as a
parent of your application, make sure that you add those plugins manually.

There are only three classes in the application: `Routes` defining the Camel routes and a couple of entity classes
(`Fruit` and `Legume`).

`src/main/resources/application.properties` configure the application. E.g. the `camel.context.name` is set there.

There are two test classes there: `RestJsonTest` is for the JVM mode while `RestJsonIT` 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 15 seconds.

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
----

This takes about 2.5 minutes (once you have all dependencies cached).

=== 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 238K Oct 11 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.23.2 started in 1.163s. Listening on: http://[::]:8080
----

Notice the boot time around 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
ls -lh target
...
-rwxr-xr-x. 1 ppalaga ppalaga  46M Oct 11 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.23.2 started in 0.013s. 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
34916 ./target/my-app-0.0.1-SNAPSHOT-runner
----

That's under 35 MB of RAM!