Quarkus - Building applications with Maven

Creating a new project

With Maven, you can scaffold a new project with:

mvn io.quarkus:quarkus-maven-plugin:1.0.0.CR1:create \
    -DprojectGroupId=my-groupId \
    -DprojectArtifactId=my-artifactId \
    -DprojectVersion=my-version \
    -DclassName="org.my.group.MyResource"

The following table lists the attributes you can pass to the create command:

If you decide to generate a REST resource (using the className attribute), the endpoint is exposed at: http://localhost:8080/$path.If you use the default path, the URL is: http://localhost:8080/hello.

The project is generated in a directory named after the passed artifactId.If the directory already exists, the generation fails.

A pair of Dockerfiles for native and jvm mode are also generated in src/main/docker.Instructions to build the image and run the container are written in those Dockerfiles.

Dealing with extensions

From inside a Quarkus project, you can obtain a list of the available extensions with:

./mvnw quarkus:list-extensions

You can enable an extension using:

./mvnw quarkus:add-extension -Dextensions="hibernate-validator"

Extensions are passed using a comma-separated list.

The extension name is the GAV name of the extension: e.g. io.quarkus:quarkus-agroal.But you can pass a partial name and Quarkus will do its best to find the right extension.For example, agroal, Agroal or agro will expand to io.quarkus:quarkus-agroal.If no extension is found or if more than one extensions match, you will see a red check mark ❌ in the command result.

$ ./mvnw quarkus:add-extensions -Dextensions=jdbc,agroal,non-exist-ent
[...]
❌ Multiple extensions matching 'jdbc'
     * io.quarkus:quarkus-jdbc-h2
     * io.quarkus:quarkus-jdbc-mariadb
     * io.quarkus:quarkus-jdbc-postgresql
     Be more specific e.g using the exact name or the full gav.
✅ Adding extension io.quarkus:quarkus-agroal
❌ Cannot find a dependency matching 'non-exist-ent', maybe a typo?
[...]

You can install all extensions which match a globbing pattern :

./mvnw quarkus:add-extension -Dextensions="hibernate-*"

Development mode

Quarkus comes with a built-in development mode.Run your application with:

./mvnw compile quarkus:dev

You can then update the application sources, resources and configurations.The changes are automatically reflected in your running application.This is great to do development spanning UI and database as you see changes reflected immediately.

quarkus:dev enables hot deployment with background compilation, which meansthat when you modify your Java files or your resource files and refresh your browser these changes will automatically take effect.This works too for resource files like the configuration property file.The act ofrefreshing the browser triggers a scan of the workspace, and if any changes are detected the Java files are compiled,and the application is redeployed, then your request is serviced by the redeployed application. If there are any issueswith compilation or deployment an error page will let you know.

Hit CTRL+C to stop the application.

Remote Development Mode

It is possible to use development mode remotely, so that you can run Quarkus in a container environment (such as Openshift)and have changes made to your local files become immediately visible.

This allows you to develop in the same environment you will actually run your app in, and with access to the same services.

To do this you must have the quarkus-undertow-websockets extension installed:

./mvnw quarkus:add-extension -Dextensions="undertow-websockets"

You must also have the following config properties set:

• quarkus.live-reload.password

• quarkus.live-reload.url

These can be set via application.properties, or any other way (e.g. system properties, environment vars etc). Thepassword must be set on both the local and remote processes, while the url only needs to be set on the local host.

Start Quarkus in dev mode on the remote host. Now you need to connect your local agent to the remote host:

./mvnw quarkus:remote-dev -Dquarkus.live-reload.url=http://my-remote-host:8080

Now every time you refresh the browser you should see any changes you have made locally immediately visible in the remoteapp.

Configuring Development Mode

By default, the Maven plugin picks up compiler flags to pass tojavac from maven-compiler-plugin.

If you need to customize the compiler flags used in development mode,add a configuration section to the plugin block and set thecompilerArgs property just as you would when configuringmaven-compiler-plugin. You can also set source, target, andjvmArgs. For example, to pass —enable-preview to both the JVMand javac:

<plugin>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-maven-plugin</artifactId>
  <version>${quarkus.version}</version>
  <configuration>
    <source>${maven.compiler.source}</source>
    <target>${maven.compiler.target}</target>
    <compilerArgs>
      <arg>--enable-preview</arg>
    </compilerArgs>
    <jvmArgs>--enable-preview</jvmArgs>
  </configuration>
  ...
