13.4 Advanced Linking Patterns and Integration

Apply advanced linking techniques for complex native integrations, library versioning, and production deployment.

Library Abstraction Layer

Creating Platform-Agnostic Wrappers:

import java.lang.foreign.*;
import java.lang.invoke.MethodHandle;
import java.util.Optional;

public abstract class AbstractNativeLibrary implements AutoCloseable {
    protected final Linker linker = Linker.nativeLinker();
    protected final Arena arena = Arena.ofShared();
    protected SymbolLookup symbolLookup;

    /**
     * Initialize library
     */
    protected abstract void initialize() throws Exception;

    /**
     * Get library version
     */
    public abstract String getVersion() throws Throwable;

    /**
     * Helper: Create downcall
     */
    protected MethodHandle createDowncall(
            String symbolName,
            FunctionDescriptor descriptor
    ) {
        MemorySegment symbol = symbolLookup.find(symbolName)
            .orElseThrow(() -> new UnsatisfiedLinkError(
                "Symbol not found: " + symbolName
            ));

        return linker.downcallHandle(symbol, descriptor);
    }

    /**
     * Helper: Optional downcall (for optional functions)
     */
    protected Optional<MethodHandle> createOptionalDowncall(
            String symbolName,
            FunctionDescriptor descriptor
    ) {
        return symbolLookup.find(symbolName)
            .map(symbol -> linker.downcallHandle(symbol, descriptor));
    }

    @Override
    public void close() {
        arena.close();
    }
}

/**
 * Concrete implementation for compression library
 */
public class CompressionLibrary extends AbstractNativeLibrary {
    private MethodHandle compress;
    private MethodHandle uncompress;
    private MethodHandle version;

    public CompressionLibrary() throws Exception {
        initialize();
    }

    @Override
    protected void initialize() throws Exception {
        // Load platform-specific library
        String libName = getPlatformLibraryName();
        System.loadLibrary(libName);
        symbolLookup = SymbolLookup.loaderLookup();

        // Initialize function handles
        compress = createDowncall(
            "compress",
            FunctionDescriptor.of(
                ValueLayout.JAVA_INT,
                ValueLayout.ADDRESS,
                ValueLayout.ADDRESS,
                ValueLayout.ADDRESS,
                ValueLayout.JAVA_LONG
            )
        );

        uncompress = createDowncall(
            "uncompress",
            FunctionDescriptor.of(
                ValueLayout.JAVA_INT,
                ValueLayout.ADDRESS,
                ValueLayout.ADDRESS,
                ValueLayout.ADDRESS,
                ValueLayout.JAVA_LONG
            )
        );

        version = createDowncall(
            "zlibVersion",
            FunctionDescriptor.of(ValueLayout.ADDRESS)
        );
    }

    private String getPlatformLibraryName() {
        String os = System.getProperty("os.name").toLowerCase();
        if (os.contains("win")) {
            return "zlib";
        } else {
            return "z";
        }
    }

    @Override
    public String getVersion() throws Throwable {
        MemorySegment versionPtr = (MemorySegment) version.invoke();
        return versionPtr.reinterpret(Long.MAX_VALUE).getUtf8String(0);
    }

    public byte[] compress(byte[] data) throws Throwable {
        try (Arena localArena = Arena.ofConfined()) {
            long maxSize = data.length + (data.length / 100) + 12;

            MemorySegment source = localArena.allocateArray(
                ValueLayout.JAVA_BYTE,
                data
            );
            MemorySegment dest = localArena.allocate(maxSize);
            MemorySegment destLen = localArena.allocate(ValueLayout.JAVA_LONG);
            destLen.set(ValueLayout.JAVA_LONG, 0, maxSize);

            int result = (int) compress.invoke(dest, destLen, source, (long) data.length);

            if (result != 0) {
                throw new RuntimeException("Compression failed: " + result);
            }

            long compressedSize = destLen.get(ValueLayout.JAVA_LONG, 0);
            return dest.asSlice(0, compressedSize).toArray(ValueLayout.JAVA_BYTE);
        }
    }
}

Version-Specific Loading

