Building Quarkus apps with Maven
Creating a new project
With Maven, you can scaffold a new project with:
mvn io.quarkus:quarkus-maven-plugin:0.12.0:create \
-DprojectGroupId=my-groupId \
-DprojectArtifactId=my-artifactId \
-DprojectVersion=my-version \
-DclassName="org.my.group.MyResource"
If you just launch mvn io.quarkus:quarkus-maven-plugin:0.12.0:create the Maven plugin asks
for user inputs. You can disable (and use default values) this interactive mode by passing -B to the Maven command.
|
The following table lists the attributes you can pass to the create
command:
Attribute | Default Value | Description |
---|---|---|
|
|
The group id of the created project |
|
mandatory |
The artifact id of the created project. Not passing it triggers the interactive mode. |
|
|
The version of the created project |
|
Not created if omitted |
The fully qualified name of the generated resource |
|
|
The resource path, only relevant if |
|
[] |
The list of extensions to add to the project (comma-separated) |
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 either generated in the current directory or in a directory named after the passed artifactId. If the current directory is empty, the project is generated in-place.
A Dockerfile
is also generated in src/main/docker
.
Instructions to build the image and run the container are written in the Dockerfile
.
Dealing with extensions
From inside a Quarkus project, you can obtain a list of the available extensions with:
You can enable an extension using:
Extensions are passed using a comma-separated list.
Development mode
Quarkus comes with a built-in development mode. Run your application with:
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 means
that 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 of
refreshing 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 issues
with compilation or deployment an error page will let you know.
Hit CTRL+C
to stop the application.
Debugging
You can run a Quarkus application in debug mode using:
Then, attach your debugger to `localhost:5005`.
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, selectImport project
. -
Select the project root
-
Select
Import project from external model
andMaven
-
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.
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 1.0.0-rc13.
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 -Pnative -Dnative-image.docker-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>
<build>
<plugins>
<plugin> (3)
<groupId>io.quarkus</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.version}</version>
<executions>
<execution>
<goals>
<goal>native-image</goal>
</goals>
<configuration>
<enableHttpUrlHandler>true</enableHttpUrlHandler>
</configuration>
</execution>
</executions>
</plugin>
<plugin> (4)
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>${surefire.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>
1 | Optionally use a BOM file to omit the version of the different Quarkus dependencies. |
2 | Use the Quarkus Maven plugin that will hook into the build process |
3 | Use a native profile and plugin to activate GraalVM compilation |
4 | If you want to test your native executable with Integration Tests, add the following plugin configuration. Test names *IT and annotated @SubstrateTest will be run against the native executable. See the Native executable guide for more info. |