</plugin>

Debugging

In development mode, Quarkus starts by default with debug mode enabled, listening to port 5005 without suspending the JVM.

This behavior can be changed by giving the debug system property one of the following values:

• false - the JVM will start with debug mode disabled

• true - The JVM is started in debug mode and will be listening on port 5005

• client - the JVM will start in client mode and attempt to connect to localhost:5005

• {port} - The JVM is started in debug mode and will be listening on {port}

An additional system property suspend can be used to suspend the JVM, when launched in debug mode. suspend supports the following values:

• y or true - The debug mode JVM launch is suspended

• n or false - The debug mode JVM is started without suspending

Import in your IDE

Once you have a project generated, you can import it in your favorite IDE.The only requirement is the ability to import a Maven project.

Eclipse

In Eclipse, click on: File → Import.In the wizard, select: Maven → Existing Maven Project.On the next screen, select the root location of the project.The next screen list the found modules; select the generated project and click on Finish. Done!

In a separated terminal, run ./mvnw compile quarkus:dev, and enjoy a highly productive environment.

IntelliJ

In IntelliJ:

• From inside IntelliJ select File → New → Project From Existing Sources…​ or, if you are on the welcome dialog, select Import project.

• Select the project root

• Select Import project from external model and Maven

• Next a few times (review the different options if needed)

• On the last screen click on Finish

In a separated terminal or in the embedded terminal, run ./mvnw compile quarkus:dev. Enjoy!

Apache Netbeans

In Netbeans:

• Select File → Open Project

• Select the project root

• Click on Open Project

In a separated terminal or the embedded terminal, go to the project root and run ./mvnw compile quarkus:dev. Enjoy!

Visual Studio Code

Open the project directory in VS Code. If you have installed the Java Extension Pack (grouping a set of Java extensions), the project is loaded as a Maven project.

Logging Quarkus application build classpath tree

Usually, dependencies of an application (which is a Maven project) could be displayed using mvn dependency:tree command. In case of a Quarkus application, however, this command will list only the runtime dependencies of the application.Given that the Quarkus build process adds deployment dependencies of the extensions used in the application to the original application classpath, it could be useful to know which dependencies and which versions end up on the build classpath.Luckily, the quarkus-bootstrap Maven plugin includes the build-tree goal which displays the build dependency tree for the application.

To be able to use it, the following plugin configuration has to be added to the pom.xml:

            <plugin>
                <groupId>io.quarkus</groupId>
                <artifactId>quarkus-bootstrap-maven-plugin</artifactId>
                <version>${quarkus.version}</version>
            </plugin>

Now you should be able to execute ./mvnw quarkus-bootstrap:build-tree on your project and see something like:

[INFO] --- quarkus-bootstrap-maven-plugin:1.0.0.CR1:build-tree (default-cli) @ getting-started ---
[INFO] org.acme:getting-started:jar:1.0-SNAPSHOT
[INFO] └─ io.quarkus:quarkus-resteasy-deployment:jar:1.0.0.CR1 (compile)
[INFO]    ├─ io.quarkus:quarkus-resteasy-server-common-deployment:jar:1.0.0.CR1 (compile)
[INFO]    │  ├─ io.quarkus:quarkus-core-deployment:jar:1.0.0.CR1 (compile)
[INFO]    │  │  ├─ commons-beanutils:commons-beanutils:jar:1.9.3 (compile)
[INFO]    │  │  │  ├─ commons-logging:commons-logging:jar:1.2 (compile)
[INFO]    │  │  │  └─ commons-collections:commons-collections:jar:3.2.2 (compile)
...

Building a native executable

Native executables make Quarkus applications ideal for containers and serverless workloads.

Make sure to have GRAALVM_HOME configured and pointing to GraalVM version 19.2.1.Verify that your pom.xml has the proper native profile (see Maven configuration).

Create a native executable using: ./mvnw package -Pnative.A native executable will be present in target/.

To run Integration Tests on the native executable, make sure to have the proper Maven plugin configured (see Maven configuration) and launch the verify goal.