Handling Multiple Library Versions:

import java.nio.file.*;
import java.util.*;

public class VersionedLibraryLoader {
    public record LibraryVersion(int major, int minor, int patch) 
            implements Comparable<LibraryVersion> {

        @Override
        public int compareTo(LibraryVersion other) {
            int cmp = Integer.compare(major, other.major);
            if (cmp != 0) return cmp;

            cmp = Integer.compare(minor, other.minor);
            if (cmp != 0) return cmp;

            return Integer.compare(patch, other.patch);
        }

        @Override
        public String toString() {
            return major + "." + minor + "." + patch;
        }
    }

    /**
     * Load library with version requirements
     */
    public SymbolLookup loadLibrary(
            String baseName,
            LibraryVersion minVersion,
            Arena arena
    ) throws Exception {
        List<Path> candidates = findLibraryCandidates(baseName);

        for (Path candidate : candidates) {
            try {
                SymbolLookup lookup = SymbolLookup.libraryLookup(candidate, arena);

                // Check version
                LibraryVersion version = getLibraryVersion(lookup);

                if (version.compareTo(minVersion) >= 0) {
                    System.out.println("Loaded " + baseName + " version " + version);
                    return lookup;
                }

            } catch (Exception e) {
                // Try next candidate
                System.err.println("Failed to load " + candidate + ": " + e.getMessage());
            }
        }

        throw new UnsatisfiedLinkError(
            "Could not find " + baseName + " >= " + minVersion
        );
    }

    private List<Path> findLibraryCandidates(String baseName) {
        List<Path> candidates = new ArrayList<>();
        String os = System.getProperty("os.name").toLowerCase();

        String[] searchPaths = {
            "/usr/lib",
            "/usr/local/lib",
            "/opt/lib",
            System.getProperty("user.home") + "/lib"
        };

        String extension = getLibraryExtension(os);
        String prefix = os.contains("win") ? "" : "lib";

        for (String searchPath : searchPaths) {
            Path dir = Paths.get(searchPath);
            if (Files.isDirectory(dir)) {
                try {
                    Files.list(dir)
                        .filter(p -> p.getFileName().toString()
                            .matches(prefix + baseName + ".*\\." + extension))
                        .forEach(candidates::add);
                } catch (Exception e) {
                    // Ignore
                }
            }
        }

        return candidates;
    }

    private String getLibraryExtension(String os) {
        if (os.contains("win")) return "dll";
        if (os.contains("mac")) return "dylib";
        return "so";
    }

    private LibraryVersion getLibraryVersion(SymbolLookup lookup) throws Throwable {
        // Try to find version function
        Optional<MemorySegment> versionFunc = lookup.find("library_version");

        if (versionFunc.isEmpty()) {
            // Default version if not available
            return new LibraryVersion(1, 0, 0);
        }

        Linker linker = Linker.nativeLinker();
        MethodHandle getVersion = linker.downcallHandle(
            versionFunc.get(),
            FunctionDescriptor.of(ValueLayout.ADDRESS)
        );

        MemorySegment versionStr = (MemorySegment) getVersion.invoke();
        String version = versionStr.reinterpret(Long.MAX_VALUE).getUtf8String(0);

        return parseVersion(version);
    }

    private LibraryVersion parseVersion(String version) {
        String[] parts = version.split("\\.");
        int major = parts.length > 0 ? Integer.parseInt(parts[0]) : 0;
        int minor = parts.length > 1 ? Integer.parseInt(parts[1]) : 0;
        int patch = parts.length > 2 ? Integer.parseInt(parts[2]) : 0;

        return new LibraryVersion(major, minor, patch);
    }
}

Lazy Function Binding

Load Functions On-Demand:

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.function.Supplier;

public class LazyFunctionBinder {
    private final Linker linker = Linker.nativeLinker();
    private final SymbolLookup lookup;
    private final Map<String, MethodHandle> cache = new ConcurrentHashMap<>();

    public LazyFunctionBinder(SymbolLookup lookup) {
        this.lookup = lookup;
    }

