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.11.7.Final-redhat-00009:create \
         -DprojectGroupId=org.acme \
         -DprojectArtifactId=getting-started \
         -DplatformGroupId=com.redhat.quarkus \
         -DplatformVersion=1.11.7.Final-redhat-00009 \
         -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.11.7.Final-redhat-00009:create -DprojectGroupId=org.acme -DprojectArtifactId=getting-started -DplatformGroupId=com.redhat.quarkus -DplatformVersion=1.11.7.Final-redhat-00009 -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.11.7.Final-redhat-00009:create "-DprojectGroupId=org.acme" "-DprojectArtifactId=getting-started" "-DplatformVersion=1.11.7.Final-redhat-00009" "-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 project directory structure
     • An org.acme.quickstart.GreetingResource resource exposed on /hello
     • Associated unit tests for testing your application in native mode and JVM mode
     • A landing page that is accessible on http://localhost:8080 after you start the application
     • Example Dockerfile.jvm, Dockerfile.native, and Dockerfile.fast-jar files in the src/main/docker directory
     • 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.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>
               <goal>generate-code</goal>
               <goal>generate-code-tests</goal>
             </goals>
           </execution>
         </executions>
       </plugin>
    </plugins>
   </build>

   Copy to Clipboard Toggle word wrap

   The Quarkus BOM is included in the <dependencyManagement> section of 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 a simple REST endpoint that returns hello as a response to a request that you send to the /hello endpoint.

   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 by using 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:

   [INFO] --------------------< org.acme:getting-started >---------------------
   [INFO] Building getting-started 1.0.0-SNAPSHOT
   [INFO] --------------------------------[ jar ]---------------------------------
   [INFO]
   [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ getting-started ---
   [INFO] Using 'UTF-8' encoding to copy filtered resources.
   [INFO] skip non existing resourceDirectory /Users/starksm/Dev/JBoss/Quarkus/starksm64-quarkus-quickstarts/getting-started/src/main/resources
   [INFO]
   [INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ getting-started ---
   [INFO] Changes detected - recompiling the module!
   [INFO] Compiling 2 source files to /Users/starksm/Dev/JBoss/Quarkus/starksm64-quarkus-quickstarts/getting-started/target/classes
   [INFO]
   [INFO] --- quarkus-maven-plugin:<version>:dev (default-cli) @ getting-started ---
   Listening for transport dt_socket at address: 5005
   2019-02-28 17:05:22,347 INFO  [io.qua.dep.QuarkusAugmentor] (main) Beginning quarkus augmentation
   2019-02-28 17:05:22,635 INFO  [io.qua.dep.QuarkusAugmentor] (main) Quarkus augmentation completed in 288ms
   2019-02-28 17:05:22,770 INFO  [io.quarkus] (main) Quarkus started in 0.668s. Listening on: http://localhost:8080
   2019-02-28 17:05:22,771 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]

   Copy to Clipboard Toggle word wrap

2. Enter the following command in a new terminal window to send a request to the endpoint provided by the application:

   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. Press CTRL+C to stop the application.

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. Open the generated pom.xml file and review the contents:

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

   Copy to Clipboard Toggle word wrap

   Note, that:

   • the java.util.logging.manager system property is set to ensure that you application uses the correct log manager for the test.
   • the maven.home property points to the location of the settings.xml file in which you can store custom Maven configuration that you want to apply to your project.

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

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

     Warning

     When your application is running in development mode, you must press CTRL+C to stop your application. You will encounter a port conflict when you try to package your application when development mode is enabled.

2. Enter the following command to start your application:

   java -jar target/getting-started-1.0-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.

Procedure

1. Navigate to https://code.quarkus.redhat.com using a web browser.

2. Specify basic details about your project:

   1. Enter a group name for your project. The format of the name follows the Java package naming convention, for example, org.acme.
   2. Enter a name that you want to use for Maven artifacts generated from your project, for example code-with-quarkus.

   3. Select the build tool that you want to use to compile and start your application. The build tool that you choose determines:

      • the directory structure of your generated project.
      • the format of configuration files used in your generated project.

      • the custom build script and command for compiling and starting your application that code.quarkus.redhat.com displays for you after you generate your project.

        Note

        Red Hat provides support for using code.quarkus.redhat.com to create Quarkus Maven projects only. Generating Gradle projects is not supported by Red Hat.

        

        View larger image

        

3. Specify additional details about your application project:

   1. Select Configure more options to display the fields that contain additional application details.
   2. Enter a version that is used in artifacts generated from your project. The default value of this field is 1.0.0-SNAPSHOT. Using semantic versioning is recommended, but you can use a different type of versioning, if you prefer.

   3. Select whether you want code.quarkus.redhat.com to add example code to your project. When you add extensions that are marked with the icon to your project from the list of extensions, you can enable this option to automatically create example class files and resource files for those extensions when you generate your project. When you do not add any extensions that provide example code, this option does not affect your generated project.

      

      View larger image

      
      Note

      code.quarkus.redhat.com automatically uses the latest release of Red Hat build of Quarkus. You can manually change the BOM version in the pom.xml file after you generate your project.

4. Select the extensions that you want to use in your application from the list of extensions. The selected extensions are included as dependencies of your Quarkus application with their versions being managed by the Quarkus platform to ensure their compatibility.

   You can enable the option to automatically generate example code for extensions that are marked with the icon.

   

   Note, that Red Hat provides different levels of support for individual extensions on the list, which are indicated by labels next to the name of each extension:

   • SUPPORTED extensions are fully supported by Red Hat for use in enterprise application in production environments.
   • TECH-PREVIEW extensions are subject to limited support by Red Hat in production environments under the Technology Preview Features Support Scope.
   • DEV-SUPPORT extensions are not supported by Red Hat for use in production environments, but the core functionalities that they provide are supported by Red Hat developers for use in developing new applications.
   • Unlabeled extensions are not supported by Red Hat for use in production environments.

   • DEPRECATED extension are planned to be replaced by a newer technology or implementation that provides the same functionality.

     You can expand the overflow menu (⋮) next to each of the extensions to access additional options that you can use to:

     • add the extension to an existing project using the Quarkus maven plugin on the command line.
     • copy an XML snippet to add the the extension to the pom.xml file of a project.
     • obtain the groupId, artifactId and version of each extension.

     • open the extension guide.

       

5. Select Generate your application to confirm your choices and display the overlay screen with the download link for the archive that contains your generated project. The overlay screen also shows the custom command that you can use to compile and start your application.
6. Select Download the ZIP to save the archive with the generated project files to your machine.
7. Extract the contents of the archive.

8. Navigate to the directory that contains your extracted project files:

   cd <directory_name>

   Copy to Clipboard Toggle word wrap

9. Compile and start your application in development mode:

   ./mvnw compile quarkus:dev

   Copy to Clipboard Toggle word wrap