Forem: Thomas Vitale

Spring Native: Getting started with GraalVM native images

Thomas Vitale — Wed, 12 May 2021 17:49:38 +0000

The Spring Native project provides support for packaging Spring applications as native images using GraalVM.

Compared to JVM executables, native images have faster startup times (< 100 ms) and lower memory consumption. However, building a native image requires more time than a JVM-based one.

The project is still in beta but already supports most of the Spring portfolio modules, including Spring Framework, Spring Boot, Spring Security, and Spring Cloud.

Its features make it a good fit for building serverless applications with Spring Cloud Function and deploying them to a platform like Azure Functions, AWS Lambda, or Knative.

This article will guide you through the building of a Spring Boot application compiled to a native executable with Spring Native. You can find the source code on GitHub.

Bootstrapping an application with Spring Native

You can add Spring Native to your application when bootstrapping the project from Spring Initializr.

The generated project will contain a dependency on the Spring Native project and the Spring AOT plugin used to compile your application source code to native executable while improving compatibility and footprint.

The build.gradle file looks as follows.

plugins {
    id 'org.springframework.boot' version '2.4.3'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'java'
    id 'org.springframework.experimental.aot' version '0.9.0'
}

group = 'com.thomasvitale'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

repositories {
    maven { url 'https://repo.spring.io/release' }
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-webflux'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'io.projectreactor:reactor-test'
}

test {
    useJUnitPlatform()
}

bootBuildImage {
    builder = 'paketobuildpacks/builder:tiny'
    environment = ['BP_NATIVE_IMAGE': 'true']
}

You can build a native image out of your application using the familiar Spring Boot plugin (Gradle or Maven) and its embedded Cloud Native Buildpacks support. The choice between JVM and GraalVM images is defined by the BP_NATIVE_IMAGE property in the bootBuildImage task, which comes pre-configured when you use Spring Initialzr.

Defining a REST endpoint with Spring WebFlux

Let's define a REST endpoint with Spring WebFlux so that we can test the application.

In the SpringNativeGraalvmApplication class generated by the Initializr, you can add a REST endpoint using a router function or a @RestController-annotated class. Let's go with the former option.

package com.thomasvitale.demo;

import reactor.core.publisher.Mono;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerResponse;

import static org.springframework.web.reactive.function.server.RouterFunctions.route;
import static org.springframework.web.reactive.function.server.ServerResponse.ok;

@SpringBootApplication
public class SpringNativeGraalvmApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringNativeGraalvmApplication.class, args);
    }

    @Bean
    RouterFunction<ServerResponse> routes() {
        return route()
                .GET("/", request -> ok().body(Mono.just("Spring Native and Beyond!"), String.class))
                .build();
    }
}

Then, in the SpringNativeGraalvmApplicationTests class generated by the Initializr, you can add an integration test for the REST endpoint.

package com.thomasvitale.demo;

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.AutoConfigureWebTestClient;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.reactive.server.WebTestClient;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureWebTestClient
class SpringNativeGraalvmApplicationTests {

    @Autowired
    private WebTestClient webClient;

    @Test
    void whenGetBooksThenReturn() {
        webClient
                .get().uri("/")
                .exchange()
                .expectStatus().is2xxSuccessful()
                .expectBody(String.class).isEqualTo("Spring Native and Beyond!");
    }
}

Running the application as an executable JAR

The Spring Native dependency in your project will optimize the application startup time and memory consumption, thanks to the Spring AOT plugin, even when running it as an executable JAR. Let's try it out.

First, open a Terminal window, navigate to the root folder of your project, and run the following command.

$ ./gradlew bootRun

The application will start up faster than its corresponding version without Spring AOT. Let's try calling the REST endpoint.

$ curl http://localhost:8080
Spring Native and Beyond!

Running the application as a native image

Now, let's try building and running a native image leveraging Spring Native with GraalVM.

Building a native image is very straightforward with the Spring Boot plugin. Make sure your Docker Engine is running, and then execute the following command. Be aware that it will take a few minutes, very much depending on your laptop CPU and memory characteristics.

$ ./gradlew bootBuildImage

The result will be a spring-native-graalvm:0.0.1-SNAPSHOT image that you can run with Docker.