    /**
     * Get or create function handle
     */
    public MethodHandle getFunction(String name, FunctionDescriptor descriptor) {
        return cache.computeIfAbsent(name, key -> {
            MemorySegment symbol = lookup.find(name)
                .orElseThrow(() -> new UnsatisfiedLinkError(
                    "Function not found: " + name
                ));

            System.out.println("Binding function: " + name);
            return linker.downcallHandle(symbol, descriptor);
        });
    }

    /**
     * Preload commonly used functions
     */
    public void preload(Map<String, FunctionDescriptor> functions) {
        functions.forEach((name, descriptor) -> {
            try {
                getFunction(name, descriptor);
            } catch (UnsatisfiedLinkError e) {
                System.err.println("Failed to preload: " + name);
            }
        });
    }

    /**
     * Check if function is available
     */
    public boolean hasFunction(String name) {
        return lookup.find(name).isPresent();
    }

    /**
     * Get statistics
     */
    public int getLoadedCount() {
        return cache.size();
    }
}

// Usage example
public class LazyLibrary {
    private final LazyFunctionBinder binder;

    // Descriptors
    private static final FunctionDescriptor STRLEN_DESC = 
        FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS);

    private static final FunctionDescriptor MALLOC_DESC =
        FunctionDescriptor.of(ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);

    public LazyLibrary() {
        System.loadLibrary("c");
        this.binder = new LazyFunctionBinder(SymbolLookup.loaderLookup());

        // Optionally preload critical functions
        Map<String, FunctionDescriptor> critical = Map.of(
            "strlen", STRLEN_DESC,
            "malloc", MALLOC_DESC
        );
        binder.preload(critical);
    }

    public long strlen(MemorySegment str) throws Throwable {
        MethodHandle strlen = binder.getFunction("strlen", STRLEN_DESC);
        return (long) strlen.invoke(str);
    }

    public MemorySegment malloc(long size) throws Throwable {
        MethodHandle malloc = binder.getFunction("malloc", MALLOC_DESC);
        return (MemorySegment) malloc.invoke(size);
    }
}

Function Pointer Tables

Managing Function Pointer Tables:

public class FunctionTable {
    private final Arena arena;
    private final MemorySegment table;
    private final Map<String, Integer> indices = new HashMap<>();
    private int nextIndex = 0;

    public FunctionTable(Arena arena, int maxFunctions) {
        this.arena = arena;
        this.table = arena.allocate(
            ValueLayout.ADDRESS.byteSize() * maxFunctions
        );
    }

    /**
     * Add function to table
     */
    public int addFunction(String name, MemorySegment functionPtr) {
        if (indices.containsKey(name)) {
            return indices.get(name);
        }

        int index = nextIndex++;
        table.set(
            ValueLayout.ADDRESS,
            index * ValueLayout.ADDRESS.byteSize(),
            functionPtr
        );

        indices.put(name, index);
        return index;
    }

    /**
     * Get function from table
     */
    public MemorySegment getFunction(String name) {
        Integer index = indices.get(name);
        if (index == null) {
            throw new IllegalArgumentException("Function not found: " + name);
        }

        return table.get(
            ValueLayout.ADDRESS,
            index * ValueLayout.ADDRESS.byteSize()
        );
    }

    /**
     * Get function by index
     */
    public MemorySegment getFunction(int index) {
        return table.get(
            ValueLayout.ADDRESS,
            index * ValueLayout.ADDRESS.byteSize()
        );
    }

    /**
     * Get table pointer (for passing to native code)
     */
    public MemorySegment getTablePointer() {
        return table;
    }

    public int getFunctionCount() {
        return nextIndex;
    }
}

Real-World Example: Plugin System

import java.lang.foreign.*;
import java.lang.invoke.MethodHandle;
import java.nio.file.*;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;

public class PluginSystem implements AutoCloseable {
    private final Linker linker = Linker.nativeLinker();
    private final Arena arena = Arena.ofShared();
    private final Map<String, Plugin> plugins = new ConcurrentHashMap<>();

    public static class Plugin {
        public final String name;
        public final Path libraryPath;
        public final SymbolLookup lookup;
        public final String version;
        public final Map<String, MethodHandle> functions = new HashMap<>();

