First steps

We recommend you to choose an example from our source tree as a base for your real world project.

Prerequisites

  • A git client

  • An IDE

  • JDK 8+ with JAVA_HOME configured appropriately

  • Apache Maven 3.6.2+

  • GraalVM with native-image command installed and GRAALVM_HOME environment variable set, see Building a native executable section of the Quarkus documentation.

  • If your are on Linux, docker is sufficient for the native mode too. Use -Pnative,docker instead of -Pnative if you choose this option.

Step by step with the rest-json example

  1. Clone Camel Quarkus and checkout the latest release tag

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

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

    <project>
    <parent>
        <groupId>org.apache.camel.quarkus</groupId>
        <artifactId>camel-quarkus-bom</artifactId>(1)
        <version>1.0.0-CR3</version>
        <!-- <relativePath>../../bom/pom.xml</relativePath> -->(2)
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.my-org</groupId>(3)
    <artifactId>my-app</artifactId>(4)
    <version>0.0.1-SNAPSHOT</version>(5)

    ...

</project>
    1 Change the <artifactId> element to camel-quarkus-bom.
    2 Remove the <relativePath> element.
    3 Add a groupId of your choice.
    4 Change the artifactId to whatever you like
    5 Add the version

Explore the application code

The application has just two compile dependencies:

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

Development mode

$ mvn clean compile quarkus:dev

This command compiles the project, starts your application and lets the Quarkus tooling watch for changes in your workspace. Any modifications in your project will automatically take effect in the running application.

Check the application in the browser, e.g. http://localhost:8080/fruits for the rest-json example

Then change something in the code and see the changes applied by refreshing the browser.

Please refer to Quarkus documentation for more details.

Testing

There are two test classes in our example: 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:

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

$ mvn clean verify -Pnative

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

Package and run the application

JVM mode

mvn package prepares a thin jar for running on a stock JVM:

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

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

$ mvn clean package -Pnative
$ 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:

$ ./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:

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

Quarkus Native executable guide contains more details including steps for creating a container image.
Back to top