Package org.zvec.binding

Class NativeLoader

java.lang.Object

org.zvec.binding.NativeLoader

public final class NativeLoader
extends Object

Centralized, three-tier native library loader for the Zvec binding.

The binding depends on two native artifacts: the JavaCPP-generated JNI glue (jnizvec) and the Zvec C-API shared library (zvec_c_api). This loader resolves them with the following precedence, mirroring the JavaCPP runtime model:

1. Explicit path — when -Dzvec.native.path=/dir (or the ZVEC_NATIVE_PATH environment variable) is set, JavaCPP is steered to resolve zvec_c_api from that directory first (via pathsFirst + platform.preloadpath). Intended for local development and custom native builds.
2. Classpath / fat JAR — the default JavaCPP behavior extracts the platform-specific libraries bundled under <platform>/ on the classpath (e.g. inside a self-contained fat JAR) to a cache directory and loads them.
3. System library path — if nothing is bundled, JavaCPP falls back to the operating-system loader search path (java.library.path, LD_LIBRARY_PATH, PATH, ...).

Tier 1 configuration is applied as early as possible from the generated ZvecNative's superclass initializer (presets.ZvecConfig), so it takes effect regardless of which public entry point is touched first. load() simply forces eager loading and converts low-level failures into an actionable UnsatisfiedLinkError.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	PATH_ENV	Environment variable equivalent of PATH_PROPERTY.
static final String	PATH_PROPERTY	System property naming an explicit directory that holds the native libraries.

Method Summary

Modifier and Type	Method	Description
static void	configure()	Steer JavaCPP toward the explicit native directory (tier 1) when one is configured.
static String	explicitPath()	Resolve the configured explicit native directory, or null when neither "zvec.native.path" nor "ZVEC_NATIVE_PATH" is set.
static boolean	isLoaded()	Returns true once the native libraries have been loaded.
static void	load()	Eagerly load the Zvec native libraries, applying the three-tier resolution described in the class documentation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

PATH_PROPERTY

public static final String PATH_PROPERTY

System property naming an explicit directory that holds the native libraries.

See Also:

• Constant Field Values

PATH_ENV

public static final String PATH_ENV

Environment variable equivalent of PATH_PROPERTY.

See Also:

• Constant Field Values

Method Details

explicitPath

public static String explicitPath()

Resolve the configured explicit native directory, or null when neither "zvec.native.path" nor "ZVEC_NATIVE_PATH" is set. The system property takes precedence over the environment variable.

configure

public static void configure()

Steer JavaCPP toward the explicit native directory (tier 1) when one is configured. Safe to call repeatedly and a no-op when no explicit path is set, so it may run during JavaCPP code generation without side effects.

Must run before ZvecNative triggers its own Loader.load(); this is guaranteed by invoking it from the generated class' superclass static initializer.

load

public static void load()

Eagerly load the Zvec native libraries, applying the three-tier resolution described in the class documentation. Idempotent.

Throws:

UnsatisfiedLinkError - if no native library can be resolved

isLoaded

public static boolean isLoaded()

Returns true once the native libraries have been loaded.