# How to Build Fast, Memory-Efficient Java Native Executables with GraalVM

#programming #devto #java #softwareengineering

As a best-selling author, I invite you to explore my books on Amazon. Don't forget to follow me on Medium and show your support. Thank you! Your support means the world!

Let's talk about turning your Java application into a fast, lean, native executable. If you've ever waited for a Spring Boot app to start, or watched a microservice consume more memory than you'd like, you'll appreciate what this process offers. I want to show you how it's done, not with complex theory, but with clear steps and code you can use.

Think of your regular Java app. It runs on the Java Virtual Machine (JVM). This is fantastic for flexibility. The JVM loads classes as needed, optimizes code while it runs, and manages memory. But this comes at a cost: startup time and a baseline memory overhead. A native executable flips this model. It compiles your application, its dependencies, and a pared-down version of the runtime into a single binary file—like a program written in C or Go. This binary starts in milliseconds, not seconds, and uses a fraction of the memory.

The tool that makes this possible is GraalVM's native-image builder. However, this shift from "just-in-time" to "ahead-of-time" compilation has consequences. The builder has to analyze your entire application at build time to see what code is reachable. Anything it can't see, it throws away. This creates challenges with features that are dynamic by nature, like creating objects from string names or loading files from the classpath on the fly. We need to guide the compiler.

This is where technique comes in. We must adapt our code and configuration. It might sound like extra work, and initially, it is. But the payoff is substantial: applications that are perfect for containerized environments, serverless functions, or command-line tools where quick startup and small size are critical. Let me walk you through five essential methods to make this transition smooth and successful.

The first and most common hurdle is reflection. In a standard JVM, you can write Class.forName("MyService") and instantiate it, even if that class wasn't directly referenced elsewhere in your code. The JVM figures it out at runtime. The native image builder can't do that. It sees a string, not a class reference. If you don't explicitly tell it about MyService, that class won't be included in the final executable, and your code will crash.

You need to declare these dynamic elements. There are a few ways to do this, and using more than one is often necessary.

You can create configuration files. The builder will look for them in META-INF/native-image/. A file named reflect-config.json can list your classes.

[
  {
    "name": "com.myapp.service.UserService",
    "methods": [
      {"name": "<init>", "parameterTypes": [] },
      {"name": "findById", "parameterTypes": ["java.lang.Long"] }
    ]
  }
]

For more control, you can write a feature class. This is Java code that runs during the build process.

import org.graalvm.nativeimage.hosted.Feature;
import org.graalvm.nativeimage.hosted.RuntimeReflection;

public class MyReflectionFeature implements Feature {
    @Override
    public void beforeAnalysis(BeforeAnalysisAccess access) {
        try {
            Class<?> userClass = Class.forName("com.myapp.service.UserService");
            RuntimeReflection.register(userClass);
            RuntimeReflection.register(userClass.getDeclaredConstructors());
            RuntimeReflection.register(userClass.getDeclaredMethods());
        } catch (ClassNotFoundException e) {
            // Handle missing class
        }
    }
}

Frameworks like Quarkus or Spring Native simplify this further with annotations.

import io.quarkus.runtime.annotations.RegisterForReflection;

@RegisterForReflection(fields = true, methods = true)
public class UserDTO {
    private Long id;
    private String name;
    // getters and setters
}

The key is to audit your code and dependencies for reflection use. Libraries for JSON mapping (like Jackson), dependency injection, or ORMs use it heavily. You'll need to provide configuration for those classes too.

Getting the build right is your next step. You can use the native-image command directly, but for a real project, integrating it into your Maven or Gradle build is much better. It automates everything. Let's look at a Maven setup for a Spring Boot 3 application, which now has excellent native support.