$ docker run --name spring-native-graalvm -p 8080:8080 spring-native-graalvm:0.0.1-SNAPSHOT

Applications with Spring Native typically start in less than 100 ms, depending on your machine's available resources.

Once again, let's call the REST endpoint to ensure the application is still working when run as a native image.

$ curl http://localhost:8080
Spring Native and Beyond!

It does. Good job!

Conclusion

In this article, I went through how to quickly bootstrap a Spring Boot application and compile it to a native executable using Spring Native and GraalVM.

For more information on the Spring Native project and to follow its roadmap, you can refer to the official documentation.

If you're interested in cloud native development with Spring Boot and Kubernetes, check out my book Cloud Native Spring in Action.

Did you like this article? Check out my personal blog for more: thomasvitale.com. I write about Enterprise Java, Spring, Keycloak and Application Security.

New Book: Cloud Native Spring in Action - With Spring Boot and Kubernetes

Thomas Vitale — Sun, 06 Sep 2020 14:25:44 +0000

I'm thrilled to announce that my new book, Cloud Native Spring in Action (Manning Publishing), is now available in early access.

In the last few years, it has become clear that many organizations had to choose the cloud to keep the business alive. A traditional approach based on application servers and on-premise “snowflake” infrastructure can hardly ensure the requirements of modern applications: scalability, resilience, zero-downtime, reliability, short feedback cycles, and frequent releases. To fully leverage the cloud capabilities, it wasn’t enough to move traditional applications to the new infrastructure. Something else was needed. Applications had to become cloud native.

This book will take you on an exciting journey in the cloud native world from development to production using the latest features from Spring, Docker, and Kubernetes. You’ll have the chance to apply every new idea along the journey by progressively building a full cloud native system for an online bookshop. By the end of the book, you’ll have it deployed to a Kubernetes cluster in a public cloud.

The book is divided into four parts. Part 1 will guide you through the cloud native landscape, defining what it means for an application to be cloud native, and establishing tools, technologies, and patterns you’ll bring on your journey.

Part 2 will get you started with the fundamentals of cloud native development. You’ll work with RESTful Spring application services and data persistence, understand how to manage configuration across environments, define automation for your continuous integration process, learn how the Docker containerization works, and finally deploy your apps to a local Kubernetes cluster.

In Part 3, your journey gets to a whole new level. You’ll move from a single app to a distributed system in the cloud. You’ll learn about service discovery, load balancing, scalability, and resilience. You’ll then explore the features of event-driven architecture and secure your system with authentication, authorization, and encryption.

In Part 4, you’ll ensure the observability of your applications, dealing with logging, tracing, and monitoring. Finally, you’ll get to the long wished for destination: production. You’ll learn how to deploy your application to a Kubernetes cluster in a public cloud, and automate the delivery and deployment process. A new journey starts in production. You’ll get familiar with the next steps in your cloud native adventure and learn some tips on migrating your existing applications.

If you start reading the book, please let me know your thoughts on Twitter or in the Manning liveBook discussion forum about what's been written so far and what you'd like to see in the rest of the book. Your feedback will be invaluable in improving Cloud Native Spring in Action.

Quarkus - Develop Your First Supersonic Enterprise Java Application

Thomas Vitale — Mon, 18 Nov 2019 21:47:26 +0000

In this article, we're going to getting started with our first supersonic Quarkus application. We will develop a RESTful application using the familiar JAX-RS and CDI APIs, learn how to run it in a Quarkus environment and see how to test it.

Recently, Quarkus 1.0 has been announced, an important milestone for the Java community.

Quarkus is an Open Source stack to write Java applications offering unparalleled startup time, memory footprint and developer experience. It offers familiar programming models and APIs (Hibernate, JAX-RS, Eclipse Vert.x, Apache Camel, Eclipse MicroProfile, Spring API compatibility and more).

In this article, we're going to getting started with our first Quarkus application, more specifically a RESTful application using the familiar JAX-RS and CDI APIs from Jakarta EE. We will also see how to test our application. You can find the source code on my GitHub.

1. Prerequisites

To follow along with this tutorial, you will need:

JDK 8 or 11+
an IDE
Apache Maven 3.5.3+
Gradle 5.5.0+

