GraalVM has been around for quite a while, steadily making big waves in OpenJDK community (looking at you, JEP 483: Ahead-of-Time Class Loading & Linking). It is wonderful piece of JVM engineering that gave birth to new generation of the frameworks like Quarkus, Helidon and Micronaut, just to name a few.
But what about the old players, like Apache CXF? A large number of applications and services were built on top of it, could those benefit from GraalVM, and particularly native image compilation? The answer to this question used to vary a lot, but thanks to steady progress, GraalVM strives to make it as frictionless as possible.
In today's post, we are going to build a sample Jakarta RESTful web service using Apache CXF and Jakarta XML Binding, and compile it to native image with GraalVM Community 21.0.2+13.1.
Let us start off with the data model, which consists of a single POJO, class Customer.
import jakarta.xml.bind.annotation.XmlRootElement;
@XmlRootElement(name = "Customer")
public class Customer {
private long id;
private String name;
public long getId() {
return id;
}
public void setId(long id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
}
The class CustomerResource, a minimal Jakarta RESTful web service implementation, exposes a few endpoints to manage Customers, for simplicity - the state is stored in memory.
import java.util.Collection;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.atomic.AtomicInteger;
import jakarta.ws.rs.DELETE;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.Response.Status;
@Path("/")
@Produces(MediaType.APPLICATION_XML)
public class CustomerResource {
private final AtomicInteger id = new AtomicInteger();
private final Map<Long, Customer> customers = new HashMap<>();
@GET
@Path("/customers")
public Collection<Customer> getCustomers() {
return customers.values();
}
@GET
@Path("/customers/{id}")
public Response getCustomer(@PathParam("id") long id) {
final Customer customer = customers.get(id);
if (customer != null) {
return Response.ok(customer).build();
} else {
return Response.status(Status.NOT_FOUND).build();
}
}
@POST
@Path("/customers")
public Response addCustomer(Customer customer) {
customer.setId(id.incrementAndGet());
customers.put(customer.getId(), customer);
return Response.ok(customer).build();
}
@DELETE
@Path("/customers/{id}")
public Response deleteCustomer(@PathParam("id") long id) {
if (customers.remove(id) != null) {
return Response.noContent().build();
} else {
return Response.status(Status.NOT_FOUND).build();
}
}
}
The last piece we need is to have running web container to host the CustomerResource service. We are going to use Eclipse Jetty but any other HTTP transport supported by Apache CXF will do the job.
import org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
import org.apache.cxf.jaxrs.lifecycle.SingletonResourceProvider;
public class Server {
public static org.apache.cxf.endpoint.Server create() {
final JAXRSServerFactoryBean sf = new JAXRSServerFactoryBean();
sf.setResourceClasses(CustomerResource.class);
sf.setResourceProvider(CustomerResource.class, new SingletonResourceProvider(new CustomerResource()));
sf.setAddress("http://localhost:9000/");
return sf.create();
}
public static void main(String[] args) throws Exception {
var server = create();
server.start();
}
}
Literally, this is all we need from the implementation perspective. The Apache Maven dependencies list is limited to handful of those:
<dependencies> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http</artifactId> <version>4.0.5</version> </dependency> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-jetty</artifactId> <version>4.0.5</version> </dependency> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-frontend-jaxrs</artifactId> <version>4.0.5</version> </dependency> <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> <version>1.5.7</version> </dependency> </dependencies>
Cool, so what is next? The GraalVM project provides Native Build Tools to faciliate building native images, including dedicated Apache Maven plugin. However, if we just add the plugin into the build, the resulting native image won't be functionable, even if the build succeeds:
$./target/cxf-jax-rs-graalvm-server
Exception in thread "main" java.lang.ExceptionInInitializerError
at java.base@21.0.2/java.lang.Class.ensureInitialized(DynamicHub.java:601)
at com.example.jaxrs.graalvm.Server.create(Server.java:27)
at com.example.jaxrs.graalvm.Server.main(Server.java:35)
at java.base@21.0.2/java.lang.invoke.LambdaForm$DMH/sa346b79c.invokeStaticInit(LambdaForm$DMH)
Caused by: java.util.MissingResourceException: Can't find bundle for base name org.apache.cxf.jaxrs.Messages, locale en
at java.base@21.0.2/java.util.ResourceBundle.throwMissingResourceException(ResourceBundle.java:2059)
at java.base@21.0.2/java.util.ResourceBundle.getBundleImpl(ResourceBundle.java:1697)
at java.base@21.0.2/java.util.ResourceBundle.getBundleImpl(ResourceBundle.java:1600)
at java.base@21.0.2/java.util.ResourceBundle.getBundle(ResourceBundle.java:1283)
at org.apache.cxf.common.i18n.BundleUtils.getBundle(BundleUtils.java:94)
at org.apache.cxf.jaxrs.AbstractJAXRSFactoryBean.<clinit>(AbstractJAXRSFactoryBean.java:69)
... 4 more
Why is that? GraalVM operates under closed world assumption: all classes and all bytecodes that are reachable at run time must be known at build time. Since a majority of the frameworks, Apache CXF included, does not comply with such assumptions, GraalVM needs some help: tracing agent. The way we are going to let GraalVM capture all necessary metadata is pretty straightforward:
- add test cases which exercise the service logic (more is better)
- run test suite using tracing agent instrumentation
- build the native image using the metadata collected by the tracing agent
If that sounds like a plan to you, let us add the test case first:
import java.io.InputStream;
import java.io.IOException;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import jakarta.ws.rs.client.ClientBuilder;
import jakarta.ws.rs.client.Entity;
import jakarta.ws.rs.core.Response;
import static org.hamcrest.CoreMatchers.equalTo;
import static org.hamcrest.MatcherAssert.assertThat;
public class ServerTest {
private org.apache.cxf.endpoint.Server server;
@BeforeEach
public void setUp() {
server = Server.create();
server.start();
}
@Test
public void addNewCustomer() throws IOException {
var client = ClientBuilder.newClient().target("http://localhost:9000/customers");
try (InputStream in = getClass().getResourceAsStream("/add_customer.xml")) {
try (Response response = client.request().post(Entity.xml(in))) {
assertThat(response.getStatus(), equalTo(200));
}
}
}
@Test
public void listCustomers() {
var client = ClientBuilder.newClient().target("http://localhost:9000/customers");
try (Response response = client.request().get()) {
assertThat(response.getStatus(), equalTo(200));
}
}
@AfterEach
public void tearDown() {
server.stop();
server.destroy();
}
}
Awesome, with tests in place, we could move on and integrate Native Build Tools into our Apache Maven build. It is established practice to have a dedicated profile for native image since the process could take quite a lot of time (and resources):
<profiles>
<profile>
<id>native-image</id>
<activation>
<property>
<name>native</name>
</property>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
<extensions>true</extensions>
<version>0.10.2</version>
<executions>
<execution>
<goals>
<goal>compile-no-fork</goal>
</goals>
<phase>package</phase>
</execution>
</executions>
<configuration>
<agent>
<enabled>true</enabled>
<defaultMode>direct</defaultMode>
<modes>
<direct>config-output-dir=${project.build.directory}/native/agent-output</direct>
</modes>
</agent>
<mainClass>com.example.jaxrs.graalvm.Server</mainClass>
<imageName>cxf-jax-rs-graalvm-server</imageName>
<buildArgs>
<buildArg>--enable-url-protocols=http</buildArg>
<buildArg>--no-fallback</buildArg>
<buildArg>-Ob</buildArg>
</buildArgs>
<metadataRepository>
<enabled>false</enabled>
</metadataRepository>
<resourcesConfigDirectory>${project.build.directory}/native</resourcesConfigDirectory>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
It may look a bit complicated but fear not. The first thing to notice is that we configure tracing agent in the <agent> ... </agent> section. The captured metadata is going to be dumped into ${project.build.directory}/native/agent-output folder. Later on, the native image builder will refer to it as part of the <resourcesConfigDirectory> ... </resourcesConfigDirectory> configuration option. The profile is activated by the presence of native property.
Time to see each step in action! First thing first, run tests and capture the metadata:
$ mvn clean -Dnative test ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 6.977 s [INFO] Finished at: 2024-08-30T15:50:55-04:00 [INFO] ------------------------------------------------------------------------
If we list the content of the target/native folder, we should see something like that:
$ tree target/native/
target/native/
└── agent-output
├── agent-extracted-predefined-classes
├── jni-config.json
├── predefined-classes-config.json
├── proxy-config.json
├── reflect-config.json
├── resource-config.json
└── serialization-config.json
If curious, you could inspect the content of each file, since it is just JSON, but we are going to proceed to the next step right away:
$ mvn -Dnative -DskipTests package
GraalVM Native Image: Generating 'cxf-jax-rs-graalvm-server' (executable)...
========================================================================================================================
Warning: Could not resolve org.junit.platform.launcher.TestIdentifier$SerializedForm for serialization configuration.
Warning: Could not resolve org.junit.platform.launcher.TestIdentifier$SerializedForm for serialization configuration.
[1/8] Initializing... (5.7s @ 0.10GB)
Java version: 21.0.2+13, vendor version: GraalVM CE 21.0.2+13.1
Graal compiler: optimization level: b, target machine: x86-64-v3
C compiler: gcc (linux, x86_64, 9.4.0)
Garbage collector: Serial GC (max heap size: 80% of RAM)
2 user-specific feature(s):
- com.oracle.svm.thirdparty.gson.GsonFeature
- org.eclipse.angus.activation.nativeimage.AngusActivationFeature
------------------------------------------------------------------------------------------------------------------------
Build resources:
- 9.99GB of memory (64.5% of 15.49GB system memory, determined at start)
- 16 thread(s) (100.0% of 16 available processor(s), determined at start)
[2/8] Performing analysis... [*****] (31.2s @ 1.59GB)
12,363 reachable types (85.2% of 14,503 total)
21,723 reachable fields (63.2% of 34,385 total)
61,933 reachable methods (57.6% of 107,578 total)
3,856 types, 210 fields, and 2,436 methods registered for reflection
62 types, 69 fields, and 55 methods registered for JNI access
4 native libraries: dl, pthread, rt, z
[3/8] Building universe... (4.8s @ 1.85GB)
[4/8] Parsing methods... [**] (3.0s @ 1.16GB)
[5/8] Inlining methods... [***] (2.2s @ 1.35GB)
[6/8] Compiling methods... [*****] (25.4s @ 1.89GB)
[7/8] Layouting methods... [***] (6.2s @ 1.49GB)
[8/8] Creating image... [***] (7.5s @ 2.03GB)
32.41MB (49.57%) for code area: 38,638 compilation units
30.78MB (47.08%) for image heap: 325,764 objects and 152 resources
2.19MB ( 3.35%) for other data
65.38MB in total
...
========================================================================================================================
Finished generating 'cxf-jax-rs-graalvm-server' in 1m 26s.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 01:30 min
[INFO] Finished at: 2024-08-30T15:58:42-04:00
[INFO] ------------------------------------------------------------------------
And we should end up with a fully functional executable, let us make sure this is the case:
$ ./target/cxf-jax-rs-graalvm-server
Aug 30, 2024 4:03:22 PM org.apache.cxf.endpoint.ServerImpl initDestination
INFO: Setting the server's publish address to be http://localhost:9000/
16:03:22.987 [main] INFO org.eclipse.jetty.server.Server -- jetty-11.0.22; built: 2024-06-27T16:27:26.756Z; git: e711d4c7040cb1e61aa68cb248fa7280b734a3bb; jvm 21.0.2+13-jvmci-23.1-b30
16:03:22.993 [main] INFO o.e.jetty.server.AbstractConnector -- Started ServerConnector@5725648b{HTTP/1.1, (http/1.1)}{localhost:9000}
16:03:22.994 [main] INFO org.eclipse.jetty.server.Server -- Started Server@1f9511a6{STARTING}[11.0.22,sto=0] @24ms
16:03:22.994 [main] INFO o.e.j.server.handler.ContextHandler -- Started o.a.c.t.h.JettyContextHandler@375bd1b5{/,null,AVAILABLE}
If we open up another terminal window and run curl from the command line, we should be hitting the instance of our service and getting successful responses back:
$curl http://localhost:9000/customers -H "Content-Type: application/xml" -d @src/test/resources/add_customer.xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Customer>
<id>3</id>
<name>Jack</name>
</Customer>
All the credits go to GraalVM team! Before we wrap up, you might be asking yourself if this the only way? And the short answer is "no": ideally, you should be able to add Native Build Tools and be good to go. The GraalVM Reachability Metadata Repository is the place that enables users of GraalVM native image to share and reuse metadata for libraries and frameworks in the Java ecosystem. Sadly, Apache CXF is not there just yet ... as many others.
The complete project sources are available on Github.
I 🇺🇦 stand 🇺🇦 with 🇺🇦 Ukraine.
Posts
