Getting started with Quarkus

Procedure

1. In a command terminal, enter the following command to verify that Maven is using JDK 11 and that the Maven version is 3.6.2 or higher:

   mvn --version

   Copy to Clipboard Toggle word wrap
2. If the preceding command does not return JDK 11, add the path to JDK 11 to the PATH environment variable and enter the preceding command again.

3. To generate the project, enter one of the following commands:

   Note

   Apple macOS and Microsoft Windows are not supported production environments.

   • If you are using Linux or Apple macOS, enter the following command:

     mvn io.quarkus:quarkus-maven-plugin:1.3.4.Final-redhat-00004:create \
         -DprojectGroupId=org.acme \
         -DprojectArtifactId=getting-started \
         -DplatformGroupId=com.redhat.quarkus \
         -DplatformVersion=1.3.4.Final-redhat-00004 \
         -DclassName="org.acme.quickstart.GreetingResource" \
         -Dpath="/hello"
     cd getting-started

     Copy to Clipboard Toggle word wrap

   • If you are using the Microsoft Windows command line, enter the following command:

     mvn io.quarkus:quarkus-maven-plugin:1.3.4.Final-redhat-00004:create -DprojectGroupId=org.acme -DprojectArtifactId=getting-started -DplatformGroupId=com.redhat.quarkus -DplatformVersion=1.3.4.Final-redhat-00004 -DclassName="org.acme.quickstart.GreetingResource" -Dpath="/hello"

     Copy to Clipboard Toggle word wrap

   • If you are using the Microsoft Windows Powershell, enter the following command:

     mvn io.quarkus:quarkus-maven-plugin:1.3.4.Final-redhat-00004:create "-DprojectGroupId=org.acme" "-DprojectArtifactId=getting-started" "-DplatformGroupId=com.redhat.quarkus" "-DclassName=org.acme.quickstart.GreetingResource" "-Dpath=/hello"

     Copy to Clipboard Toggle word wrap

     These commands create the following elements in the ./getting-started directory:

     • The Maven structure
     • An org.acme.quickstart.GreetingResource resource exposed on /hello
     • An associated unit test
     • A landing page that is accessible on http://localhost:8080 after you start the application
     • Example Dockerfile file in src/main/docker
     • The application configuration file

4. After the directory structure is created, open the pom.xml file in a text editor and examine the contents of the file:

   <dependencyManagement>
       <dependencies>
           <dependency>
               <groupId>com.redhat.quarkus</groupId>
               <artifactId>quarkus-universe-bom</artifactId>
               <version>${quarkus-plugin.version}</version>
               <type>pom</type>
               <scope>import</scope>
           </dependency>
       </dependencies>
   </dependencyManagement>
   
   <build>
     <plugins>
       <plugin>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-maven-plugin</artifactId>
         <version>${quarkus-plugin.version}</version>
         <executions>
           <execution>
             <goals>
               <goal>build</goal>
             </goals>
           </execution>
         </executions>
       </plugin>
       <plugin>
         <artifactId>maven-compiler-plugin</artifactId>
         <version>${compiler-plugin.version}</version>
       </plugin>
       <plugin>
         <artifactId>maven-surefire-plugin</artifactId>
         <version>${surefire-plugin.version}</version>
         <configuration>
           <systemProperties>
             <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
           </systemProperties>
         </configuration>
       </plugin>
     </plugins>
   </build>

   Copy to Clipboard Toggle word wrap

   The Quarkus BOM is imported into the pom.xml file. Therefore, you do not need to list the versions of individual Quarkus dependencies in the pom.xml file. In addition, you can see the quarkus-maven-plugin plug-in that is responsible for packaging the application and providing the development mode.

5. Review the quarkus-resteasy dependency in the pom.xml file. This dependency enables you to develop REST applications:

       <dependency>
           <groupId>io.quarkus</groupId>
           <artifactId>quarkus-resteasy</artifactId>
       </dependency>

   Copy to Clipboard Toggle word wrap

6. Review the src/main/java/org/acme/quickstart/GreetingResource.java file:

   package org.acme.quickstart;
   
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.ws.rs.core.MediaType;
   
   @Path("/hello")
   public class GreetingResource {
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return "hello";
       }
   }

   Copy to Clipboard Toggle word wrap

   This file contains the Java API for RESTful Web Services (JAX-RS) and a very simple REST endpoint that returns hello to requests on /hello.

   Note

   With Quarkus, the Application class for JAX-RS is supported but not required. In addition, only one instance of the GreetingResource class is created and not one per request. You can configure this instance by using the different *Scoped annotations, for example ApplicationScoped, RequestScoped, and so forth.

Procedure

1. To compile the Quarkus Hello application in development mode, enter the following command from the project directory:

   ./mvnw compile quarkus:dev

   Copy to Clipboard Toggle word wrap

   The following example shows the output of this command:

   2020-04-02 10:53:44,263 INFO  [io.quarkus] (main) getting-started 1.0-SNAPSHOT (powered by Quarkus 1.3.4.Final-redhat-00004) started in 0.946s. Listening on: http://0.0.0.0:8080
   2020-04-02 10:53:44,267 INFO  [io.quarkus] (main) Profile dev activated. Live Coding activated.
   2020-04-02 10:53:44,267 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]

   Copy to Clipboard Toggle word wrap