I will use Gradle to build the application, but you're free to use Maven. Be aware that using Gradle with Quarkus is preview functionality. It might not support all the possible scenarios, but it works well enough for the application we are going to build in this tutorial.

2. Bootstrapping a Quarkus Application

The application that we are going to develop is a fictitious RESTful application for a library, which exposes an endpoint to fetch all the available books.

We can quickly bootstrap a Quarkus application in two ways: leveraging Maven from the command line or using the convenient UI-based application generator.

In both cases, we need to provide some important information:

group and artifact ids
build tool (Maven or Gradle)
extensions (i.e. dependencies).

The RESTeasy JAX-RS extension is included by default, while we need to include the RESTeasy JSON-B extension explicitly.

Using the Maven generator, we can also specify a resource class to be automatically generated and configured for JAX-RS and an optional path.

Let's have a look at both the options.

Using Maven to generate a Quarkus application

Let's open a Terminal window and run the following command to generate an application which will use Maven as a built tool:

mvn io.quarkus:quarkus-maven-plugin:1.0.0.CR1:create \
    -DprojectGroupId=com.thomasvitale \
    -DprojectArtifactId=quarkus-getting-started \
    -DclassName="com.thomasvitale.library.BookResource" \
    -Dpath="/books" \
    -Dextensions="resteasy-jsonb"

Should we prefer to use Gradle as the tool to build our application, we can do so in this way (notice the extra buildTool parameter):

mvn io.quarkus:quarkus-maven-plugin:1.0.0.CR1:create \
    -DprojectGroupId=com.thomasvitale \
    -DprojectArtifactId=quarkus-getting-started \
    -DclassName="com.thomasvitale.library.BookResource" \
    -Dpath="/books" \
    -Dextensions="resteasy-jsonb" \
    -DbuildTool=gradle

Using the UI-based initializer to generate a Quarkus application

In alternative to Maven, we can go to code.quarkus.io and create our Quarkus application from a convenient user interface where to insert all the details about the project, the build tool and the extensions we need. Are you familiar with the Spring Initializr? This tool works in the same way.

3. The Structure of a Quarkus Application

The basic structure of the generated Quarkus application follows the Maven standard. On top of that, there are some extra features.

As defined in the previous section, we can notice that the BookResource class has been generated in src/main/java, together with test classes in src/test/java and src/native-test/java. The first tests are run in JVM mode, the second in native mode. The BookResource is exposed to the /books endpoint and accessible by default on http://localhost:8080.

In src/main/docker, we can find example Dockerfile files to run our application in a container, either in JVM or native mode.

To easily build the application, a Quarkus plugin is applied (either for Maven or Gradle), and a Quarkus BOM is imported to define which version we want to use throughout the application.

In the dependencies section of our gradle.build file (or pom.xml if using Maven), we can find the RESTeasy extensions that we defined for the generator, plus JUnit5 and RestAssured to test our application both in JVM and native mode.

dependencies {
    implementation 'io.quarkus:quarkus-resteasy-jsonb'
    implementation 'io.quarkus:quarkus-resteasy'

    testImplementation 'io.quarkus:quarkus-junit5'
    testImplementation 'io.rest-assured:rest-assured'

    nativeTestImplementation 'io.quarkus:quarkus-junit5'
    nativeTestImplementation 'io.rest-assured:rest-assured'
}

4. JVM vs Native Mode

In the previous section, we mentioned a few times JVM and native modes. Some clarification is in order.

The JVM mode exploits the standard JVM. It tailors the runtime such that it includes only what the application actually needs, removing all the extra dynamics of a standard enterprise runtime. This results in lower memory consumption, and a faster boot phase and first response time comparing to a traditional enterprise application.

The Quarkus JVM mode is already a significant advantage over the traditional enterprise Java application. In reality, what makes Quarkus shines is its native mode. Quarkus has been designed around a container first philosophy, with native support for GraalVM and SubstrateVM. When using this mode, our applications are pre-built and compiled to native executables which start up almost immediately and are incredibly well-performant both in terms of time and memory consumption.

In this tutorial, we're going to run the application and its tests in JVM mode. In a future article, instead, we will see how the native mode works.

5. Implementing the REST API

Now, let's get started with the actual development phase. A BookResource class has been generated for us. It's time to implement some endpoints.