<build>
    <plugins>
        <plugin>
            <groupId>org.graalvm.buildtools</groupId>
            <artifactId>native-maven-plugin</artifactId>
            <version>0.9.23</version>
            <executions>
                <execution>
                    <id>build-native</id>
                    <goals><goal>compile-no-fork</goal></goals>
                    <phase>package</phase>
                </execution>
            </executions>
            <configuration>
                <imageName>my-application</imageName>
                <buildArgs>
                    <!-- Enable essential features -->
                    <arg>--enable-https</arg>
                    <arg>--enable-http</arg>
                    <!-- Initialize key libraries at build time for speed -->
                    <arg>--initialize-at-build-time=org.slf4j.LoggerFactory</arg>
                    <!-- Choose a garbage collector suited for low memory -->
                    <arg>-H:+UseSerialGC</arg>
                    <!-- Set a maximum heap size -->
                    <arg>-H:MaxHeapSize=128m</arg>
                    <!-- Exclude a problematic library from build-time init -->
                    <arg>--initialize-at-run-time=com.example.unstablelib</arg>
                    <!-- Shrink the image size -->
                    <arg>--no-debug</arg>
                    <arg>--no-fallback</arg>
                </buildArgs>
            </configuration>
        </plugin>
    </plugins>
</build>

Running mvn -Pnative native:compile will start the process. It takes longer than a regular build—often several minutes—because it's doing extensive analysis and compilation. The output is a single binary file in your target directory. You can run it directly with ./target/my-application. The first thing you'll notice is how fast it starts.

Handling resources—like property files, XML configs, or HTML templates—presents a similar challenge to reflection. In a JVM, you can call getClass().getResourceAsStream("/config.yml") and the system will search the classpath. The native image doesn't have a dynamic classpath. You must declare every resource file you intend to load.

Again, configuration files are your friend. You can list resources with patterns.

{
  "resources": {
    "includes": [
      {"pattern": "application.*\\\\.ya?ml$"},
      {"pattern": "META-INF/services/.*"},
      {"pattern": "static/.*\\\\.css$"},
      {"pattern": "templates/.*\\\\.html$"}
    ],
    "excludes": [
      {"pattern": ".*\\\\.gitkeep$"}
    ]
  }
}

Sometimes, you need to be programmatic, especially if resource paths are dynamic. You can pre-load and cache resources at startup.

import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;
import jakarta.annotation.PostConstruct;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.ConcurrentHashMap;

@Component
public class NativeResourceCache {
    private final Map<String, String> cache = new ConcurrentHashMap<>();

    @PostConstruct
    public void loadCriticalResources() {
        String[] criticalPaths = {
            "/templates/home.html",
            "/static/logo.png",
            "/messages.properties"
        };
        for (String path : criticalPaths) {
            cacheResource(path);
        }
    }

    private void cacheResource(String path) {
        ClassPathResource resource = new ClassPathResource(path);
        if (resource.exists()) {
            try {
                String content = resource.getContentAsString(StandardCharsets.UTF_8);
                cache.put(path, content);
            } catch (IOException e) {
                // Log warning
            }
        }
    }

    public String getResource(String path) {
        return cache.get(path);
    }
}

This approach ensures your resources are available instantly and removes uncertainty about whether the native image builder included them.

When something goes wrong with your native executable, your usual Java debugging toolkit feels different. There's no Java Debug Wire Protocol (JDWP) agent to connect to by default. You need to plan for observability.

First, build a development-friendly image. You can add flags to include debugging symbols and enable monitoring features.

In your Maven buildArgs:

<arg>-g</arg> <!-- Generate debug info -->
<arg>-H:+AllowVMInspection</arg> <!-- Allow tools like jcmd -->
<arg>-H:EnableMonitoring=jfr,jmx</arg> <!-- Enable Java Flight Recorder and JMX -->
<arg>-H:+PrintInitialHeapSize</arg> <!-- Log memory settings -->

You can then expose basic metrics within your application itself. This is good practice anyway.

import org.springframework.boot.actuate.endpoint.annotation.*;
import org.springframework.stereotype.Component;
import java.lang.management.*;

