Layered Modules and Runtime Images in Java

The Java Module System introduced powerful features for creating layered module architectures and custom runtime images. These capabilities enable better application isolation, dynamic loading, and optimized deployments.

1. Module Layers Overview

What are Module Layers?

Module Layers are hierarchical arrangements of modules
Each layer has its own module graph and class loaders
Enables multiple versions of same module to coexist
Supports dynamic module loading and plugin architectures

Key Concepts

Boot Layer - The initial layer containing application modules
Custom Layers - Additional layers for plugins/extensions
Parent-Child Relationship - Layers can have parent layers
Isolation - Each layer has separate module resolution

2. Creating Custom Module Layers

Basic Layer Creation

import java.lang.module.*; import java.nio.file.*; import java.util.*; public class BasicLayerExample { public static void main(String[] args) throws Exception { // Step 1: Create module finders ModuleFinder pluginFinder = ModuleFinder.of(Paths.get("plugins")); ModuleFinder appFinder = ModuleFinder.of(Paths.get("app")); // Step 2: Get boot layer configuration ModuleLayer bootLayer = ModuleLayer.boot(); Configuration bootConfig = bootLayer.configuration(); // Step 3: Resolve plugin modules Configuration pluginConfig = bootConfig.resolve( pluginFinder, ModuleFinder.of(), Set.of("com.example.plugin") ); // Step 4: Create class loader and module layer ClassLoader parentLoader = ClassLoader.getSystemClassLoader(); ModuleLayer pluginLayer = bootLayer.defineModulesWithOneLoader( pluginConfig, parentLoader ); System.out.println("Plugin layer created with modules: " + pluginLayer.modules().stream() .map(Module::getName) .collect(Collectors.joining(", "))); } }

Advanced Multi-Layer Architecture

import java.lang.module.*; import java.nio.file.*; import java.util.*; import java.util.stream.*; public class AdvancedLayerManager { private final Map<String, ModuleLayer> layers = new HashMap<>(); private final ModuleLayer bootLayer; public AdvancedLayerManager() { this.bootLayer = ModuleLayer.boot(); } /** * Creates a new module layer for plugins */ public ModuleLayer createPluginLayer(String layerName, Path pluginPath, Set<String> rootModules) throws Exception { ModuleFinder pluginFinder = ModuleFinder.of(pluginPath); Configuration parentConfig = bootLayer.configuration(); Configuration pluginConfig = parentConfig.resolve( pluginFinder, ModuleFinder.of(), rootModules ); ClassLoader layerLoader = new LayerClassLoader("layer-" + layerName); ModuleLayer pluginLayer = bootLayer.defineModulesWithOneLoader( pluginConfig, layerLoader ); layers.put(layerName, pluginLayer); return pluginLayer; } /** * Creates a child layer with specific parent layers */ public ModuleLayer createChildLayer(String layerName, Path modulePath, Set<String> rootModules, ModuleLayer... parents) throws Exception { List<Configuration> parentConfigs = Arrays.stream(parents) .map(ModuleLayer::configuration) .collect(Collectors.toList()); ModuleFinder finder = ModuleFinder.of(modulePath); Configuration config = Configuration.resolve( finder, parentConfigs, ModuleFinder.of(), rootModules ); ClassLoader layerLoader = new LayerClassLoader("layer-" + layerName); List<ModuleLayer> parentLayers = Arrays.asList(parents); ModuleLayer childLayer = ModuleLayer.defineModulesWithOneLoader( config, parentLayers, layerLoader ); layers.put(layerName, childLayer); return childLayer; } /** * Finds a class in all layers */ public Optional<Class<?>> findClass(String className) { for (ModuleLayer layer : layers.values()) { try { ClassLoader loader = layer.findLoader(className); if (loader != null) { return Optional.of(Class.forName(className, true, loader)); } } catch (ClassNotFoundException e) { // Continue searching in other layers } } return Optional.empty(); } /** * Gets all modules across all layers */ public Set<Module> getAllModules() { return layers.values().stream() .flatMap(layer -> layer.modules().stream()) .collect(Collectors.toSet()); } // Custom class loader for layer isolation static class LayerClassLoader extends ClassLoader { private final String layerName; public LayerClassLoader(String layerName) { this.layerName = layerName; } @Override public String toString() { return "LayerClassLoader[" + layerName + "]"; } } }

3. Complete Plugin System Example

Plugin Architecture with Module Layers

Core Application Module

// core-app/module-info.java module com.example.core { exports com.example.core.api; exports com.example.core.spi; uses com.example.core.spi.Plugin; }

// core-app/com/example/core/api/PluginContext.java package com.example.core.api; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; public class PluginContext { private final Map<String, Object> attributes = new ConcurrentHashMap<>(); public void setAttribute(String key, Object value) { attributes.put(key, value); } @SuppressWarnings("unchecked") public <T> T getAttribute(String key) { return (T) attributes.get(key); } public <T> T getAttribute(String key, Class<T> type) { Object value = attributes.get(key); return type.isInstance(value) ? type.cast(value) : null; } }

// core-app/com/example/core/spi/Plugin.java package com.example.core.spi; import com.example.core.api.PluginContext; public interface Plugin { String getName(); String getVersion(); void initialize(PluginContext context); void start(); void stop(); boolean isRunning(); }

Plugin Manager with Module Layers

// core-app/com/example/core/PluginManager.java package com.example.core; import com.example.core.api.PluginContext; import com.example.core.spi.Plugin; import java.lang.module.*; import java.nio.file.*; import java.util.*; import java.util.concurrent.*; import java.util.stream.*; public class PluginManager { private final Map<String, ModuleLayer> pluginLayers = new ConcurrentHashMap<>(); private final Map<String, Plugin> plugins = new ConcurrentHashMap<>(); private final PluginContext context; public PluginManager(PluginContext context) { this.context = context; } /** * Loads a plugin from the specified directory */ public void loadPlugin(String pluginId, Path pluginDir) throws Exception { if (pluginLayers.containsKey(pluginId)) { throw new IllegalStateException("Plugin already loaded: " + pluginId); } ModuleFinder pluginFinder = ModuleFinder.of(pluginDir); ModuleLayer bootLayer = ModuleLayer.boot(); // Find all modules in plugin directory Set<String> pluginModules = pluginFinder.findAll().stream() .map(ModuleReference::descriptor) .map(ModuleDescriptor::name) .collect(Collectors.toSet()); if (pluginModules.isEmpty()) { throw new IllegalArgumentException("No modules found in: " + pluginDir); } // Resolve plugin configuration Configuration pluginConfig = bootLayer.configuration().resolve( pluginFinder, ModuleFinder.of(), pluginModules ); // Create isolated class loader for plugin ClassLoader pluginLoader = new PluginClassLoader(pluginId); ModuleLayer pluginLayer = bootLayer.defineModulesWithOneLoader( pluginConfig, pluginLoader ); pluginLayers.put(pluginId, pluginLayer); // Discover and initialize plugins initializePluginsInLayer(pluginId, pluginLayer); } private void initializePluginsInLayer(String pluginId, ModuleLayer layer) { ServiceLoader<Plugin> loader = ServiceLoader.load(layer, Plugin.class); for (Plugin plugin : loader) { String pluginName = plugin.getName(); System.out.println("Initializing plugin: " + pluginName + " from layer: " + pluginId); try { plugin.initialize(context); plugins.put(pluginName, plugin); } catch (Exception e) { System.err.println("Failed to initialize plugin: " + pluginName); e.printStackTrace(); } } } /** * Starts all loaded plugins */ public void startAllPlugins() { plugins.values().forEach(plugin -> { try { if (!plugin.isRunning()) { plugin.start(); System.out.println("Started plugin: " + plugin.getName()); } } catch (Exception e) { System.err.println("Failed to start plugin: " + plugin.getName()); e.printStackTrace(); } }); } /** * Stops and unloads a plugin */ public void unloadPlugin(String pluginId) { ModuleLayer layer = pluginLayers.get(pluginId); if (layer == null) { return; } // Stop all plugins from this layer plugins.entrySet().removeIf(entry -> { Plugin plugin = entry.getValue(); if (plugin.getClass().getModule().getLayer() == layer) { try { plugin.stop(); System.out.println("Stopped plugin: " + plugin.getName()); } catch (Exception e) { System.err.println("Error stopping plugin: " + plugin.getName()); } return true; } return false; }); pluginLayers.remove(pluginId); // Note: In real implementation, you might need to handle // resource cleanup and class loader unloading more carefully } /** * Gets all loaded plugins */ public List<Plugin> getPlugins() { return new ArrayList<>(plugins.values()); } /** * Finds plugin by name */ public Optional<Plugin> getPlugin(String name) { return Optional.ofNullable(plugins.get(name)); } // Custom class loader for plugin isolation static class PluginClassLoader extends ClassLoader { private final String pluginId; public PluginClassLoader(String pluginId) { this.pluginId = pluginId; } @Override public String toString() { return "PluginClassLoader[" + pluginId + "]"; } } }

Example Plugin Implementation

// calculator-plugin/module-info.java module com.example.calculator.plugin { requires com.example.core; provides com.example.core.spi.Plugin with com.example.calculator.plugin.CalculatorPlugin; exports com.example.calculator.plugin; }

// calculator-plugin/com/example/calculator/plugin/CalculatorPlugin.java package com.example.calculator.plugin; import com.example.core.api.PluginContext; import com.example.core.spi.Plugin; public class CalculatorPlugin implements Plugin { private volatile boolean running = false; private PluginContext context; @Override public String getName() { return "Calculator Plugin"; } @Override public String getVersion() { return "1.0.0"; } @Override public void initialize(PluginContext context) { this.context = context; System.out.println("Calculator Plugin initialized"); // Register calculator service in context context.setAttribute("calculator", new CalculatorService()); } @Override public void start() { running = true; System.out.println("Calculator Plugin started"); } @Override public void stop() { running = false; System.out.println("Calculator Plugin stopped"); } @Override public boolean isRunning() { return running; } // Plugin-specific functionality public static class CalculatorService { public double add(double a, double b) { return a + b; } public double subtract(double a, double b) { return a - b; } public double multiply(double a, double b) { return a * b; } public double divide(double a, double b) { return a / b; } } }

Main Application

// core-app/com/example/core/MainApplication.java package com.example.core; import com.example.core.api.PluginContext; import java.nio.file.*; public class MainApplication { public static void main(String[] args) throws Exception { PluginContext context = new PluginContext(); PluginManager pluginManager = new PluginManager(context); // Load plugins from different directories Path pluginsDir = Paths.get("plugins"); if (Files.exists(pluginsDir)) { Files.list(pluginsDir) .filter(Files::isDirectory) .forEach(pluginDir -> { try { String pluginId = pluginDir.getFileName().toString(); pluginManager.loadPlugin(pluginId, pluginDir); } catch (Exception e) { System.err.println("Failed to load plugin from: " + pluginDir); e.printStackTrace(); } }); } // Start all plugins pluginManager.startAllPlugins(); // Demonstrate plugin functionality pluginManager.getPlugins().forEach(plugin -> { System.out.println("Active plugin: " + plugin.getName() + " (Running: " + plugin.isRunning() + ")"); }); // Keep application running System.out.println("Application running. Press Ctrl+C to exit."); Thread.sleep(Long.MAX_VALUE); } }

4. Custom Runtime Images with jlink

Creating Minimal Runtime Images

Basic jlink Usage

# Create a custom runtime image jlink --module-path $JAVA_HOME/jmods:mods \ --add-modules java.base,java.logging,com.example.app \ --output custom-runtime # Create with compression and stripped debug info jlink --module-path $JAVA_HOME/jmods:mods \ --add-modules java.base,java.sql,java.logging,com.example.app \ --compress=2 \ --no-header-files \ --no-man-pages \ --strip-debug \ --output minimal-runtime

Advanced jlink Configuration

# Create runtime with specific VM options jlink --module-path $JAVA_HOME/jmods:mods \ --add-modules java.base,java.logging,java.management,com.example.app \ --output production-runtime \ --launcher start-app=com.example.app/com.example.app.Main \ --vm=server \ --bind-services \ --ignore-signing-information

jlink Plugin System

// Example: Custom jlink plugin for resource optimization import jdk.tools.jlink.plugin.*; import jdk.tools.jlink.builder.*; import java.util.*; public class ResourceOptimizerPlugin implements Plugin { private final Set<String> excludedResources = Set.of( "*.md", "*.txt", "*.html", "META-INF/LICENSE" ); @Override public String getName() { return "resource-optimizer"; } @Override public String getDescription() { return "Removes unnecessary resources from runtime image"; } @Override public Category getType() { return Category.FILTER; } @Override public boolean hasArguments() { return true; } @Override public String getArgumentsDescription() { return "<exclude-patterns> - Comma separated list of patterns to exclude"; } @Override public void configure(Map<String, String> config) { String patterns = config.get("exclude-patterns"); if (patterns != null) { excludedResources.clear(); Collections.addAll(excludedResources, patterns.split(",")); } } @Override public ResourcePool transform(ResourcePool in, ResourcePoolBuilder out) { in.transformAndCopy((resource) -> { String path = resource.path(); // Check if resource should be excluded for (String pattern : excludedResources) { if (matchesPattern(path, pattern)) { System.out.println("Excluding resource: " + path); return null; // Exclude this resource } } return resource; }, out); return out.build(); } private boolean matchesPattern(String path, String pattern) { if (pattern.startsWith("*.")) { String extension = pattern.substring(1); return path.endsWith(extension); } return path.contains(pattern); } }

Building Custom Runtime with jlink API

import jdk.tools.jlink.*; import jdk.tools.jlink.plugin.*; import java.nio.file.*; import java.util.*; public class RuntimeImageBuilder { public Path buildCustomRuntime(Path modulePath, Set<String> modules, Path outputDir) throws Exception { // Create jlink configuration JlinkTask task = JlinkTask.builder() .modulePath(modulePath) .addModules(modules) .output(outputDir) .endianness(JlinkTask.Endianness.NATIVE) .compress(JlinkTask.Compression.ZIP) .build(); // Execute jlink task task.call(); return outputDir.resolve("bin").resolve("java"); } public Path buildOptimizedRuntime(Path modulePath, Set<String> modules, Path outputDir, List<Plugin> plugins) throws Exception { JlinkTask.Builder builder = JlinkTask.builder() .modulePath(modulePath) .addModules(modules) .output(outputDir) .compress(JlinkTask.Compression.ZIP) .stripDebug(true) .noHeaderFiles(true) .noManPages(true); // Add custom plugins for (Plugin plugin : plugins) { builder.plugin(plugin); } return builder.build().call(); } }

5. Dynamic Module Loading at Runtime

Runtime Module Resolution

import java.lang.module.*; import java.nio.file.*; import java.util.*; import java.util.stream.*; public class DynamicModuleLoader { private final Map<String, ResolvedModule> loadedModules = new HashMap<>(); private final ModuleLayer bootLayer; public DynamicModuleLoader() { this.bootLayer = ModuleLayer.boot(); } /** * Dynamically loads a module at runtime */ public Module loadModule(Path modulePath, String moduleName) throws Exception { ModuleFinder finder = ModuleFinder.of(modulePath); Optional<ModuleReference> moduleRef = finder.find(moduleName); if (moduleRef.isEmpty()) { throw new IllegalArgumentException("Module not found: " + moduleName); } Configuration parentConfig = bootLayer.configuration(); Configuration newConfig = parentConfig.resolveAndBind( finder, ModuleFinder.of(), Set.of(moduleName) ); ClassLoader loader = new DynamicModuleClassLoader(moduleName); ModuleLayer newLayer = bootLayer.defineModulesWithOneLoader(newConfig, loader); Optional<Module> module = newLayer.findModule(moduleName); if (module.isPresent()) { loadedModules.put(moduleName, newConfig.findModule(moduleName).get()); return module.get(); } throw new IllegalStateException("Failed to load module: " + moduleName); } /** * Unloads a dynamically loaded module * Note: This is simplified - real unloading is complex */ public void unloadModule(String moduleName) { loadedModules.remove(moduleName); // In practice, you'd need to handle class loader cleanup } /** * Gets dependencies of a module */ public Set<String> getDependencies(String moduleName) { ResolvedModule resolved = loadedModules.get(moduleName); if (resolved == null) { return Set.of(); } return resolved.reads().stream() .map(ResolvedModule::name) .collect(Collectors.toSet()); } static class DynamicModuleClassLoader extends ClassLoader { private final String moduleName; public DynamicModuleClassLoader(String moduleName) { this.moduleName = moduleName; } @Override public String toString() { return "DynamicModuleClassLoader[" + moduleName + "]"; } } }

6. Service Binding in Module Layers

Service Binding Across Layers

import java.lang.module.*; import java.util.*; import java.util.stream.*; public class CrossLayerServiceManager { private final List<ModuleLayer> layers = new ArrayList<>(); public CrossLayerServiceManager() { layers.add(ModuleLayer.boot()); } /** * Finds services across all layers */ public <T> List<T> findAllServices(Class<T> serviceClass) { return layers.stream() .flatMap(layer -> ServiceLoader.load(layer, serviceClass).stream()) .map(ServiceLoader.Provider::get) .collect(Collectors.toList()); } /** * Finds service in specific layer */ public <T> Optional<T> findServiceInLayer(Class<T> serviceClass, ModuleLayer layer) { return ServiceLoader.load(layer, serviceClass) .stream() .map(ServiceLoader.Provider::get) .findFirst(); } /** * Creates service bridge between layers */ public <T> void createServiceBridge(Class<T> serviceClass, ModuleLayer sourceLayer, ModuleLayer targetLayer) { // This would require reflection or code generation // to bridge services between isolated layers System.out.println("Creating service bridge for " + serviceClass.getName() + " from " + sourceLayer + " to " + targetLayer); } }

7. Best Practices and Patterns

1. Layer Isolation Strategy

public class LayerIsolationManager { private final Map<String, ModuleLayer> layers = new ConcurrentHashMap<>(); private final Map<String, ClassLoader> loaders = new ConcurrentHashMap<>(); public ModuleLayer createIsolatedLayer(String layerId, Path modulePath, Set<String> rootModules) throws Exception { ModuleFinder finder = ModuleFinder.of(modulePath); ModuleLayer parent = ModuleLayer.boot(); Configuration config = parent.configuration().resolve( finder, ModuleFinder.of(), rootModules ); // Create completely isolated class loader ClassLoader isolatedLoader = new IsolatedClassLoader(layerId); ModuleLayer layer = parent.defineModulesWithOneLoader(config, isolatedLoader); layers.put(layerId, layer); loaders.put(layerId, isolatedLoader); return layer; } public void destroyLayer(String layerId) { ModuleLayer layer = layers.remove(layerId); ClassLoader loader = loaders.remove(layerId); if (loader instanceof IsolatedClassLoader) { ((IsolatedClassLoader) loader).cleanup(); } // Additional cleanup for layer resources System.out.println("Destroyed layer: " + layerId); } static class IsolatedClassLoader extends ClassLoader { private final String layerId; public IsolatedClassLoader(String layerId) { super(null); // No parent - complete isolation this.layerId = layerId; } public void cleanup() { // Clean up resources, close opened resources, etc. } @Override public String toString() { return "IsolatedClassLoader[" + layerId + "]"; } } }

2. Module Version Management

public class ModuleVersionManager { private final Map<String, List<ModuleLayer>> versionedLayers = new HashMap<>(); /** * Loads specific version of a module */ public ModuleLayer loadModuleVersion(String moduleName, String version, Path versionedPath) throws Exception { ModuleFinder finder = ModuleFinder.of(versionedPath); String versionedModuleName = moduleName + ".v" + version.replace('.', '_'); ModuleLayer bootLayer = ModuleLayer.boot(); Configuration config = bootLayer.configuration().resolve( finder, ModuleFinder.of(), Set.of(versionedModuleName) ); ClassLoader versionedLoader = new VersionedClassLoader(moduleName, version); ModuleLayer versionedLayer = bootLayer.defineModulesWithOneLoader( config, versionedLoader ); versionedLayers.computeIfAbsent(moduleName, k -> new ArrayList<>()) .add(versionedLayer); return versionedLayer; } /** * Gets all loaded versions of a module */ public List<String> getLoadedVersions(String moduleName) { return versionedLayers.getOrDefault(moduleName, List.of()).stream() .map(layer -> extractVersionFromLayer(layer)) .collect(Collectors.toList()); } private String extractVersionFromLayer(ModuleLayer layer) { // Extract version from layer or class loader return "unknown"; } static class VersionedClassLoader extends ClassLoader { private final String moduleName; private final String version; public VersionedClassLoader(String moduleName, String version) { this.moduleName = moduleName; this.version = version; } @Override public String toString() { return "VersionedClassLoader[" + moduleName + "-" + version + "]"; } } }

8. Troubleshooting and Diagnostics

Layer Diagnostics Tool

public class LayerDiagnostics { public static void printLayerHierarchy(ModuleLayer layer, String indent) { System.out.println(indent + "Layer: " + layer); System.out.println(indent + " Parent: " + layer.parents()); System.out.println(indent + " Modules: " + layer.modules().stream() .map(Module::getName) .collect(Collectors.joining(", "))); // Recursively print parent layers for (ModuleLayer parent : layer.parents()) { printLayerHierarchy(parent, indent + " "); } } public static void analyzeLayerConfiguration(ModuleLayer layer) { Configuration config = layer.configuration(); System.out.println("Configuration Analysis:"); System.out.println(" Modules: " + config.modules().size()); config.modules().forEach(module -> { System.out.println(" Module: " + module.name()); System.out.println(" Reads: " + module.reads().stream() .map(ResolvedModule::name) .collect(Collectors.joining(", "))); }); } public static void checkLayerIsolation(ModuleLayer layer1, ModuleLayer layer2) { boolean canAccess = layer1.modules().stream() .anyMatch(module1 -> layer2.modules().stream() .anyMatch(module2 -> module1.getPackages().stream() .anyMatch(pkg -> module2.getPackages().contains(pkg)))); System.out.println("Layer isolation: " + (canAccess ? "BROKEN" : "MAINTAINED")); } }

Summary

Layered modules and runtime images provide:

Module Isolation - Separate module graphs and class loaders
Dynamic Loading - Load modules at runtime
Plugin Architectures - Support for extensible applications
Optimized Deployment - Custom runtime images with jlink
Version Management - Multiple versions of same module

Key benefits:

Better application architecture through clear boundaries
Improved security through module isolation
Smaller deployment footprints with jlink
Dynamic extensibility without application restarts

These features enable building modern, modular, and scalable Java applications that can evolve independently and deploy efficiently.