We're going to expose two endpoints:

/books returns the list of books available in the library;
/books/{id} returns the book having the specified id.

@Path("/books")
@Produces(MediaType.APPLICATION_JSON)
public class BookResource {

    @Inject
    BookService bookService;

    @GET
    public List<Book> getBooks() {
        return bookService.getBooks();
    }

    @GET
    @Path("{id}")
    public Book getBookById(@PathParam("id") Long id) {
        return bookService.getBookById(id);
    }
}

It's interesting to notice that, differently from vanilla JAX-RS as used in Jakarta EE, in Quarkus we don't need to define an Application class annotated with @ApplicationPath to enable the REST API. Also, by default, the resource class is configured as @ApplicationScoped. You can change the configuration by using the familiar annotations from CDI to define the scope of a class.

The functionality to retrieve books is delegated to the BookService class, which is injected as a CDI bean in BookResource. The service defines a static map to simulate a book repository.

@ApplicationScoped
public class BookService {

    private static Map<Long, Book> bookRepository = new ConcurrentHashMap<>();

    static {
        bookRepository.put(1L, new Book(1L, "Harry Potter"));
        bookRepository.put(2L, new Book(2L, "The Lord of The Rings"));
        bookRepository.put(3L, new Book(3L, "The Golden Compass"));
    }

    List<Book> getBooks() {
        return new ArrayList<>(bookRepository.values());
    }

    Book getBookById(Long id) {
        return bookRepository.get(id);
    }
}

Finally, the Book class is a POJO.

public class Book {
    private Long id;
    private String title;

    Book(Long id, String title) {
        this.id = id;
        this.title = title;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }
}

6. Running the Quarkus Application

It's time to run our Quarkus application for the first time. Ready for some supersonic subatomic deployment?

Let's open a Terminal window and run the command:

./gradlew assemble quarkusDev

If using Maven, we can run the command:

./mvnw compile quarkus:dev

The quarkusDev task (or quarkus:dev when using Maven) runs Quarkus in development mode. The main feature of this mode is the hot deployment with background compilation, which means we can modify our source files (both Java classes and resources) while the application is running and the changes will automatically take effect.

When running Quarkus in development mode, the debug mode is enabled by default, listening to port 5005 without suspending the JVM.

Now, let's verify if it's working. From the Terminal, let's call our brand new REST API:

curl http://localhost:8080/books/1

This is the result:

{"id":1,"title":"Harry Potter"}

Great, it's working!

7. Testing

We manually verified that our REST endpoints are correctly exposed to our Quarkus application, but it's better to write some autotests.

Let's use the BookResourceTest class in src/test/java that has been already generated for us and let's write a couple of tests for the two endpoints exposed by the BookResource class. As mentioned before, we're going to use JUnit5 and RestAssured to write our tests.

@QuarkusTest
public class BookResourceTest {

    @Test
    void testGetBooks() {
        given()
            .when().get("/books")
            .then()
                .statusCode(200)
                .body("id", hasItems(1, 2, 3));
    }

    @Test
    void testGetBookById() {
        given()
          .pathParam("id", 1)
          .when().get("/books/{id}")
          .then()
             .statusCode(200)
             .body("id", is(1));
    }
}

The @QuarkusTest annotation makes sure that the application is running before starting the tests.

Tests can be run either directly from our IDE or our build tool. If we use Gradle:

./gradlew test

With Maven, instead, we run the following command:

./mvnw test

Super! We now also have autotests ensuring that our application works as intended.

Conclusion

In this article, we have had a first look at Quarkus. We have explored the different ways to generate a basic Quarkus project and went through its structure to identify all the main parts of the application. Then, we have implemented a simple RESTful application leveraging the familiar JAX-RS and CDI APIs for enterprise Java and learned how to run a Quarkus application in development mode. Finally, we have ensured that the application has been implemented correctly by writing some autotests and learned how to run them.

Quarkus is definitely here to stay, and I'm looking forward to seeing how it will change the enterprise Java application landscape. And you? Let me know what you think about Quarkus and if you're considering starting using it for your future projects.

Did you like this article? Check out my personal blog for more: thomasvitale.com. I write about Enterprise Java, Spring, Keycloak and Application Security.