        public Plugin(String name, Path libraryPath, SymbolLookup lookup, String version) {
            this.name = name;
            this.libraryPath = libraryPath;
            this.lookup = lookup;
            this.version = version;
        }
    }

    /**
     * Load plugin from path
     */
    public Plugin loadPlugin(Path pluginPath) throws Exception {
        if (!Files.exists(pluginPath)) {
            throw new IllegalArgumentException("Plugin not found: " + pluginPath);
        }

        // Load library
        SymbolLookup lookup = SymbolLookup.libraryLookup(pluginPath, arena);

        // Get plugin info
        String name = getPluginName(lookup);
        String version = getPluginVersion(lookup);

        if (plugins.containsKey(name)) {
            throw new IllegalStateException("Plugin already loaded: " + name);
        }

        Plugin plugin = new Plugin(name, pluginPath, lookup, version);

        // Initialize plugin
        initializePlugin(plugin);

        plugins.put(name, plugin);
        System.out.println("Loaded plugin: " + name + " v" + version);

        return plugin;
    }

    private String getPluginName(SymbolLookup lookup) throws Throwable {
        MethodHandle getName = linker.downcallHandle(
            lookup.find("plugin_name").orElseThrow(),
            FunctionDescriptor.of(ValueLayout.ADDRESS)
        );

        MemorySegment namePtr = (MemorySegment) getName.invoke();
        return namePtr.reinterpret(Long.MAX_VALUE).getUtf8String(0);
    }

    private String getPluginVersion(SymbolLookup lookup) throws Throwable {
        MethodHandle getVersion = linker.downcallHandle(
            lookup.find("plugin_version").orElseThrow(),
            FunctionDescriptor.of(ValueLayout.ADDRESS)
        );

        MemorySegment versionPtr = (MemorySegment) getVersion.invoke();
        return versionPtr.reinterpret(Long.MAX_VALUE).getUtf8String(0);
    }

    private void initializePlugin(Plugin plugin) throws Throwable {
        // Call plugin initialization
        Optional<MemorySegment> initFunc = plugin.lookup.find("plugin_init");

        if (initFunc.isPresent()) {
            MethodHandle init = linker.downcallHandle(
                initFunc.get(),
                FunctionDescriptor.of(ValueLayout.JAVA_INT)
            );

            int result = (int) init.invoke();
            if (result != 0) {
                throw new RuntimeException("Plugin initialization failed: " + result);
            }
        }
    }

    /**
     * Call plugin function
     */
    public Object callPluginFunction(
            String pluginName,
            String functionName,
            FunctionDescriptor descriptor,
            Object... args
    ) throws Throwable {
        Plugin plugin = plugins.get(pluginName);
        if (plugin == null) {
            throw new IllegalArgumentException("Plugin not loaded: " + pluginName);
        }

        // Get or create function handle
        MethodHandle handle = plugin.functions.computeIfAbsent(
            functionName,
            name -> {
                MemorySegment symbol = plugin.lookup.find(name)
                    .orElseThrow(() -> new UnsatisfiedLinkError(
                        "Function not found: " + name
                    ));
                return linker.downcallHandle(symbol, descriptor);
            }
        );

        // Invoke function
        return handle.invokeWithArguments(args);
    }

    /**
     * Unload plugin
     */
    public void unloadPlugin(String name) throws Throwable {
        Plugin plugin = plugins.remove(name);
        if (plugin == null) {
            return;
        }

        // Call cleanup function if available
        Optional<MemorySegment> cleanupFunc = plugin.lookup.find("plugin_cleanup");

        if (cleanupFunc.isPresent()) {
            try {
                MethodHandle cleanup = linker.downcallHandle(
                    cleanupFunc.get(),
                    FunctionDescriptor.ofVoid()
                );
                cleanup.invoke();
            } catch (Throwable t) {
                System.err.println("Plugin cleanup failed: " + t.getMessage());
            }
        }

        System.out.println("Unloaded plugin: " + name);
    }