2. To request the provided endpoint, enter the following command in a new terminal window:

   curl -w "\n" http://localhost:8080/hello
   hello

   Copy to Clipboard Toggle word wrap
   Note

   This example uses the "\n" attribute to automatically add a new line before the output of the command. This prevents your terminal from printing a '%' character or putting both the result and the next command prompt on the same line.

3. To stop the application, press CTRL+C.

Procedure

1. To modify the application and add a companion bean, create the src/main/java/org/acme/quickstart/GreetingService.java file with the following content:

   package org.acme.quickstart;
   
   import javax.enterprise.context.ApplicationScoped;
   
   @ApplicationScoped
   public class GreetingService {
   
       public String greeting(String name) {
           return "hello " + name;
       }
   
   }

   Copy to Clipboard Toggle word wrap

2. Edit the src/main/java/org/acme/quickstart/GreetingResource.java to inject the GreetingService and create a new endpoint using it:

   package org.acme.quickstart;
   
   import javax.inject.Inject;
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.ws.rs.core.MediaType;
   
   import org.jboss.resteasy.annotations.jaxrs.PathParam;
   
   @Path("/hello")
   public class GreetingResource {
   
       @Inject
       GreetingService service;
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       @Path("/greeting/{name}")
       public String greeting(@PathParam String name) {
           return service.greeting(name);
       }
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return "hello";
       }
   }

   Copy to Clipboard Toggle word wrap

3. If you stopped the application, enter the following command to restart it:

   ./mvnw compile quarkus:dev

   Copy to Clipboard Toggle word wrap

4. To verify that the endpoint returns hello quarkus, enter the following command in a new terminal window:

   curl -w "\n" http://localhost:8080/hello/greeting/quarkus
   hello quarkus

   Copy to Clipboard Toggle word wrap

Procedure

1. Set the version of the Surefire Maven plug-in:

   <plugin>
       <artifactId>maven-surefire-plugin</artifactId>
       <version>${surefire-plugin.version}</version>
       <configuration>
          <systemProperties>
            <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
          </systemProperties>
       </configuration>
   </plugin>

   Copy to Clipboard Toggle word wrap

   The default Surefire Maven plugin version does not support JUnit 5.

2. Set the java.util.logging system property to make sure tests use the correct log manager.

3. Edit the src/test/java/org/acme/quickstart/GreetingResourceTest.java file to match the following content:

   package org.acme.quickstart;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.junit.jupiter.api.Test;
   
   import java.util.UUID;
   
   import static io.restassured.RestAssured.given;
   import static org.hamcrest.CoreMatchers.is;
   
   @QuarkusTest
   public class GreetingResourceTest {
   
       @Test
       public void testHelloEndpoint() {
           given()
             .when().get("/hello")
             .then()
                .statusCode(200)
                .body(is("hello"));
       }
   
       @Test
       public void testGreetingEndpoint() {
           String uuid = UUID.randomUUID().toString();
           given()
             .pathParam("name", uuid)
             .when().get("/hello/greeting/{name}")
             .then()
               .statusCode(200)
               .body(is("hello " + uuid));
       }
   
   }

   Copy to Clipboard Toggle word wrap
   Note

   By using the QuarkusTest runner, you instruct JUnit to start the application before starting the tests.

4. To run these tests from Maven, enter the following command:

   ./mvnw test

   Copy to Clipboard Toggle word wrap
   Note

   You can also run the test from your IDE. If you do this, make sure to stop the application first.

   By default, tests run on port 8081 so they do not conflict with the running application. In Quarkus, the RestAssured dependency is configured to use this port. If you want to use a different client, use the @TestHTTPResource annotation to directly inject the URL of the tested application into a field on the Test class. This field can be of the type string, URL or URI. You can also provide the test path in this annotation. For example, to test a servlet mapped to /myservlet, add the following lines to your test:

   @TestHTTPResource("/myservlet")
   URL testUrl;

   Copy to Clipboard Toggle word wrap
5. If necessary, specify the test port in the quarkus.http.test-port configuration property.

Procedure

1. To package your Quarkus Getting Started project, enter the following command in the root directory:

   ./mvnw package

   Copy to Clipboard Toggle word wrap

   This command produces the following JAR files in the /target directory:

   • getting-started-1.0-SNAPSHOT.jar: Contains the classes and resources of the projects. This is the regular artifact produced by the Maven build.
   • getting-started-1.0-SNAPSHOT-runner.jar: Is an executable JAR file. Be aware that this file is not an uber-JAR file because the dependencies are copied into the target/lib directory.
2. If development mode is running, press CTRL+C to stop development mode. If you do not do this, you will have a port conflict.

3. To run the application, enter the following command:

   java -jar target/getting-started-1.0-SNAPSHOT-runner.jar

   Copy to Clipboard Toggle word wrap
   Note

   The Class-Path entry of the MANIFEST.MF file from the runner JAR file explicitly lists the JAR files from the lib directory. If you want to deploy your application from another location, you must copy the runner JAR file as well as the lib directory.