Quarkus - Building my first extension

Quarkus extensions enhance your application just as projects dependencies do. The role of the extensions is to leverage Quarkus paradigms to integrate seamlessly a library into Quarkus architecture - e.g. do more things at build time. This is how you can use your battle-tested ecosystem and take advantage of Quarkus performance and native compilation. Go to code.quarkus.io to get the list of the supported extensions.

In this guide we are going to develop the Sample Greeting Extension. The extension will expose a customizable HTTP endpoint which simply greets the visitor.

Disclaimer
To be sure it’s extra clear you don’t need an extension to add a Servlet to your application. This guide is a simplified example to explain the concepts of extensions development. Keep in mind it’s not representative of the power of moving things to build time or simplifying the build of native images.

Prerequisites

To complete this guide, you need:

  • less than 30 minutes

  • an IDE

  • JDK 1.8+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.6.2+

Solution

We recommend that you follow the instructions in the next sections and create the extension step by step. However, you can go right to the completed example.

Clone the Git repository: git clone [https://github.com/quarkusio/quarkus-quickstarts.git](https://github.com/quarkusio/quarkus-quickstarts.git), or download an archive.

The solution is located in the getting-started-extension directory.

Basic Concepts

First things first, we will need to start with some basic concepts.

  • JVM mode vs Native mode

    • Quarkus is first and foremost a Java framework, that means you can develop, package and run classic JAR applications, that’s what we call JVM mode.

    • Thanks to GraalVM you can compile your Java application into machine specific code (like you do in Go or C++) and that’s what we call Native mode.

The operation of compiling Java bytecode into a native system-specific machine code is named Ahead of Time Compilation (aka AoT).

  • build time vs runtime in classic Java frameworks

    • The build time corresponds to all the actions you apply to your Java source files to convert them into something runnable (class files, jar/war, native images). Usually this stage is composed by the compilation, annotation processing, bytecode generation, etc. At this point, everything is under developer’s scope and control.

    • The runtime is all the actions that happen when you execute your application. It’s obviously focused on starting your business-oriented actions but it relies on a lot of technical actions like loading libraries and configuration files, scanning the application’s classpath, configuring the dependency injection, setting up your Object-Relational Mapping, instantiating your REST controllers, etc.

Usually, Java frameworks do their bootstrapping during the runtime before actually starting the application “Business oriented layer”. During bootstrap, frameworks dynamically collect metadata by scanning the classpath to find configurations, entity definitions, dependency injection binding, etc. in order to instantiate proper objects through reflection. The main consequences are:

  • Delaying the readiness of your application: you need to wait a couple of seconds before actually serving a business request.

  • Having a peak of resource consumption at bootstrap: in a constrained environment, you will need to size the needed resources based on your technical bootstrap needs rather than your actual business needs.

Quarkus’ philosophy is to prevent as much as possible slow and memory intensive dynamic code execution by shifting left these actions and eventually do them during the build time. A Quarkus extension is a Java piece of code acting as an adapter layer for your favorite library or technology.

Description of a Quarkus extension

A Quarkus extension consists of two parts:

  • The runtime module which represents the capabilities the extension developer exposes to the application’s developer (an authentication filter, an enhanced data layer API, etc). Runtime dependencies are the ones the users will add as their application dependencies (in Maven POMs or Gradle build scripts).

  • The deployment module which is used during the augmentation phase of the build, it describes how to “deploy” a library following the Quarkus philosophy. In other words, it applies all the Quarkus optimizations to your application during the build. The deployment module is also where we prepare things for GraalVM’s native compilation.

Users should not be adding the deployment modules of extension as application dependencies. The deployment dependencies are resolved by Quarkus during the augmentation phase from the runtime dependencies of the application.

At this point, you should have understood that most of the magic will happen at the Augmentation build time thanks to the deployment module.

Quarkus Application Bootstrap

There are three distinct bootstrap phases of a Quarkus application.

  • Augmentation. During the build time, the Quarkus extensions will load and scan your application’s bytecode (including the dependencies) and configuration. At this stage, the extension can read configuration files, scan classes for specific annotations, etc. Once all the metadata has been collected, the extensions can pre-process the libraries bootstrap actions like your ORM, DI or REST controllers configurations. The result of the bootstrap is directly recorded into bytecode and will be part of your final application package.

  • Static Init. During the run time, Quarkus will execute first a static init method which contains some extensions actions/configurations. When you will do your native packaging, this static method will be pre-processed during the build time and the objects it has generated will be serialized into the final native executable, so the initialization code will not be executed in the native mode (imagine you execute a Fibonacci function during this phase, the result of the computation will be directly recorded in the native executable). When running the application in JVM mode, this static init phase is executed at the start of the application.

  • Runtime Init. Well nothing fancy here, we do classic run time code execution. So, the more code you run during the two phases above, the faster your application will start.

Now that everything is explained, we can start coding!

Maven setup

Quarkus provides create-extension Maven Mojo to initialize your extension project.

  1. $ mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final:create-extension -N \
  2. -DgroupId=org.acme \ (1)
  3. -DartifactId=quarkus-greeting \ (2)
  4. -Dversion=1.0-SNAPSHOT \ (3)
  5. -Dquarkus.nameBase="Greeting Extension" (4)
  6. [INFO] Scanning for projects...
  7. [INFO]
  8. [INFO] ------------------< org.apache.maven:standalone-pom >-------------------
  9. [INFO] Building Maven Stub Project (No POM) 1
  10. [INFO] --------------------------------[ pom ]---------------------------------
  11. [INFO]
  12. [INFO] --- quarkus-maven-plugin:1.7.6.Final:create-extension (default-cli) @ standalone-pom ---
  13. [INFO] ------------------------------------------------------------------------
  14. [INFO] BUILD SUCCESS
  15. [INFO] ------------------------------------------------------------------------
  16. [INFO] Total time: 1.233 s
  17. [INFO] Finished at: 2020-04-22T23:28:15+02:00
  18. [INFO] ------------------------------------------------------------------------
1Project’s groupId
2artifactId for the runtime artifact of the extension (the deployment artifactId will be derived from the runtime artifactId by appending -deployment)
3Project’s version
4Prefix for the <name> element values in the generated POMs

Maven has generated a quarkus-greeting directory containing the extension project which consists of the parent pom.xml, the runtime and the deployment modules.

The parent pom.xml

Your extension is a multi-module project. So let’s start by checking out the parent POM at ./quarkus-greeting/pom.xml.

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <project xmlns="http://maven.apache.org/POM/4.0.0"
  3. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  4. xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  5. <modelVersion>4.0.0</modelVersion>
  6. <groupId>org.acme</groupId>
  7. <artifactId>quarkus-greeting-parent</artifactId>
  8. <version>1.0-SNAPSHOT</version>
  9. <name>Greeting Extension - Parent</name>
  10. <packaging>pom</packaging>
  11. <properties>
  12. <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  13. <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
  14. <maven.compiler.source>1.8</maven.compiler.source>
  15. <maven.compiler.target>1.8</maven.compiler.target>
  16. <maven.compiler.parameters>true</maven.compiler.parameters>
  17. <quarkus.version>1.7.6.Final</quarkus.version>
  18. <compiler-plugin.version>3.8.1</compiler-plugin.version>
  19. </properties>
  20. <modules> (1)
  21. <module>deployment</module>
  22. <module>runtime</module>
  23. </modules>
  24. <dependencyManagement>
  25. <dependencies>
  26. <dependency>
  27. <groupId>io.quarkus</groupId>
  28. <artifactId>quarkus-bom-deployment</artifactId> (2)
  29. <version>${quarkus.version}</version>
  30. <type>pom</type>
  31. <scope>import</scope>
  32. </dependency>
  33. </dependencies>
  34. </dependencyManagement>
  35. <build>
  36. <pluginManagement>
  37. <plugins>
  38. <plugin>
  39. <groupId>org.apache.maven.plugins</groupId>
  40. <artifactId>maven-compiler-plugin</artifactId>
  41. <version>${compiler-plugin.version}</version> (3)
  42. </plugin>
  43. </plugins>
  44. </pluginManagement>
  45. </build>
  46. </project>
1Your extension declares 2 sub-modules deployment and runtime.
2The quarkus-bom-deployment aligns your dependencies with those used by Quarkus during the augmentation phase.
3Quarkus requires a recent version of the Maven compiler plugin supporting the annotationProcessorPaths configuration.

The Deployment module

Let’s have a look at the deployment’s ./quarkus-greeting/deployment/pom.xml.

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <project xmlns="http://maven.apache.org/POM/4.0.0"
  3. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  4. xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  5. <modelVersion>4.0.0</modelVersion>
  6. <parent>
  7. <groupId>org.acme</groupId>
  8. <artifactId>quarkus-greeting-parent</artifactId>
  9. <version>1.0-SNAPSHOT</version>
  10. <relativePath>../pom.xml</relativePath>
  11. </parent>
  12. <artifactId>quarkus-greeting-deployment</artifactId> (1)
  13. <name>Greeting Extension - Deployment</name>
  14. <dependencies>
  15. <dependency>
  16. <groupId>io.quarkus</groupId>
  17. <artifactId>quarkus-core-deployment</artifactId> (2)
  18. <version>${quarkus.version}</version>
  19. </dependency>
  20. <dependency>
  21. <groupId>org.acme</groupId>
  22. <artifactId>quarkus-greeting</artifactId> (3)
  23. <version>${project.version}</version>
  24. </dependency>
  25. </dependencies>
  26. <build>
  27. <plugins>
  28. <plugin>
  29. <groupId>org.apache.maven.plugins</groupId>
  30. <artifactId>maven-compiler-plugin</artifactId>
  31. <configuration>
  32. <annotationProcessorPaths>
  33. <path>
  34. <groupId>io.quarkus</groupId>
  35. <artifactId>quarkus-extension-processor</artifactId> (4)
  36. <version>${quarkus.version}</version>
  37. </path>
  38. </annotationProcessorPaths>
  39. </configuration>
  40. </plugin>
  41. </plugins>
  42. </build>
  43. </project>

The key points are:

1By convention, the deployment module has the -deployment suffix (greeting-deployment).
2The deployment module depends on the quarkus-core-deployment artifact. We will see later which dependencies are convenient to add.
3The deployment module also must depend on the runtime module.
4We add the quarkus-extension-processor to the compiler annotation processors.

In addition to the pom.xml create-extension also generated the org.acme.quarkus.greeting.deployment.GreetingProcessor class.

  1. package org.acme.quarkus.greeting.deployment;
  2. import io.quarkus.deployment.annotations.BuildStep;
  3. import io.quarkus.deployment.builditem.FeatureBuildItem;
  4. class GreetingProcessor {
  5. private static final String FEATURE = "greeting";
  6. @BuildStep
  7. FeatureBuildItem feature() {
  8. return new FeatureBuildItem(FEATURE);
  9. }
  10. }
FeatureBuildItem represents a functionality provided by an extension. The name of the feature gets displayed in the log during application bootstrap. An extension should provide at most one feature.

Be patient, we will explain the Build Step Processor concept and all the extension deployment API later on. At this point, you just need to understand that this class explains to Quarkus how to deploy a feature named greeting which is your extension. In other words, you are augmenting your application to use the greeting extension with all the Quarkus benefits (build time optimization, native support, etc.).

The Runtime module

Finally ./quarkus-greeting/runtime/pom.xml.

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <project xmlns="http://maven.apache.org/POM/4.0.0"
  3. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  4. xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  5. <modelVersion>4.0.0</modelVersion>
  6. <parent>
  7. <groupId>org.acme</groupId>
  8. <artifactId>quarkus-greeting-parent</artifactId>
  9. <version>1.0-SNAPSHOT</version>
  10. <relativePath>../pom.xml</relativePath>
  11. </parent>
  12. <artifactId>quarkus-greeting</artifactId> (1)
  13. <name>Greeting Extension - Runtime</name>
  14. <dependencies>
  15. </dependencies>
  16. <build>
  17. <plugins>
  18. <plugin>
  19. <groupId>io.quarkus</groupId>
  20. <artifactId>quarkus-bootstrap-maven-plugin</artifactId> (2)
  21. <version>${quarkus.version}</version>
  22. <executions>
  23. <execution>
  24. <goals>
  25. <goal>extension-descriptor</goal>
  26. </goals>
  27. <phase>compile</phase>
  28. <configuration>
  29. <deployment>${project.groupId}:${project.artifactId}-deployment:${project.version}
  30. </deployment>
  31. </configuration>
  32. </execution>
  33. </executions>
  34. </plugin>
  35. <plugin>
  36. <groupId>org.apache.maven.plugins</groupId>
  37. <artifactId>maven-compiler-plugin</artifactId>
  38. <configuration>
  39. <annotationProcessorPaths>
  40. <path>
  41. <groupId>io.quarkus</groupId>
  42. <artifactId>quarkus-extension-processor</artifactId> (3)
  43. <version>${quarkus.version}</version>
  44. </path>
  45. </annotationProcessorPaths>
  46. </configuration>
  47. </plugin>
  48. </plugins>
  49. </build>
  50. </project>

The key points are:

1By convention, the runtime module has no suffix (greeting) as it is the artifact exposed to the end user.
2We add the quarkus-bootstrap-maven-plugin to generate the Quarkus extension descriptor included into the runtime artifact which links it with the corresponding deployment artifact.
3We add the quarkus-extension-processor to the compiler annotation processors.

Basic version of the Sample Greeting extension

Implementing the Greeting feature

The (killer) feature proposed by our extension is to greet the user. To do so, our extension will deploy, in the user application, a Servlet exposing the HTTP endpoint /greeting which responds to the GET verb with a plain text Hello.

The runtime module is where you develop the feature you want to propose to your users, so it’s time to create our Web Servlet.

To use Servlets in your applications you need to have a Servlet Container such as Undertow. Luckily, quarkus-bom-deployment imported by our parent pom.xml already includes the Undertow Quarkus extension. All we need to do is add

  1. <dependencies>
  2. <dependency>
  3. <groupId>io.quarkus</groupId>
  4. <artifactId>quarkus-undertow</artifactId>
  5. </dependency>
  6. </dependencies>

to our ./quarkus-greeting/runtime/pom.xml.

Now we can create our Servlet org.acme.quarkus.greeting.GreetingServlet in the runtime module.

  1. package org.acme.quarkus.greeting;
  2. import javax.servlet.annotation.WebServlet;
  3. import javax.servlet.http.HttpServlet;
  4. import javax.servlet.http.HttpServletRequest;
  5. import javax.servlet.http.HttpServletResponse;
  6. import java.io.IOException;
  7. @WebServlet
  8. public class GreetingServlet extends HttpServlet { (1)
  9. @Override
  10. protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { (2)
  11. resp.getWriter().write("Hello");
  12. }
  13. }
1As usual, defining a servlet requires to extend javax.servlet.http.HttpServlet.
2Since we want to respond to the HTTP GET verb, we override the doGet method and write Hello in the Servlet response’s output stream.

Deploying the Greeting feature

Quarkus magic relies on bytecode generation at build time rather than waiting for the runtime code evaluation, that’s the role of your extension’s deployment module. Calm down, we know, bytecode is hard and you don’t want to do it manually, Quarkus proposes a high level API to make your life easier. Thanks to basic concepts, you will describe the items to produce/consume and the corresponding steps in order to generate the bytecode to produce during the deployment time.

The io.quarkus.builder.item.BuildItem concept represents object instances you will produce or consume (and at some point convert into bytecode) thanks to methods annotated with @io.quarkus.deployment.annotations.BuildStep which describe your extension’s deployment tasks.

Go back to the generated org.acme.quarkus.greeting.deployment.GreetingProcessor class.

  1. package org.acme.quarkus.greeting.deployment;
  2. import io.quarkus.deployment.annotations.BuildStep;
  3. import io.quarkus.deployment.builditem.FeatureBuildItem;
  4. class GreetingProcessor {
  5. private static final String FEATURE = "greeting";
  6. @BuildStep (1)
  7. FeatureBuildItem feature() {
  8. return new FeatureBuildItem(FEATURE); (2)
  9. }
  10. }
1feature() method is annotated with @BuildStep which means it is identified as a deployment task Quarkus will have to execute during the deployment. BuildStep methods are run concurrently at augmentation time to augment the application. They use a producer/consumer model, where a step is guaranteed not to be run until all the items that it is consuming have been produced.
2io.quarkus.deployment.builditem.FeatureBuildItem is an implementation of BuildItem which represents the description of an extension. This BuildItem will be used by Quarkus to display information to the users when the application is starting.

There are many BuildItem implementations, each one represents an aspect of the deployment process. Here are some examples:

  • ServletBuildItem: describes a Servlet (name, path, etc.) we want to generate during the deployment.

  • BeanContainerBuildItem: describes a container used to store and retrieve object instances during the deployment.

If you don’t find a BuildItem for what you want to achieve, you can create your own implementation. Keep in mind that a BuildItem should be as fine-grained as possible, representing a specific part of the deployment. To create your BuildItem you can extend:

  • io.quarkus.builder.item.SimpleBuildItem if you need only a single instance of the item during the deployment (e.g. BeanContainerBuildItem, you only want one container).

  • io.quarkus.builder.item.MultiBuildItem if you want to have multiple instances (e.g. ServletBuildItem, you can produce many Servlets during the deployment).

It’s now time to declare our HTTP endpoint. To do so, we need to produce a ServletBuildItem. At this point, we are sure you understood that if the quarkus-undertow dependency proposes Servlet support for our runtime module, we will need the quarkus-undertow-deployment dependency in our deployment module to have access to the io.quarkus.undertow.deployment.ServletBuildItem.

Update the ./quarkus-greeting/deployment/pom.xml as follows:

  1. <dependencies>
  2. <dependency>
  3. <groupId>org.acme</groupId>
  4. <artifactId>quarkus-greeting</artifactId>
  5. <version>${project.version}</version>
  6. </dependency>
  7. <dependency>
  8. <groupId>io.quarkus</groupId>
  9. <artifactId>quarkus-undertow-deployment</artifactId>
  10. </dependency>
  11. </dependencies>
The dependency on quarkus-core-deployment generated by the create-extension mojo can now be removed since quarkus-undertow-deployment already depends on it.

We can now update org.acme.quarkus.greeting.deployment.GreetingProcessor:

  1. package org.acme.quarkus.greeting.deployment;
  2. import io.quarkus.deployment.annotations.BuildStep;
  3. import io.quarkus.deployment.builditem.FeatureBuildItem;
  4. import org.acme.quarkus.greeting.GreetingServlet;
  5. import io.quarkus.undertow.deployment.ServletBuildItem;
  6. class GreetingProcessor {
  7. private static final String FEATURE = "greeting";
  8. @BuildStep
  9. FeatureBuildItem feature() {
  10. return new FeatureBuildItem(FEATURE);
  11. }
  12. @BuildStep
  13. ServletBuildItem createServlet() { (1)
  14. ServletBuildItem servletBuildItem = ServletBuildItem.builder("greeting", GreetingServlet.class.getName())
  15. .addMapping("/greeting")
  16. .build(); (2)
  17. return servletBuildItem;
  18. }
  19. }
1We add a createServlet method which returns a ServletBuildItem and annotate it with @BuildStep. Now, Quarkus will process this new task which will result in the bytecode generation of the Servlet registration at build time.
2ServletBuildItem proposes a fluent API to instantiate a Servlet named greeting of type GreetingServlet (it’s our class provided by our extension runtime module), and map it the /greeting path.

Testing the Greeting feature

When developing a Quarkus extension, you mainly want to test your feature is properly deployed in an application and works as expected. That’s why the tests will be hosted in the deployment module.

Let’s add the testing dependencies into the ./quarkus-greeting/deployment/pom.xml and maven-surefire configuration

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <project xmlns="http://maven.apache.org/POM/4.0.0"
  3. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  4. xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  5. <modelVersion>4.0.0</modelVersion>
  6. <parent>
  7. <groupId>org.acme</groupId>
  8. <artifactId>quarkus-greeting-parent</artifactId>
  9. <version>1.0-SNAPSHOT</version>
  10. <relativePath>../pom.xml</relativePath>
  11. </parent>
  12. <artifactId>quarkus-greeting-deployment</artifactId>
  13. <name>Greeting Extension - Deployment</name>
  14. <properties>
  15. <maven.surefire.version>3.0.0-M4</maven.surefire.version>
  16. </properties>
  17. <dependencies>
  18. <dependency>
  19. <groupId>org.acme</groupId>
  20. <artifactId>quarkus-greeting</artifactId>
  21. <version>${project.version}</version>
  22. </dependency>
  23. <dependency>
  24. <groupId>io.quarkus</groupId>
  25. <artifactId>quarkus-undertow-deployment</artifactId>
  26. </dependency>
  27. <dependency>
  28. <groupId>io.quarkus</groupId>
  29. <artifactId>quarkus-junit5-internal</artifactId> (1)
  30. <scope>test</scope>
  31. </dependency>
  32. <dependency>
  33. <groupId>io.rest-assured</groupId>
  34. <artifactId>rest-assured</artifactId> (2)
  35. <scope>test</scope>
  36. </dependency>
  37. </dependencies>
  38. <build>
  39. <plugins>
  40. <plugin>
  41. <groupId>org.apache.maven.plugins</groupId>
  42. <artifactId>maven-compiler-plugin</artifactId>
  43. <configuration>
  44. <annotationProcessorPaths>
  45. <path>
  46. <groupId>io.quarkus</groupId>
  47. <artifactId>quarkus-extension-processor</artifactId>
  48. <version>${quarkus.version}</version>
  49. </path>
  50. </annotationProcessorPaths>
  51. </configuration>
  52. </plugin>
  53. <plugin>
  54. <artifactId>maven-surefire-plugin</artifactId> (3)
  55. <version>${maven.surefire.version}</version>
  56. <configuration>
  57. <systemPropertyVariables>
  58. <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
  59. <maven.home>${maven.home}</maven.home>
  60. </systemPropertyVariables>
  61. </configuration>
  62. </plugin>
  63. </plugins>
  64. </build>
  65. </project>
1Quarkus proposes facilities to test extensions via the quarkus-junit5-internal artifact, in particular the io.quarkus.test.QuarkusUnitTest runner which starts an application with your extension.
2We will use RestAssured (massively used in Quarkus) to test our HTTP endpoint.
3In order to not fallback to JUnit 4 legacy mode you need to define a recent version of maven-surefire plugin.

Currently, the create-extension Maven Mojo does not create the test structure. We’ll create it ourselves:

  1. mkdir -p ./quarkus-greeting/deployment/src/test/java/org/acme/quarkus/greeting/deployment

To start testing your extension, create the following org.acme.quarkus.greeting.deployment.GreetingTest test class:

  1. package org.acme.quarkus.greeting.deployment;
  2. import io.quarkus.test.QuarkusUnitTest;
  3. import io.restassured.RestAssured;
  4. import org.jboss.shrinkwrap.api.ShrinkWrap;
  5. import org.jboss.shrinkwrap.api.spec.JavaArchive;
  6. import org.junit.jupiter.api.Test;
  7. import org.junit.jupiter.api.extension.RegisterExtension;
  8. import static org.hamcrest.Matchers.containsString;
  9. public class GreetingTest {
  10. @RegisterExtension
  11. static final QuarkusUnitTest config = new QuarkusUnitTest()
  12. .setArchiveProducer(() -> ShrinkWrap.create(JavaArchive.class)); (1)
  13. @Test
  14. public void testGreeting() {
  15. RestAssured.when().get("/greeting").then().statusCode(200).body(containsString("Hello")); (2)
  16. }
  17. }
1We register a Junit Extension which will start a Quarkus application with the Greeting extension.
2We verify the application has a greeting endpoint responding to a HTTP GET request with a OK status (200) and a plain text body containing Hello

Time to test!

  1. $ mvn clean test
  2. [INFO] Scanning for projects...
  3. [INFO] ------------------------------------------------------------------------
  4. [INFO] Reactor Build Order:
  5. [INFO]
  6. [INFO] Greeting Extension - Parent [pom]
  7. [INFO] Greeting Extension - Runtime [jar]
  8. [INFO] Greeting Extension - Deployment [jar]
  9. [INFO]
  10. ...
  11. [INFO] --- maven-surefire-plugin:3.0.0-M4:test (default-test) @ quarkus-greeting-deployment ---
  12. [INFO]
  13. [INFO] -------------------------------------------------------
  14. [INFO] T E S T S
  15. [INFO] -------------------------------------------------------
  16. [INFO] Running org.acme.quarkus.greeting.deployment.GreetingTest
  17. 2020-04-23 13:55:44,612 INFO [io.quarkus] (main) Quarkus 1.7.6.Final started in 0.395s. Listening on: http://0.0.0.0:8081
  18. 2020-04-23 13:55:44,614 INFO [io.quarkus] (main) Profile test activated.
  19. 2020-04-23 13:55:44,614 INFO [io.quarkus] (main) Installed features: [cdi, quarkus-greeting, servlet]
  20. 2020-04-23 13:55:45,876 INFO [io.quarkus] (main) Quarkus stopped in 0.025s
  21. [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.609 s - in org.acme.quarkus.greeting.deployment.GreetingTest
  22. [INFO]
  23. [INFO] Results:
  24. [INFO]
  25. [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
  26. [INFO]
  27. [INFO] ------------------------------------------------------------------------
  28. [INFO] Reactor Summary for getting-started-extension 1.0-SNAPSHOT:
  29. [INFO]
  30. [INFO] getting-started-extension .......................... SUCCESS [ 0.076 s]
  31. [INFO] Greeting Extension - Parent ........................ SUCCESS [ 0.002 s]
  32. [INFO] Greeting Extension - Runtime ....................... SUCCESS [ 1.467 s]
  33. [INFO] Greeting Extension - Deployment .................... SUCCESS [ 4.099 s]
  34. [INFO] ------------------------------------------------------------------------
  35. [INFO] BUILD SUCCESS
  36. [INFO] ------------------------------------------------------------------------
  37. [INFO] Total time: 5.745 s
  38. [INFO] Finished at: 2020-01-28T22:40:56+01:00
  39. [INFO] ------------------------------------------------------------------------

Looks good! Congratulations you just finished your first extension.

Debugging your extension

If debugging is the process of removing bugs, then programming must be the process of putting them in. Edsger W. Dijkstra

Debugging your application build

Since your extension deployment is made during the application build, this process is triggered by your build tool. That means if your want to debug this phase you need to launch your build tool with the remote debug mode switched one.

Maven

You can activate Maven remote debugging by using mvnDebug. You can launch your application with the following command line:

  1. mvnDebug clean compile quarkus:dev

By default, Maven will wait for a connection on localhost:8000. Now, you can run your IDE Remote configuration to attach it to localhost:8000.

Gradle

You can activate Gradle remote debugging by using the flags org.gradle.debug=true or org.gradle.daemon.debug=true in daemon mode. You can launch your application with the following command line:

  1. ./gradlew quarkusDev -Dorg.gradle.daemon.debug=true

By default, Maven will wait for a connection on localhost:5005. Now, you can run your IDE Remote configuration to attach it to localhost:5005.

Debugging your extension tests

We have seen together how to test your extension and sometimes things don’t go so well and you want to debug your tests. Same principle here, the trick is to enable the Maven Surefire remote debugging in order to attach an IDE Remote configuration.

  1. $ cd ./greeting
  2. $ mvn clean test -Dmaven.surefire.debug

By default, Maven will wait for a connection on localhost:5005.

Extension publication

Now that you just finish to build your first extension you should be eager to use it in a Quarkus application!

Classic Maven publication

Because your extension produces traditional JARs, the easiest way to share your extension is to publish it to a Maven repository. Once published you can simply declare it with your project dependencies. Let’s demonstrate that by creating a simple Quarkus application

  1. $mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final:create \
  2. -DprojectGroupId=org.acme \
  3. -DprojectArtifactId=greeting-app \
  4. -DprojectVersion=1.0-SNAPSHOT \
  5. -DclassName=HelloResource

cd into greeting-app and add the dependency on quarkus-greeting extension we created above.

quarkus-greeting extension has to be installed in the local Maven repository to be usable in the application.
  1. <dependencies>
  2. <dependency>
  3. <groupId>org.acme</groupId>
  4. <artifactId>quarkus-greeting</artifactId>
  5. <version>1.0-SNAPSHOT</version>
  6. </dependency>
  7. <dependency>
  8. <groupId>io.quarkus</groupId>
  9. <artifactId>quarkus-resteasy</artifactId>
  10. </dependency>
  11. <!-- the rest of the application dependencies -->

Run the application and notice the Install Features list contains the quarkus-greeting extension.

  1. $ mvn clean compile quarkus:dev
  2. [INFO] Scanning for projects...
  3. [INFO]
  4. [INFO] ---------------------< org.acme:code-with-quarkus >---------------------
  5. [INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
  6. [INFO] --------------------------------[ jar ]---------------------------------
  7. [INFO]
  8. [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ code-with-quarkus ---
  9. [INFO] Deleting /tmp/code-with-quarkus/target
  10. [INFO]
  11. [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ code-with-quarkus ---
  12. [INFO] Using 'UTF-8' encoding to copy filtered resources.
  13. [INFO] Copying 2 resources
  14. [INFO]
  15. [INFO] --- maven-compiler-plugin:3.8.1:compile (default-compile) @ code-with-quarkus ---
  16. [INFO] Changes detected - recompiling the module!
  17. [INFO] Compiling 1 source file to /tmp/code-with-quarkus/target/classes
  18. [INFO]
  19. [INFO] --- quarkus-maven-plugin:1.7.6.Final:dev (default-cli) @ code-with-quarkus ---
  20. Listening for transport dt_socket at address: 5005
  21. __ ____ __ _____ ___ __ ____ ______
  22. --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
  23. -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
  24. --\___\_\____/_/ |_/_/|_/_/|_|\____/___/
  25. 2020-04-23 14:17:36,137 INFO [io.quarkus] (Quarkus Main Thread) greeting-app 1.0-SNAPSHOT (powered by Quarkus 1.7.6.Final) started in 0.985s. Listening on: http://0.0.0.0:8080
  26. 2020-04-23 14:17:36,140 INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
  27. 2020-04-23 14:17:36,140 INFO [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, quarkus-greeting, resteasy, servlet]

From an extension developer standpoint the Maven publication strategy is very handy and fast but Quarkus wants to go one step further by also ensuring a reliability of the ecosystem for the people who will use the extensions. Think about it, we all had a poor Developer Experience with an unmaintained library, an incompatibility between dependencies (and we don’t even talk about legal issues). That’s why there is the Quarkus Platform.

Quarkus Platform

Quarkus proposes a quarkus-universe-bom which is a certified list of extensions placed under the Quarkus Platform label. From an application developer, the objectives of the platform are:

  • To guarantee a supportability of the extension (bugfix, security issues, dependency upgrades)

  • To ease the extension discovery through the Quarkus CLI or https://code.quarkus.io/

  • To ensure a global consistency of the extension ecosystem

Should I publish my extension to the platform?
If you feel your extensions is for you or a limited group, simply publishing to Maven is fine. If the extension solves a general problem, it is very handy for Quarkus users to see it on https://code.quarkus.io. But this comes with some responsibility for you, keeping it up to date with Quarkus minor releases (every month or so at the moment). When in doubt, have a conversation with the community in the Quarkus Google Group. We can make a collective decision.
As for now, the process to propose a new extension is not defined yet. Your best chance is to present your extension on the Quarkus Google Group and wait for an official invitation to join the Quarkus Platform.

Conclusion

Creating new extensions may appear to be an intricate task at first but once you understood the Quarkus game-changer paradigm (build time vs runtime) the structure of an extension makes perfectly sense.

As usual, along the path Quarkus simplifies things under the hood (Maven Mojo, bytecode generation or testing) to make it pleasant to develop new features.