@Component
@Endpoint(id = "nativeinfo")
public class NativeInfoEndpoint {

    @ReadOperation
    public Map<String, Object> getInfo() {
        Map<String, Object> info = new HashMap<>();
        RuntimeMXBean runtime = ManagementFactory.getRuntimeMXBean();
        MemoryMXBean memory = ManagementFactory.getMemoryMXBean();

        info.put("startTime", runtime.getStartTime());
        info.put("uptimeMs", runtime.getUptime());
        info.put("imageBuildTime", System.getProperty("org.graalvm.nativeimage.imagecode")); // GraalVM property

        info.put("heapUsed", memory.getHeapMemoryUsage().getUsed());
        info.put("heapCommitted", memory.getHeapMemoryUsage().getCommitted());

        // Thread info
        ThreadMXBean threadBean = ManagementFactory.getThreadMXBean();
        info.put("threadCount", threadBean.getThreadCount());

        return info;
    }
}

For logging, keep it simple. Complex, async appenders can cause issues. A straightforward console or file appender is reliable. Configure your logback-spring.xml to have a simpler profile for native images.

<springProfile name="native">
    <root level="INFO">
        <appender-ref ref="CONSOLE" />
    </root>
</springProfile>

The final technique is about changing how you write code. Some patterns that are fine on the JVM can be slow or problematic in a native image. A little adaptation goes a long way.

Consider class initialization. The builder can initialize classes at build time (faster startup) or run time (more compatible). You control this with build arguments, but you can also influence it with @Lazy beans in Spring.

@Configuration
public class AppConfig {
    // This won't be created until it's first injected
    @Bean
    @Lazy
    public ExpensiveService expensiveService() {
        return new ExpensiveService();
    }

    // This is created when the application context starts
    @Bean(initMethod = "warmUp")
    public CacheService cacheService() {
        return new CacheService();
    }
}

For dynamic service loading, instead of pure reflection, consider using a map or factory pattern.

public class ServiceFactory {
    private final Map<String, Supplier<MyService>> registry = new HashMap<>();

    public ServiceFactory() {
        // Explicit registration
        registry.put("email", EmailService::new);
        registry.put("sms", SmsService::new);
    }

    public MyService getService(String type) {
        Supplier<MyService> supplier = registry.get(type);
        if (supplier == null) {
            throw new IllegalArgumentException("Unknown service: " + type);
        }
        return supplier.get(); // No reflection involved
    }
}

Serialization is another area. Java's default serialization is highly reflective. For native images, consider formats like JSON (with pre-configured reflection for your DTOs) or a simple custom binary format.

Putting all this together, you get a clear path. Start by adding the native build plugin to your project. Try to build it. The build will likely fail, pointing out missing reflection or resource configuration. Use the tracing agent (a tool provided by GraalVM that runs your app on the JVM and logs all dynamic accesses) to automatically generate much of this config. Then, refine it. Move on to optimizing your code patterns and setting up monitoring.

The result is worth it. You'll have a single, self-contained binary. You can copy it to any compatible Linux machine (or macOS, or Windows) and run it—no JVM installation needed. It will start almost immediately and use a small, predictable amount of memory. This makes your Java applications truly competitive in modern, scalable environments where efficiency is paramount. It's not magic; it's a different way of thinking about compilation, and with these techniques, it's firmly within your reach.

📘 Checkout my latest ebook for free on my channel!

Be sure to like, share, comment, and subscribe to the channel!

101 Books

101 Books is an AI-driven publishing company co-founded by author Aarav Joshi. By leveraging advanced AI technology, we keep our publishing costs incredibly low—some books are priced as low as $4—making quality knowledge accessible to everyone.

Check out our book Golang Clean Code available on Amazon.

Stay tuned for updates and exciting news. When shopping for books, search for Aarav Joshi to find more of our titles. Use the provided link to enjoy special discounts!