    /**
     * List loaded plugins
     */
    public Set<String> getLoadedPlugins() {
        return new HashSet<>(plugins.keySet());
    }

    /**
     * Get plugin info
     */
    public Optional<Plugin> getPluginInfo(String name) {
        return Optional.ofNullable(plugins.get(name));
    }

    @Override
    public void close() throws Exception {
        // Unload all plugins
        List<String> pluginNames = new ArrayList<>(plugins.keySet());
        for (String name : pluginNames) {
            unloadPlugin(name);
        }

        arena.close();
    }

    // Example usage
    public static void main(String[] args) {
        try (PluginSystem system = new PluginSystem()) {
            // Load plugins
            Path pluginDir = Paths.get("plugins");

            if (Files.exists(pluginDir)) {
                Files.list(pluginDir)
                    .filter(p -> p.toString().endsWith(".so") || 
                                p.toString().endsWith(".dylib"))
                    .forEach(pluginPath -> {
                        try {
                            system.loadPlugin(pluginPath);
                        } catch (Exception e) {
                            System.err.println("Failed to load " + pluginPath + ": " + e);
                        }
                    });
            }

            // List loaded plugins
            System.out.println("Loaded plugins: " + system.getLoadedPlugins());

            // Call plugin functions
            // Example: int process_data(const char *input)
            for (String plugin : system.getLoadedPlugins()) {
                try (Arena localArena = Arena.ofConfined()) {
                    MemorySegment input = localArena.allocateUtf8String("test");

                    Object result = system.callPluginFunction(
                        plugin,
                        "process_data",
                        FunctionDescriptor.of(
                            ValueLayout.JAVA_INT,
                            ValueLayout.ADDRESS
                        ),
                        input
                    );

                    System.out.println(plugin + " returned: " + result);
                } catch (Exception e) {
                    System.err.println("Plugin call failed: " + e);
                }
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Performance Optimization

Optimized Function Calls:

public class OptimizedCalls {
    // Cache everything possible
    private static final Linker LINKER = Linker.nativeLinker();
    private static final SymbolLookup LOOKUP = LINKER.defaultLookup();

    // Static initialization for hot path functions
    private static final MethodHandle STRLEN;
    private static final MethodHandle MEMCPY;

    static {
        try {
            STRLEN = LINKER.downcallHandle(
                LOOKUP.find("strlen").orElseThrow(),
                FunctionDescriptor.of(
                    ValueLayout.JAVA_LONG,
                    ValueLayout.ADDRESS
                )
            );

            MEMCPY = LINKER.downcallHandle(
                LOOKUP.find("memcpy").orElseThrow(),
                FunctionDescriptor.of(
                    ValueLayout.ADDRESS,
                    ValueLayout.ADDRESS,
                    ValueLayout.ADDRESS,
                    ValueLayout.JAVA_LONG
                )
            );
        } catch (Exception e) {
            throw new ExceptionInInitializerError(e);
        }
    }

    /**
     * Hot path: optimized strlen call
     */
    public static long strlen(MemorySegment str) throws Throwable {
        return (long) STRLEN.invokeExact(str);  // Use invokeExact for performance
    }

    /**
     * Batch operations with reused arena
     */
    public static void batchProcess(List<String> strings) throws Throwable {
        try (Arena arena = Arena.ofConfined()) {
            for (String str : strings) {
                MemorySegment segment = arena.allocateUtf8String(str);
                long len = strlen(segment);
                // Process...
            }
        }
    }
}

Best Practices Summary

1. Library Lifecycle Management:

• Use try-with-resources for arenas
• Initialize libraries at startup
• Clean up in reverse order of initialization

2. Error Handling:

• Validate library versions
• Provide fallbacks for missing functions
• Log all failures with context

3. Performance:

• Cache MethodHandles aggressively
• Use appropriate arena types
• Minimize marshalling overhead

4. Maintainability:

• Abstract platform differences
• Document native dependencies
• Version all native interfaces

5. Testing:

• Mock native interfaces for unit tests
• Test on all target platforms
• Validate library versions in CI/CD

These advanced patterns enable robust, production-ready native integrations.