./mvnw verify -Pnative
...
[quarkus-quickstart-runner:50955]     universe:     391.96 ms
[quarkus-quickstart-runner:50955]      (parse):     904.37 ms
[quarkus-quickstart-runner:50955]     (inline):   1,143.32 ms
[quarkus-quickstart-runner:50955]    (compile):   6,228.44 ms
[quarkus-quickstart-runner:50955]      compile:   9,130.58 ms
[quarkus-quickstart-runner:50955]        image:   2,101.42 ms
[quarkus-quickstart-runner:50955]        write:     803.18 ms
[quarkus-quickstart-runner:50955]      [total]:  33,520.15 ms
[INFO]
[INFO] --- maven-failsafe-plugin:2.22.0:integration-test (default) @ quarkus-quickstart-native ---
[INFO]
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.acme.quickstart.GreetingResourceIT
Executing [/Users/starksm/Dev/JBoss/Quarkus/starksm64-quarkus-quickstarts/getting-started-native/target/quarkus-quickstart-runner, -Dquarkus.http.port=8081, -Dtest.url=http://localhost:8081, -Dquarkus.log.file.path=target/quarkus.log]
2019-02-28 16:52:42,020 INFO  [io.quarkus] (main) Quarkus started in 0.007s. Listening on: http://localhost:8080
2019-02-28 16:52:42,021 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.081 s - in org.acme.quickstart.GreetingResourceIT
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
...

Build a container friendly executable

The native executable will be specific to your operating system.To create an executable that will run in a container, use the following:

./mvnw package -Dnative -Dquarkus.native.container-build=true

The produced executable will be a 64 bit Linux executable, so depending on your operating system it may no longer be runnable.However, it’s not an issue as we are going to copy it to a Docker container.Note that in this case the build itself runs in a Docker container too, so you don’t need to have GraalVM installed locally.

You can follow the Build a native executable guide as well as Deploying Application to Kubernetes and OpenShift for more information.

Maven configuration

If you have not used project scaffolding, add the following elements in your pom.xml

<dependencyManagement>
    <dependencies>
        <dependency> (1)
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<build>
    <plugins>
        <plugin> (2)
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-maven-plugin</artifactId>
            <version>${quarkus.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>build</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
<profiles>
    <profile> (3)
        <id>native</id>
        <properties> (4)
            <quarkus.package.type>native</quarkus.package.type>
        </properties>
        <build>
            <plugins>
                <plugin> (5)
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-failsafe-plugin</artifactId>
                    <version>${surefire-plugin.version}</version>
                    <executions>
                        <execution>
                            <goals>
                                <goal>integration-test</goal>
                                <goal>verify</goal>
                            </goals>
                            <configuration>
                                <systemProperties>
                                    <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                                </systemProperties>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

Uber-Jar Creation

Quarkus Maven plugin supports the generation of Uber-Jars by specifying a quarkus.package.uber-jar=true configuration option in your application.properties.

The original jar will still be present in the target directory but it will be renamed to contain the .original suffix.

When building an Uber-Jar you can specify entries that you want to exclude from the generated jar by using the quarkus.package.ignored-entries configurationoption, this takes a comma seperated list of entries to ignore.

Uber-Jar creation by default excludes signature files that might be present in the dependencies of the application.

Uber-Jar’s final name is configurable via a Maven’s build settings finalName option.

Configuring the Project Output

There are a several configuration options that will define what the output of your project build will be.These are provided in application.properties the same as any other config property.

The properties are shown below:

Configuration property fixed at build time - ️ Configuration property overridable at runtime

Custom test configuration profile in JVM mode

By default, Quarkus tests in JVM mode are run using the test configuration profile. If you are not familiar with Quarkusconfiguration profiles, everything you need to know is explained in theConfiguration Profiles Documentation.

It is however possible to use a custom configuration profile for your tests with the Maven Surefire and Maven Failsafeconfigurations shown below. This can be useful if you need for example to run some tests using a specific database which is notyour default testing database.

<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>${surefire-plugin.version}</version>
        <configuration>
          <systemPropertyVariables>
            <quarkus.test.profile>foo</quarkus.test.profile> (1)
            <buildDirectory>${project.build.directory}</buildDirectory>
            [...]
          </systemPropertyVariables>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <version>${failsafe-plugin.version}</version>
        <configuration>
          <systemPropertyVariables>
            <quarkus.test.profile>foo</quarkus.test.profile> (1)
            <buildDirectory>${project.build.directory}</buildDirectory>
            [...]
          </systemPropertyVariables>
        </configuration>
      </plugin>
    </plugins>
  </build>
  [...]
</project>