Chapter 2 – Getting Started with Quarkus

Continuous testing will need to be re-enabled after making a change to the project’s
dependencies. On the terminal, press the r key to resume continuous testing.

Next, return to the GreetingResourceTest class. Add a GreetingService attribute

to the class and place the @InjectMock annotation on it:

@InjectMock
GreetingService greetingService;

The @InjectMock annotation on the attribute injects a mock of the Greeting-

Service class into the GreetingResourceTest class and makes it available in
all test class methods. The @InjectMock annotation is similar to the @MockBean
annotation provided by the Spring Boot Test framework. The Mockito framework
can then be used directly to define and verify interactions on the mock, just as in
a Spring Boot test.

Replace the contents of the testHelloEndpoint() method with the contents from Note: Similarly, the
Listing 2.13 and save the changes. @InjectSpy annotation
from Quarkus spies on a
Listing 2.13: GreetingResourceTest.java.
bean just like the @SpyBean
@QuarkusTest annotation provided by the
public class GreetingResourceTest { Spring Boot Test framework.
@InjectMock
GreetingService greetingService;

@Test
public void testHelloEndpoint() {
Mockito.when(this.greetingService.getGreeting())
.thenReturn(“Hello Quarkus”);

given()
.when().get(“/hello-resteasy”)
.then()

.body(is(“Hello Quarkus”));

Mockito.verify(this.greetingService).getGreeting();
Mockito.verifyNoMoreInteractions(this.greetingService);
}
}

The Mockito.when(this.greetingService.getGreeting()).thenRe-
turn(“Hello Quarkus”); statement says that when the getGreeting() method
is called on the GreetingService bean, the call returns the value Hello Quarkus.
GreetingService.getGreeting() method was
called exactly once, and no other methods were called on the GreetingService class.

Return to the terminal and notice that Quarkus automatically ran the test successfully.

GreetingServiceTest.java class was not rerun.

--
All 2 tests are passing (0 skipped), 1 tests were run in 697ms.

Feel free to try out the continuous testing a bit more by making changes to the applica-
tion source code. Quarkus will automatically rerun tests affected by changes made.

Quarkus for Spring Developers | 41

 Chapter 2 – Getting Started with Quarkus

Return to the terminal where the ./mvnw quarkus:dev command is running and ter-
minate Dev Mode.

Native Image Testing

native image. The native image should also be tested as part of the build process.
However, keep in mind that the tests do not run within the native image; they run in
the JVM. The native application image runs in a separate process, and a native image
test interacts with the application as an external client. This separation prohibits in-
jecting or mocking beans in a native image test. Instead, a native image test typically
interacts with the application via HTTP, messaging, or other communication channels,
just like any other external client to the application. Additionally, by default, the native
image runs the prod quarkus.
property in src/main/resources/application.
properties.

To create a native image test, create a new test class and extend an existing JVM
test annotated with @QuarkusTest, placing the @NativeImageTest annotation on
it. As mentioned previously, if the base test class injects or mocks beans, those
tests need to be excluded from the native image test by annotating test methods
with the @DisabledOnNativeImage annotation. The native image test class can then
add additional test methods.

In the chapter-2-simple-project project, open the src/test/java/org/acme/

NativeGreetingResourceIt.java
state because the parent GreetingResourceTest class mocks the GreetingService
bean.

To fix this, first add the @DisabledOnNativeImage annotation to the

testHelloEndpoint() method in the GreetingResourceTest class. Then replace
the NativeGreetingResourceIT class contents with the content in Listing 2.14.

Listing 2.14: NativeGreetingResourceIT.java.

@NativeImageTest
public class NativeGreetingResourceIT extends GreetingResourceTest {
@Test
public void testHelloEndpointNative() {
given()
.when().get(“/hello-resteasy”)
.then()

.body(is(“Hello Quarkus for Spring Developer (prod)”));

}
}

Assuming a proper GraalVM setup, return to the terminal and run:

