Introduction
SubstrateVM (used in GraalVM Native Image) requires explicit configuration for reflection usage since it performs closed-world analysis during native image generation. Reflection configuration tells the native image builder which classes, methods, and fields need to be accessible via reflection at runtime.
Understanding Reflection in Native Image
The Reflection Challenge
public class ReflectionChallenge {
// This will fail in native image without configuration
public void problematicReflection() {
try {
Class<?> clazz = Class.forName("com.example.HiddenClass");
Method method = clazz.getDeclaredMethod("hiddenMethod");
method.setAccessible(true);
Object instance = clazz.getDeclaredConstructor().newInstance();
method.invoke(instance);
} catch (Exception e) {
// This will fail in native image without configuration
e.printStackTrace();
}
}
// Common reflection patterns that need configuration
public void commonReflectionPatterns() {
// 1. Class.forName()
Class<?> clazz = Class.forName("fully.qualified.ClassName");
// 2. getMethod() / getDeclaredMethod()
Method method = clazz.getDeclaredMethod("methodName", String.class);
// 3. getField() / getDeclaredField()
Field field = clazz.getDeclaredField("fieldName");
// 4. getConstructor()
Constructor<?> constructor = clazz.getDeclaredConstructor();
// 5. Array.newInstance()
Object array = Array.newInstance(clazz, 10);
// 6. Resource loading
InputStream resource = clazz.getResourceAsStream("/config.properties");
}
}
Manual Reflection Configuration
JSON Configuration Files
// META-INF/native-image/reflect-config.json
[
{
"name": "com.example.User",
"allDeclaredConstructors": true,
"allPublicConstructors": true,
"allDeclaredMethods": true,
"allPublicMethods": true,
"allDeclaredFields": true,
"allPublicFields": true
},
{
"name": "com.example.Product",
"methods": [
{
"name": "getName",
"parameterTypes": []
},
{
"name": "setPrice",
"parameterTypes": ["double"]
}
],
"fields": [
{
"name": "id",
"type": "long"
},
{
"name": "name",
"type": "java.lang.String"
}
]
},
{
"name": "com.example.Service",
"queriedMethods": [
{
"name": "process",
"parameterTypes": ["java.lang.String", "int"]
}
]
}
]
Comprehensive Configuration Structure
// Complete reflect-config.json example
[
{
"name": "com.example.dto.UserDTO",
"allDeclaredClasses": true,
"allDeclaredConstructors": true,
"allDeclaredMethods": true,
"allDeclaredFields": true,
"allPublicClasses": true,
"allPublicConstructors": true,
"allPublicMethods": true,
"allPublicFields": true
},
{
"name": "com.example.util.ReflectionHelper",
"methods": [
{
"name": "<init>",
"parameterTypes": []
},
{
"name": "invokePrivateMethod",
"parameterTypes": ["java.lang.Object", "java.lang.String", "java.lang.Class[]"]
}
]
},
{
"name": "java.util.ArrayList",
"fields": [
{
"name": "elementData",
"type": "java.lang.Object[]"
},
{
"name": "size",
"type": "int"
}
]
},
{
"name": "com.example.enums.Status",
"allDeclaredFields": true,
"allDeclaredMethods": true
}
]
Automated Configuration Generation
Runtime Reflection Registration
public class RuntimeReflectionRegistrar {
public static void registerForReflection() {
// Register classes for reflection
registerClass("com.example.User");
registerClass("com.example.Product");
registerClass("com.example.Order");
// Register specific methods
registerMethod("com.example.Service", "processOrder", String.class, int.class);
registerMethod("com.example.Util", "convertToJson", Object.class);
// Register fields
registerField("com.example.Config", "apiKey");
registerField("com.example.Config", "timeout");
}
private static void registerClass(String className) {
try {
Class<?> clazz = Class.forName(className);
RuntimeReflection.register(clazz);
RuntimeReflection.register(clazz.getDeclaredConstructors());
RuntimeReflection.register(clazz.getDeclaredMethods());
RuntimeReflection.register(clazz.getDeclaredFields());
} catch (ClassNotFoundException e) {
System.err.println("Class not found for reflection registration: " + className);
}
}
private static void registerMethod(String className, String methodName, Class<?>... parameterTypes) {
try {
Class<?> clazz = Class.forName(className);
Method method = clazz.getDeclaredMethod(methodName, parameterTypes);
RuntimeReflection.register(method);
} catch (Exception e) {
System.err.println("Method not found for reflection registration: " +
className + "." + methodName);
}
}
private static void registerField(String className, String fieldName) {
try {
Class<?> clazz = Class.forName(className);
Field field = clazz.getDeclaredField(fieldName);
RuntimeReflection.register(field);
} catch (Exception e) {
System.err.println("Field not found for reflection registration: " +
className + "." + fieldName);
}
}
// Register all classes in a package
public static void registerPackage(String packageName) {
try {
ClassPath classpath = ClassPath.from(Thread.currentThread().getContextClassLoader());
for (ClassPath.ClassInfo classInfo : classpath.getTopLevelClasses(packageName)) {
registerClass(classInfo.getName());
}
} catch (IOException e) {
System.err.println("Failed to scan package: " + packageName);
}
}
}
Feature Interface for Automatic Registration
import org.graalvm.nativeimage.hosted.Feature;
import org.graalvm.nativeimage.hosted.RuntimeReflection;
public class ReflectionFeature implements Feature {
@Override
public void beforeAnalysis(BeforeAnalysisAccess access) {
System.out.println("Registering classes for reflection...");
// Register core application classes
registerApplicationClasses();
// Register framework classes
registerFrameworkClasses();
// Register dynamic classes
registerDynamicReflection();
}
private void registerApplicationClasses() {
// Register all DTOs
registerClassAndMembers("com.example.dto.UserDTO");
registerClassAndMembers("com.example.dto.ProductDTO");
registerClassAndMembers("com.example.dto.OrderDTO");
// Register service classes
registerClassAndMembers("com.example.service.UserService");
registerClassAndMembers("com.example.service.ProductService");
// Register entity classes
registerClassAndMembers("com.example.entity.User");
registerClassAndMembers("com.example.entity.Product");
}
private void registerFrameworkClasses() {
// Jackson JSON processing
registerClass("com.fasterxml.jackson.databind.ObjectMapper");
registerClass("com.fasterxml.jackson.annotation.JsonProperty");
// Spring Framework
registerClass("org.springframework.stereotype.Component");
registerClass("org.springframework.web.bind.annotation.RestController");
}
private void registerDynamicReflection() {
// Register classes that might be loaded dynamically
try {
Class<?> dynamicClass = Class.forName("com.example.dynamic.DynamicProcessor");
RuntimeReflection.register(dynamicClass);
} catch (ClassNotFoundException e) {
// Ignore - class might not be available at build time
}
}
private void registerClassAndMembers(String className) {
try {
Class<?> clazz = Class.forName(className);
RuntimeReflection.register(clazz);
RuntimeReflection.register(clazz.getDeclaredConstructors());
RuntimeReflection.register(clazz.getDeclaredMethods());
RuntimeReflection.register(clazz.getDeclaredFields());
} catch (ClassNotFoundException e) {
System.err.println("Class not found: " + className);
}
}
private void registerClass(String className) {
try {
Class<?> clazz = Class.forName(className);
RuntimeReflection.register(clazz);
} catch (ClassNotFoundException e) {
System.err.println("Class not found: " + className);
}
}
@Override
public String getDescription() {
return "Automatic reflection registration for application classes";
}
}
Framework-Specific Configuration
Spring Boot Native Image Configuration
@NativeHint(
trigger = SpringBootApplication.class,
types = {
@TypeHint(types = {
org.springframework.web.bind.annotation.RestController.class,
org.springframework.stereotype.Service.class,
org.springframework.stereotype.Component.class
}, access = TypeAccess.DECLARED_CONSTRUCTORS),
@TypeHint(
types = com.example.dto.UserDTO.class,
access = {TypeAccess.PUBLIC_CONSTRUCTORS, TypeAccess.PUBLIC_METHODS}
)
},
options = {"--enable-https"}
)
@Configuration
public class SpringNativeConfiguration {
@Bean
@NativeHint(types = @TypeHint(types = ObjectMapper.class))
public ObjectMapper objectMapper() {
return new ObjectMapper();
}
}
// Alternative using Spring Native 0.11+ with @RegisterReflectionForBinding
@SpringBootApplication
@RegisterReflectionForBinding({
UserDTO.class,
ProductDTO.class,
OrderDTO.class
})
public class NativeApplication {
public static void main(String[] args) {
SpringApplication.run(NativeApplication.class, args);
}
}
Jackson JSON Reflection Configuration
public class JacksonReflectionConfig {
// JSON configuration for Jackson
/*
META-INF/native-image/jackson-config.json
*/
public static String getJacksonReflectionConfig() {
return """
[
{
"name": "com.example.dto.UserDTO",
"allDeclaredConstructors": true,
"allDeclaredMethods": true,
"allDeclaredFields": true
},
{
"name": "com.example.dto.ProductDTO",
"allDeclaredConstructors": true,
"allDeclaredMethods": true,
"allDeclaredFields": true
},
{
"name": "com.fasterxml.jackson.databind.ObjectMapper",
"methods": [
{"name": "<init>", "parameterTypes": []},
{"name": "readValue", "parameterTypes": ["java.lang.String", "java.lang.Class"]}
]
}
]
""";
}
// Runtime registration for Jackson
public static void registerJacksonForReflection() {
try {
// Register ObjectMapper
Class<?> objectMapperClass = Class.forName("com.fasterxml.jackson.databind.ObjectMapper");
RuntimeReflection.register(objectMapperClass);
RuntimeReflection.register(objectMapperClass.getDeclaredConstructors());
// Register common Jackson annotations
Class<?> jsonPropertyClass = Class.forName("com.fasterxml.jackson.annotation.JsonProperty");
RuntimeReflection.register(jsonPropertyClass);
// Register your DTOs
registerDTOClasses();
} catch (ClassNotFoundException e) {
System.err.println("Jackson classes not found for reflection registration");
}
}
private static void registerDTOClasses() {
String[] dtoClasses = {
"com.example.dto.UserDTO",
"com.example.dto.ProductDTO",
"com.example.dto.OrderDTO",
"com.example.dto.AddressDTO"
};
for (String className : dtoClasses) {
try {
Class<?> clazz = Class.forName(className);
RuntimeReflection.register(clazz);
RuntimeReflection.register(clazz.getDeclaredConstructors());
RuntimeReflection.register(clazz.getDeclaredMethods());
RuntimeReflection.register(clazz.getDeclaredFields());
} catch (ClassNotFoundException e) {
System.err.println("DTO class not found: " + className);
}
}
}
}
Dynamic Proxy Configuration
Proxy Configuration Files
// META-INF/native-image/proxy-config.json
[
{
"interfaces": ["java.lang.Runnable", "java.util.concurrent.Callable"]
},
{
"interfaces": ["com.example.service.UserService", "org.springframework.stereotype.Component"]
},
{
"interfaces": ["java.io.Serializable", "com.example.dto.Transferable"]
}
]
Runtime Proxy Registration
public class DynamicProxyRegistrar {
public static void registerProxies() {
// Register common proxy interfaces
registerProxyInterfaces(
"java.lang.Runnable",
"java.util.concurrent.Callable",
"java.io.Serializable"
);
// Register Spring proxies
registerProxyInterfaces(
"org.springframework.stereotype.Component",
"org.springframework.context.annotation.Bean"
);
// Register application-specific proxies
registerProxyInterfaces(
"com.example.service.UserService",
"com.example.service.ProductService"
);
}
private static void registerProxyInterfaces(String... interfaceNames) {
List<Class<?>> interfaces = new ArrayList<>();
for (String interfaceName : interfaceNames) {
try {
Class<?> interfaceClass = Class.forName(interfaceName);
interfaces.add(interfaceClass);
} catch (ClassNotFoundException e) {
System.err.println("Interface not found: " + interfaceName);
}
}
if (!interfaces.isEmpty()) {
RuntimeReflection.register(interfaces.toArray(new Class<?>[0]));
}
}
// Register proxy for specific interface combinations
public static void registerSpecificProxy(Class<?>... interfaces) {
RuntimeReflection.register(interfaces);
}
}
Resource Configuration
Resource Configuration Files
// META-INF/native-image/resource-config.json
{
"resources": {
"includes": [
{
"pattern": ".*\\\\.properties$"
},
{
"pattern": ".*\\\\.json$"
},
{
"pattern": ".*\\\\.xml$"
},
{
"pattern": "META-INF/services/.*"
},
{
"pattern": "templates/.*"
}
],
"excludes": [
{
"pattern": ".*\\\\.gitignore$"
},
{
"pattern": ".*\\\\.md$"
}
]
},
"bundles": [
{
"name": "com.sun.org.apache.xerces.internal.impl.msg.XMLMessages"
},
{
"name": "sun.util.resources.CurrencyNames"
}
]
}
Runtime Resource Registration
public class ResourceRegistration {
public static void registerResources() {
// Register property files
registerResourcePattern(".*\\\\.properties");
// Register configuration files
registerResourcePattern("application.*");
registerResourcePattern("bootstrap.*");
// Register service files
registerResourcePattern("META-INF/services/.*");
// Register template files
registerResourcePattern("templates/.*");
registerResourcePattern("static/.*");
}
private static void registerResourcePattern(String pattern) {
try {
RuntimeResourceAccess.addResourcePattern(pattern);
} catch (Exception e) {
System.err.println("Failed to register resource pattern: " + pattern);
}
}
// Register specific resources
public static void registerSpecificResources(String... resources) {
for (String resource : resources) {
try {
RuntimeResourceAccess.addResource(resource);
} catch (Exception e) {
System.err.println("Failed to register resource: " + resource);
}
}
}
// Register resource bundles
public static void registerResourceBundles() {
String[] bundles = {
"sun.util.resources.CurrencyNames",
"com.sun.org.apache.xerces.internal.impl.msg.XMLMessages",
"java.util.PropertyResourceBundle"
};
for (String bundle : bundles) {
try {
RuntimeResourceAccess.addResourceBundle(bundle);
} catch (Exception e) {
System.err.println("Failed to register resource bundle: " + bundle);
}
}
}
}
JNI Configuration
JNI Configuration Files
// META-INF/native-image/jni-config.json
[
{
"name": "java.lang.System",
"methods": [
{
"name": "loadLibrary",
"parameterTypes": ["java.lang.String"]
},
{
"name": "load",
"parameterTypes": ["java.lang.String"]
}
]
},
{
"name": "java.lang.Runtime",
"methods": [
{
"name": "loadLibrary0",
"parameterTypes": ["java.lang.Class", "java.lang.String"]
}
]
},
{
"name": "com.example.NativeLibrary",
"allDeclaredMethods": true,
"allDeclaredConstructors": true
}
]
Testing Reflection Configuration
Reflection Testing Utility
public class ReflectionTestUtil {
public static void testReflectionAccess(String className) {
try {
Class<?> clazz = Class.forName(className);
System.out.println("Testing reflection for: " + className);
// Test constructors
testConstructors(clazz);
// Test methods
testMethods(clazz);
// Test fields
testFields(clazz);
System.out.println("✓ All reflection tests passed for: " + className);
} catch (ClassNotFoundException e) {
System.err.println("✗ Class not found: " + className);
} catch (Exception e) {
System.err.println("✗ Reflection test failed for: " + className + " - " + e.getMessage());
}
}
private static void testConstructors(Class<?> clazz) {
try {
Constructor<?>[] constructors = clazz.getDeclaredConstructors();
for (Constructor<?> constructor : constructors) {
constructor.setAccessible(true);
// Try to access constructor
System.out.println(" ✓ Constructor: " + constructor);
}
} catch (Exception e) {
throw new RuntimeException("Constructor access failed", e);
}
}
private static void testMethods(Class<?> clazz) {
try {
Method[] methods = clazz.getDeclaredMethods();
for (Method method : methods) {
method.setAccessible(true);
// Try to access method
System.out.println(" ✓ Method: " + method.getName());
}
} catch (Exception e) {
throw new RuntimeException("Method access failed", e);
}
}
private static void testFields(Class<?> clazz) {
try {
Field[] fields = clazz.getDeclaredFields();
for (Field field : fields) {
field.setAccessible(true);
// Try to access field
System.out.println(" ✓ Field: " + field.getName());
}
} catch (Exception e) {
throw new RuntimeException("Field access failed", e);
}
}
// Test specific method invocation
public static void testMethodInvocation(String className, String methodName, Class<?>[] paramTypes, Object... args) {
try {
Class<?> clazz = Class.forName(className);
Method method = clazz.getDeclaredMethod(methodName, paramTypes);
method.setAccessible(true);
Object instance = clazz.getDeclaredConstructor().newInstance();
Object result = method.invoke(instance, args);
System.out.println("✓ Method invocation successful: " + methodName + " -> " + result);
} catch (Exception e) {
throw new RuntimeException("Method invocation failed: " + methodName, e);
}
}
// Run all reflection tests
public static void runAllTests() {
String[] testClasses = {
"com.example.dto.UserDTO",
"com.example.service.UserService",
"com.example.util.ValidationUtil"
};
for (String className : testClasses) {
testReflectionAccess(className);
}
}
}
Build-Time Configuration
Maven Configuration for Native Image
<!-- pom.xml configuration for GraalVM Native Image --> <plugin> <groupId>org.graalvm.buildtools</groupId> <artifactId>native-maven-plugin</artifactId> <version>0.9.19</version> <executions> <execution> <id>build-native</id> <goals> <goal>build</goal> </goals> <phase>package</phase> </execution> </executions> <configuration> <mainClass>com.example.Application</mainClass> <buildArgs> <buildArg>--verbose</buildArg> <buildArg>--no-fallback</buildArg> <buildArg>-H:EnableURLProtocols=http,https</buildArg> <buildArg>-H:+ReportExceptionStackTraces</buildArg> <buildArg>-H:ReflectionConfigurationFiles=reflect-config.json</buildArg> <buildArg>-H:ResourceConfigurationFiles=resource-config.json</buildArg> <buildArg>-H:JNIConfigurationFiles=jni-config.json</buildArg> </buildArgs> </configuration> </plugin> <!-- Agent for automatic configuration generation --> <plugin> <groupId>org.graalvm.buildtools</groupId> <artifactId>native-maven-plugin</artifactId> <version>0.9.19</version> <executions> <execution> <id>test-native</id> <goals> <goal>test</goal> </goals> <phase>test</phase> </execution> </executions> <configuration> <agent>true</agent> </configuration> </plugin>
Gradle Configuration
// build.gradle for Native Image
plugins {
id 'org.graalvm.buildtools.native' version '0.9.19'
}
graalvmNative {
binaries {
main {
buildArgs.addAll(
'--verbose',
'--no-fallback',
'-H:EnableURLProtocols=http,https',
'-H:+ReportExceptionStackTraces',
'-H:ReflectionConfigurationFiles=reflect-config.json',
'-H:ResourceConfigurationFiles=resource-config.json'
)
}
}
agent {
defaultMode = "standard"
}
}
// Task to generate reflection configuration
task generateReflectionConfig(type: JavaExec) {
classpath = sourceSets.main.runtimeClasspath
mainClass = 'com.example.ReflectionConfigGenerator'
}
Best Practices and Troubleshooting
Reflection Configuration Best Practices
public class ReflectionBestPractices {
// 1. Use specific configuration over broad patterns
public void specificConfiguration() {
// Good: Specific methods and fields
/*
{
"name": "com.example.User",
"methods": [
{"name": "getName", "parameterTypes": []},
{"name": "setEmail", "parameterTypes": ["java.lang.String"]}
],
"fields": [
{"name": "id", "type": "long"}
]
}
*/
// Avoid: Overly broad configuration
/*
{
"name": "com.example.*",
"allDeclaredMethods": true,
"allDeclaredFields": true
}
*/
}
// 2. Register classes used in serialization
public void registerSerializationClasses() {
String[] serializationClasses = {
"com.example.dto.UserDTO",
"com.example.dto.ProductDTO",
"com.example.dto.OrderDTO",
"java.util.ArrayList",
"java.util.HashMap"
};
for (String className : serializationClasses) {
try {
Class<?> clazz = Class.forName(className);
RuntimeReflection.register(clazz);
} catch (ClassNotFoundException e) {
System.err.println("Serialization class not found: " + className);
}
}
}
// 3. Handle dynamic class loading
public void handleDynamicClasses() {
// Use Feature interface to register classes that might be loaded dynamically
// Or use conditional registration based on build-time analysis
}
// 4. Test configuration thoroughly
public void testConfiguration() {
ReflectionTestUtil.runAllTests();
}
// 5. Use the agent for initial configuration
public void useAgentForDiscovery() {
// Run with: -agentlib:native-image-agent=config-output-dir=./config
// This generates configuration files based on runtime behavior
}
}
// Common troubleshooting patterns
public class ReflectionTroubleshooting {
public static void diagnoseReflectionIssues() {
// Check if class is available
checkClassAvailability("com.example.MissingClass");
// Check method accessibility
checkMethodAccessibility("com.example.User", "getEmail");
// Check field accessibility
checkFieldAccessibility("com.example.User", "password");
}
private static void checkClassAvailability(String className) {
try {
Class<?> clazz = Class.forName(className);
System.out.println("✓ Class available: " + className);
} catch (ClassNotFoundException e) {
System.err.println("✗ Class not available: " + className);
}
}
private static void checkMethodAccessibility(String className, String methodName) {
try {
Class<?> clazz = Class.forName(className);
Method method = clazz.getDeclaredMethod(methodName);
method.setAccessible(true);
System.out.println("✓ Method accessible: " + methodName);
} catch (Exception e) {
System.err.println("✗ Method not accessible: " + methodName + " - " + e.getMessage());
}
}
private static void checkFieldAccessibility(String className, String fieldName) {
try {
Class<?> clazz = Class.forName(className);
Field field = clazz.getDeclaredField(fieldName);
field.setAccessible(true);
System.out.println("✓ Field accessible: " + fieldName);
} catch (Exception e) {
System.err.println("✗ Field not accessible: " + fieldName + " - " + e.getMessage());
}
}
}
Conclusion
Proper SubstrateVM reflection configuration is essential for successful native image generation. Key takeaways:
- Be Specific - Prefer explicit method/field registration over broad patterns
- Use the Agent - Leverage the tracing agent for initial configuration generation
- Test Thoroughly - Validate reflection access in both JVM and native modes
- Framework Integration - Use framework-specific annotations and hints when available
- Runtime Registration - Implement Feature interface for dynamic registration scenarios
- Resource Management - Don't forget to configure resources and proxies
By following these patterns and best practices, you can successfully configure reflection for SubstrateVM native images while maintaining application functionality and performance.