$ ./mvnw verify -Pnative

This command will compile the application, run the regular tests, and build a native im-
age. It may take a few minutes for the native image build to complete. Once complet-
ed, the native image starts and the native image tests run within the JVM. The output
should show something similar to the following, indicating successful native image test
execution:

Quarkus for Spring Developers | 42

 Chapter 2 – Getting Started with Quarkus

[INFO] Running org.acme.NativeGreetingResourceIT

Executing [/examples/chapter-2/chapter-2-simple-project/target/
chapter-2-simple-project-1.0.0-SNAPSHOT-runner, -Dquarkus.http.port=8081,
-Dquarkus.http.ssl-port=8444, -Dtest.url=http://localhost:8081, -Dquarkus.log.

__ ____ __ _____ ___ __ ____ ______

--/ __ \/ / / / _ | / _ \/ //_/ / / / __/
-/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
INFO [io.quarkus] (main) chapter-2-simple-project 1.0.0-SNAPSHOT native (powered
by Quarkus 2.xx.x.Final) started in 0.019s. Listening on: http://0.0.0.0:8081

INFO [io.quarkus] (main) Installed features: [cdi, resteasy,

smallrye-context-propagation]
[WARNING] Tests run: 2, Failures: 0, Errors: 0, Skipped: 1, Time elapsed: 2.676 s -
in org.acme.NativeGreetingResourceIT

Native image tests aren’t required to extend another test class. The code.quarkus.
io generator uses this convention purely for convenience. There may be tests in the

inheritance. You could remove the extends GreetingResourceTest clause from the
NativeGreetingResourceIT class and the native image tests would run successfully.

Additionally, the @NativeImageTest annotation will be deprecated at some point in

the future [2.30]. The @QuarkusIntegrationTest annotation will replace it [2.31].
Tests annotated with @QuarkusIntegrationTest will run against whatever the output
of the build was: an executable jar, native image, or container image. The class annotat-
ed with @QuarkusIntegrationTest will run in the JVM but the output of the build will
be run in a separate process.
Note: @NativeImageTest is
still used in these examples
Summary
because the samples gen-
Quarkus draws many parallels to Spring. As this chapter shows, anyone familiar with erated with code.quarkus.
Spring should understand many of the concepts behind Quarkus and be able to be- io at the time of this book’s
come productive quickly. The main difference is and will continue to be the number of writing still used it.
optimizations done at build time instead of runtime. This difference will continue as you
move forward into further chapters in this book.

References
[2.1] “Quarkus Tools for Visual Studio Code”: https://marketplace.visualstudio.com/
items?itemName=redhat.vscode-quarkus
[2.2] “JetBrains IntelliJ IDEA Ultimate Edition Quarkus Tooling”:
https://www.jetbrains.com/help/idea/quarkus.html
[2.3] “Quarkus Tools for IntelliJ plugin”:
https://plugins.jetbrains.com/plugin/13234-quarkus-tools
[2.4] “Quarkus Tools JBoss Tools”: https://tools.jboss.org/features/quarkus.html
[2.5] “Quarkus Tools on Eclipse Marketplace”:
https://marketplace.eclipse.org/content/quarkus-tools
[2.6] “Spring Boot Starters”: https://docs.spring.io/spring-boot/docs/current/refer-
ence/htmlsingle/#using-boot-starter
[2.7] “Quarkiverse”: https://github.com/quarkiverse/quarkiverse/wiki
[2.8] “Quarkus Extension for Spring Boot Properties”:
https://quarkus.io/guides/spring-boot-properties

Quarkus for Spring Developers | 43

 Chapter 2 – Getting Started with Quarkus

[2.9] “Quarkus Extension for Spring Cache”: https://quarkus.io/guides/spring-cache

[2.11] “Quarkus Extension for Spring Dependency Injection”:

https://quarkus.io/guides/spring-di
[2.12] “Quarkus Extension for Spring Data JPA”:
https://quarkus.io/guides/spring-data-jpa
[2.13] “Quarkus Extension for Spring Data REST”:
https://quarkus.io/guides/spring-data-rest
[2.14] “Quarkus Extension for Spring Scheduled”: https://quarkus.io/guides/
spring-scheduled
[2.15] “Quarkus Extension for Spring Security”: https://quarkus.io/guides/spring-security
[2.16] “Quarkus Extension for Spring Web”: https://quarkus.io/guides/spring-web
[2.17] “Red Hat’s migration toolkit for applications”:
https://developers.redhat.com/products/mta
[2.18] “Quarkus + Spring Cheat Sheet”:
https://developers.redhat.com/cheat-sheets/quarkus-spring-cheat-sheet
[2.19] “Apache Maven Bill of Materials (BOM) POMs”:
https://maven.apache.org/guides/introduction/introduction-to-dependen-
cy-mechanism.html#bill-of-materials-bom-poms
[2.20] “Apache Maven: Introduction to the POM”:
https://maven.apache.org/guides/introduction/introduction-to-the-pom.html
[2.21] “Apache Maven: Importing Dependencies”:
https://maven.apache.org/guides/introduction/introduction-to-dependen-
cy-mechanism.html#Importing_Dependencies

[2.23] “Contexts and Dependency Injection for Java 2.0”:

https://docs.jboss.org/cdi/spec/2.0/cdi-spec.html
[2.24] “ArC: Quarkus Dependency Injection”:
https://quarkus.io/blog/quarkus-dependency-injection
[2.25] “Quarkus: Building a Native Executable”:
https://quarkus.io/guides/building-native-image
[2.26] “Resident Set Size”: https://en.wikipedia.org/wiki/Resident_set_size
[2.27] “JUnit 5”: https://junit.org/junit5
[2.28] “Mockito”: https://site.mockito.org
[2.29] “REST-assured”: https://rest-assured.io
[2.30] “Quarkus Native Executable Testing Guide”:
https://quarkus.io/guides/getting-started-testing#native-executable-testing
[2.31] “Using @QuarkusIntegrationTest”:
https://quarkus.io/guides/getting-started-testing#quarkus-integration-test

Quarkus for Spring Developers | 44

Chapter 3

RESTful Applications
Eric Deandrea

Web applications make up a large portion of today’s application landscape. Applications

communicate with each other via the web, specifically over the HTTP protocol, and
are designed using RESTful APIs. A RESTful web application responds to HTTP
requests following standard HTTP constructs and sends responses primarily textual
in representation, often JSON. This chapter examines web applications, and more

Quarkus and Spring when building such applications.

Both Quarkus and Spring have built-in support for building RESTful applications.
Application development in each technology is similar from a conceptual stand-
point. A developer in each framework constructs classes containing methods
representing RESTful resources or endpoints. These methods additionally declare
specific input and output parameters. Developers place annotations on these
classes and methods describing how to match an incoming HTTP request to a single
method within a single class. Some typical constraints used to match a request
include:

• HTTP method
• For example, GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.
• URI path
• For example, in the URL https://www.somewhere.com/api/resources/1,
/api/resources/1 is the path.
• Query parameters
• For example, in the URL https://www.somewhere.com/api/resources/
1?param1=value&param2=value, there are two query parameters, param1
and param2.
• Media types
• Also known as content negotiation, media type headers present in the HTTP
request signify the request body’s format (Content-Type request header)
and what response formats the client can accept (Accept request header and
Content-Type response header).

A RESTful Quarkus application uses JAX-RS (Jakarta RESTful Web Services [3.1],
formerly known as the Java API for RESTful Web Services) for defining endpoints.
This specification was introduced in Java SE 5 and later became an official part of

an implementation. For Quarkus, the implementation is RESTEasy [3.2]. For the

most part, the internals of RESTEasy are hidden from Quarkus developers.

A Quarkus developer creates resource classes using APIs from the JAX-RS speci-
controller classes, or more
restcontroller classes, which have their own set of standards for rep-
resenting RESTful concepts. Developers familiar with one can quickly become familiar
with the other.

Quarkus for Spring Developers | 45

 Chapter 3 – RESTful Applications

There are nevertheless a few differences when using RESTEasy in Quarkus versus with-
in a Java EE orJakarta EE application:

Application class. Quarkus will automatically cre-

ate and supply an Application subclass.
• Only a single JAX-RS application is supported within a JVM. Quarkus supports the
deployment of only a single JAX-RS application, in contrast to JAX-RS running in a
standard servlet container, where multiple JAX-RS applications could be deployed.
• All JAX-RS resources are treated as CDI beans by default and are scoped as CDI
Singletons.

Underlying Runtime
One fundamental difference between Quarkus and Spring is the choice of the underly-
ing runtime for building RESTful endpoints and its impact on development libraries and

Spring MVC [3.3], adopted this runtime early on.

As mentioned in Chapter 1, reactive frameworks and servers have emerged to support

the event-loop thread model. Spring had to build a mostly new web framework, called
Spring WebFlux [3.4], to support the new architecture. Although WebFlux reused
pieces across modules within the framework, the set of development libraries, the
styles, and even the documentation for Spring MVC and Spring WebFlux are different
and separated. A developer needs to decide upon project creation which framework to
use and cannot mix and match within the same application, never mind within the same
class. Additionally, a developer building a custom Spring Boot Starter interacting with
the web layer may also need to support two different versions of the same functional-
ity. This duplication of logic is not always trivial to implement.

Quarkus JAX-RS applications using the RESTEasy extension use the Eclipse Vert.x reactive
event-loop engine as the default runtime. Quarkus manages a few I/O threads (sometimes
called event-loop threads) to handle incoming HTTP requests. Additionally, Quarkus auto-
matically moves the execution of any JAX-RS resource class methods onto a separate work-
The RESTEasy extension
er thread, enabling a developer to mix and match blocking and reactive programming styles
is also known as RESTEasy
and frameworks within the same resource class. Figure 3.1 shows a high-level overview.
Classic or Classical
RESTEasy.

Quarkus for Spring Developers | 46

 Chapter 3 – RESTful Applications

Quarkus developers can also use the RESTEasy Reactive extension instead of the
RESTEasy extension. This extension is a drop-in replacement for the RESTEasy Classic
extension in most cases, achieving maximum throughput by handling each HTTP re-
quest on the I/O thread rather than moving to a worker thread. This approach is similar
to how Spring WebFlux uses threads. Figure 3.2 shows a high-level overview.

Using the RESTEasy Reactive extension, a developer needs to ensure that resource
class methods do not perform blocking work, just as with Spring WebFlux. A developer
can add the @Blocking annotation to a resource class method to signal that the meth-
od performs blocking work. In that case, Quarkus will execute the method on a separate
worker thread, similar to how the RESTEasy Classic extension works.
Performance using RESTEasy Reactive is far better, even when using the @Blocking
annotation, due to the tight integration between RESTEasy Reactive and Eclipse Vert.x.
Like RESTEasy Classic, developers can mix and match blocking and reactive program-
ming styles within the same resource class. Benchmarks have shown that a RESTEasy
Reactive endpoint using @Blocking still achieves around 50% higher throughput than
the same method using RESTEasy Classic [3.5].

Reactive Libraries
Developers building Spring WebFlux applications are most likely familiar with the Mono
and Flux reactive types provided by Project Reactor [3.6]. SmallRye Mutiny [3.7] is the
reactive library used by Quarkus, providing APIs conceptually similar to the ones found
in Project Reactor. In fact, Mutiny and Project Reactor share a lot of common code.
Mutiny is an intuitive, event-driven, reactive programming library for Java, allowing de-
velopers to express and compose asynchronous actions. Mutiny offers two types: Uni
for asynchronous actions providing either no result or a single value result and Multi to
provide multi-item streams with backpressure [3.10]. SmallRye Mutiny is part of
the SmallRye project [3.8]
Both types are lazy and follow a subscription pattern: Computation starts only when there
and an implementation of
is an actual need for it, known as a subscription. Both Uni and Multi expose event-driven
the Eclipse MicroProfile
APIs, where a developer expresses what to do upon receiving a given event (i.e., success,
Reactive Streams
failure, etc.). Additionally, Multi implements a Reactive Streams [3.11] Publisher and
Operator [3.9].
implements the Reactive Streams backpressure mechanism. Uni does not implement
Publisher, as the Uni subscription is enough to indicate interest in the result it
may provide.

Quarkus for Spring Developers | 47

 Chapter 3 – RESTful Applications

Both Uni and Multi

from Quarkus and provide bridges to imperative constructs. For example, a Multi can
be transformed into an Iterable and vice-versa. A Uni or Multi can also be convert-
ed to and from RxJava [3.12] and Project Reactor types.

HTTP Method

that indicate the desired action to be performed on a resource. Spring and Quarkus

a given method within a class. Furthermore, the JAX-RS annotations denote only the
HTTP method, whereas the Spring annotations have other metadata associated with
them. Discussion of this other metadata follows in the next section.

Table 3.1 outlines some common Quarkus and Spring HTTP method annotations used
in RESTful applications.

Quarkus Spring
@GET @GetMapping
@POST @PostMapping
@PUT @PutMapping Note: The semantics around
@DELETE @DeleteMapping
which HTTP method to use
in various circumstances is
@PATCH @PatchMapping
outside this book’s scope.
@HEAD @RequestMethod(method = RequestMethod.HEAD)
@OPTIONS @RequestMethod(method = RequestMethod.OPTIONS)

The HEAD and OPTIONS HTTP methods do not have their own Spring annotations.
Spring’s general-purpose @RequestMethod annotation handles these cases.

Routing HTTP Requests

As mentioned previously, both JAX-RS and Spring provide annotations to map an
incoming HTTP request to a single method in a single class. Table 3.2 outlines some

annotations.

Quarkus Spring Annotation Description

location
@Path @RequestMapping Class URI base path for all other URI paths
handled by methods in the class.

@Path Preferred: path Method

attribute of the Spring will be appended to the class level.
HTTP method anno-
tation from Table 3.1
Supported: path
attribute of the Spring
@RequestMapping
annotation
@Produces produces attribute of Class Output type produced by all resource
@RequestMapping methods (i.e., the Accept header of the
request and the Content-Type header
of the response).

Quarkus for Spring Developers | 48

 Chapter 3 – RESTful Applications

@Produces produces attribute Method Output type produced by a resource

of the HTTP method method (i.e., the Accept header of the
annotation used from request and the Content-Type header
Table 3.1 of the response). Overrides anything

@Consumes consumes attribute of Class Media type consumed by all resource

@RequestMapping methods (i.e., the Content-Type header
of the request).
@Consumes consumes attribute Method Media type consumed by a resource
of HTTP method method (i.e., the Content-Type header
annotation used from of the request). Overrides anything
Table 3.1
@PathParam @PathVariable Method Variable in the URI path
parameter (i.e., /path/{variable}).
@QueryParam @RequestParam Method Query parameter.
parameter
@FormParam @RequestParam Method Form parameter.
parameter
@HeaderParam @RequestHeader Method Header value.
parameter
@CookieParam @CookieValue Method Cookie value.
parameter
@MatrixParam @MatrixVariable Method Matrix parameter.
parameter
N/A. Just include @RequestBody Method Request body.
the object in the parameter
method signature
@Context [3.13] N/A; just include the Method Used to inject contextual, request-spe-
object in the method parameter
signature [3.14] [3.15]

Both Quarkus and Spring [3.16] [3.17] methods have many potential return values that a
developer can specify. Table 3.3 lists some common ones.

Quarkus Spring Description

Response HttpEntity<>, Return a value specifying the
ResponseEntity<> full HTTP response, including
headers, response status, and
(potentially) a body.
void void No response body.
Publisher<>, Publisher<>, Produce a result asynchronously.
CompletionStage<>, Callable<>,
CompletableFuture<> ListenableFuture<>,
DeferredResult<>,
CompletionStage<>,
CompletableFuture<>
Publisher<>, SseEmitter, Emit server-sent events.
Multi<> Flux<ServerSentEvent>
Uni<> Mono<> Reactive type; provide an empty
or single-value result.
Multi<> Flux<> Reactive type; provide multi-item
streams with backpressure support.
Any other object Any other object Return a value converted and
written to the response (i.e.,
marshaled to JSON).

Quarkus for Spring Developers | 49

 Chapter 3 – RESTful Applications

Building RESTful Endpoints

The best way to highlight similarities and differences between Quarkus and Spring
is to show a few examples in each technology. All examples showcase the following
use cases:

• HTTP GET to /fruits retrieves all available fruits as JSON.

• HTTP GET to /fruits/{name} retrieves a single fruit denoted by the path
variable {name}. Returns 404 (Not Found) if no such fruit is found.
• HTTP POST to /fruits, passing valid JSON representing a fruit, returns all
available fruits as JSON. Passing invalid JSON results in an HTTP return status
of 400 (Bad Request).
• HTTP DELETE to /fruits/{name} deletes a single fruit denoted by the path
variable {name}. Returns an HTTP status of 204 (No Content).
• HTTP GET to /fruits/error returns an HTTP status of 500 (Internal
Server Error). This example showcases error handling.
The complete examples in the following listings can be found in this chapter’s GitHub
repository [3.18]:

• Spring MVC: Inside the chapter-3/chapter-3-spring-rest-json project

• Spring WebFlux: Inside the
json project
• Quarkus: Inside the chapter-3/chapter-3-quarkus-rest-json project
Remember from earlier that a Spring developer needs to choose whether to use
blocking or non-blocking/reactive architecture when creating the project. In
Quarkus, a developer can mix both styles within the same class. Not shown in each Note: The Quarkus resource
snippet is the injection of a FruitService bean or the Fruit class contents. The class used in the examples
contents of the Fruit class are nearly identical in all three examples. mixes blocking and reactive
types within the same class
In all the Spring examples, the class and method annotations are identical. The method
simply to illustrate that it can
return types, however, are different. The Spring MVC example returns standard objects
be done. Besides the server-
and a ResponseEntity, but the Spring WebFlux version returns Mono and Flux reac-
sent event endpoint, there
tive types. The FruitService class’s implementation (not shown here but found in the
was no compelling reason
examples repository) is also different in both versions. On the other hand, the Quarkus
dictating which endpoints
code combines reactive asynchronous and blocking synchronous methods within the
were implemented as blocking
same class.
versus reactive. Additionally,
Both Quarkus and Spring support Jackson [3.19] and Jakarta JSON Binding none of the reactive end-
(JSON-B) [3.20] for marshaling and unmarshaling JSON to and from Java objects. points utilize the @Blocking
Spring defaults to Jackson, whereas Quarkus forces a developer to make a con- annotation because the
scious choice. When using Jackson, both frameworks provide a default Jackson examples are trivial and
ObjectMapper don’t perform blocking
bean override mechanisms. work. The examples in
Chapter 4 will use the
@Blocking annotation.

need to be registered. Quarkus does most of this work automatically by analyzing

the annotated resource class methods at build time. In the majority of the follow-
ing examples, Quarkus knows that the Fruit class needs to be included in a native
executable because the Fruit class is input to or output from the list, add, and
deleteFruit methods.

Quarkus for Spring Developers | 50