org.bytedeco.javacpp

Class Loader

java.lang.Object

org.bytedeco.javacpp.Loader

public class Loader
extends Object

The Loader contains functionality to load native libraries, but also has a bit of everything that does not fit anywhere else. In addition to its library loading features, it also has utility methods to get the platform name, to load properties from Java resources and from Class annotations, to extract file resources to the temporary directory, and to get the offsetof() or sizeof() a native struct, class, or union with its Pointer peer class and a HashMap initialized by the native libraries inside JNI_OnLoad().

Author:

Samuel Audet

Field Summary

Fields

Modifier and Type	Field and Description
(package private) static File	cacheDir User-specified cache directory set and returned by getCacheDir().
(package private) static Map<String,String>	loadedLibraries Contains all the native libraries that we have loaded to avoid reloading them.
private static Logger	logger
(package private) static WeakHashMap<Class<? extends Pointer>,HashMap<String,Integer>>	memberOffsets Contains offsetof() and sizeof() values of native types of struct, class, and union.
private static String	PLATFORM Value created out of "java.vm.name", "os.name", and "os.arch" system properties.
private static Properties	platformProperties Default platform properties loaded and returned by loadProperties().
(package private) static File	tempDir Temporary directory set and returned by getTempDir().

Constructor Summary

Constructors

Constructor and Description
Loader()

Method Summary

Modifier and Type	Method and Description
static File	cacheResource(Class cls, String name) Extracts a resource using the ClassLoader of the specified Class, and returns the cached File.
static File	cacheResource(String name) Extracts a resource using the ClassLoader of the caller class, and returns the cached File.
static File	cacheResource(URL resourceURL) Returns cacheResource(resourceUrl, null)
static File	cacheResource(URL resourceURL, String target) Extracts a resource, if the size or last modified timestamp differs from what is in cache, and returns the cached File.
static File	extractResource(Class cls, String name, File directory, String prefix, String suffix) Extracts by name a resource using the ClassLoader of the specified Class.
static File	extractResource(String name, File directory, String prefix, String suffix) Extracts by name a resource using the ClassLoader of the caller.
static File	extractResource(URL resourceURL, File directoryOrFile, String prefix, String suffix) Extracts a resource into the specified directory and with the specified prefix and suffix for the filename.
static URL[]	findLibrary(Class cls, ClassProperties properties, String libnameversion, boolean pathsFirst) Finds from where the library may be extracted and loaded among the Class resources.
static File	getCacheDir() Creates and returns System.getProperty("org.bytedeco.javacpp.cachedir") or ~/.javacpp/cache/ when not set.
static Class	getCallerClass(int i) Returns the Class object that contains a caller's method.
static Class	getEnclosingClass(Class cls) If annotated with properties, returns the argument as "enclosing Class".
static String	getPlatform() Returns either the value of the "org.bytedeco.javacpp.platform" system property, or PLATFORM when the former is not set.
static File	getTempDir() Creates a unique name for tempDir out of System.getProperty("java.io.tmpdir") and System.nanoTime().
static boolean	isLoadLibraries() Returns System.getProperty("org.bytedeco.javacpp.loadlibraries").
static String	load() Returns load(getCallerClass(2), loadProperties(), false).
static String	load(boolean pathsFirst) Loads native libraries associated with the Class of the caller.
static String	load(Class cls) Returns load(cls, loadProperties(), false).
static String	load(Class cls, Properties properties, boolean pathsFirst) Loads native libraries associated with the given Class.
static String	loadLibrary(URL[] urls, String libnameversion) Tries to load the library from the URLs in order, extracting resources as necessary.
static Properties	loadProperties() Loads the Properties associated with the default getPlatform().
static ClassProperties	loadProperties(Class[] cls, Properties properties, boolean inherit) For all the classes, loads all properties from each Class annotations for the given platform.
static ClassProperties	loadProperties(Class cls, Properties properties, boolean inherit) Loads all properties from Class annotations for the given platform.
static Properties	loadProperties(String name, String defaults) Loads from resources the default Properties of the specified platform name.
static int	offsetof(Class<? extends Pointer> type, String member) Gets offsetof() values from memberOffsets filled by native libraries.
(package private) static void	putMemberOffset(Class<? extends Pointer> type, String member, int offset) Called by native libraries to put offsetof() and sizeof() values in memberOffsets.
(package private) static Class	putMemberOffset(String typeName, String member, int offset) Called by native libraries to put offsetof() and sizeof() values in memberOffsets.
static int	sizeof(Class<? extends Pointer> type) Gets sizeof() values from memberOffsets filled by native libraries.

Methods inherited from class java.lang.Object

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

Field Detail

logger

private static final Logger logger

PLATFORM

private static final String PLATFORM

Value created out of "java.vm.name", "os.name", and "os.arch" system properties. Returned by getPlatform() as default.

platformProperties

private static Properties platformProperties

Default platform properties loaded and returned by loadProperties().

cacheDir

static File cacheDir

User-specified cache directory set and returned by getCacheDir().

tempDir

static File tempDir

Temporary directory set and returned by getTempDir().

loadedLibraries

static Map<String,String> loadedLibraries

Contains all the native libraries that we have loaded to avoid reloading them.

memberOffsets

static WeakHashMap<Class<? extends Pointer>,HashMap<String,Integer>> memberOffsets

Contains offsetof() and sizeof() values of native types of struct, class, and union. A WeakHashMap is used to prevent the Loader from hanging onto Class objects the user may be trying to unload.

Constructor Detail

Loader

public Loader()

Method Detail

getPlatform

public static String getPlatform()

Returns either the value of the "org.bytedeco.javacpp.platform" system property, or PLATFORM when the former is not set.

Returns:

System.getProperty("org.bytedeco.javacpp.platform", platform)

See Also:

PLATFORM

loadProperties

public static Properties loadProperties()

Loads the Properties associated with the default getPlatform().

Returns:

loadProperties(getPlatform(), null)

See Also:

loadProperties(String, String)

loadProperties

public static Properties loadProperties(String name,
                                        String defaults)

Loads from resources the default Properties of the specified platform name. The resource must be at "org/bytedeco/javacpp/properties/" + name + ".properties".

Parameters:

name - the platform name

defaults - the fallback platform name (null == "generic")

Returns:

the Properties from resources

getEnclosingClass

public static Class getEnclosingClass(Class cls)

If annotated with properties, returns the argument as "enclosing Class". If no properties are found on the Class, makes a search for the first Class with properties that we can use, and returns it as the enclosing Class found.

Parameters:

cls - the Class to start the search from

Returns:

the enclosing Class

See Also:

Platform, Properties

loadProperties

public static ClassProperties loadProperties(Class[] cls,
                                             Properties properties,
                                             boolean inherit)

For all the classes, loads all properties from each Class annotations for the given platform.

See Also:

loadProperties(Class, java.util.Properties, boolean)

loadProperties

public static ClassProperties loadProperties(Class cls,
                                             Properties properties,
                                             boolean inherit)

Loads all properties from Class annotations for the given platform. The platform of interest needs to be specified as the value of the "platform" key in the properties argument. It is also possible to indicate whether to load all the classes specified in the Properties.inherit() annotation recursively via the inherit argument.

Parameters:

cls - the Class of which to return Properties

properties - the platform Properties to inherit

inherit - indicates whether or not to inherit properties from other classes

Returns:

all the properties associated with the Class for the given platform

getCallerClass

public static Class getCallerClass(int i)

Returns the Class object that contains a caller's method.

Parameters:

i - the offset on the call stack of the method of interest

Returns:

the Class found from the calling context, or null if not found

cacheResource

public static File cacheResource(String name)
                          throws IOException

Extracts a resource using the ClassLoader of the caller class, and returns the cached File.

Parameters:

name - the name of the resource passed to Class.getResource(String)

Throws:

IOException

See Also:

cacheResource(Class, String)

cacheResource

public static File cacheResource(Class cls,
                                 String name)
                          throws IOException

Extracts a resource using the ClassLoader of the specified Class, and returns the cached File.

Parameters:

cls - the Class from which to load resources

name - the name of the resource passed to Class.getResource(String)

Throws:

IOException

See Also:

cacheResource(URL)

cacheResource

public static File cacheResource(URL resourceURL)
                          throws IOException

Returns cacheResource(resourceUrl, null)

Throws:

IOException

cacheResource

public static File cacheResource(URL resourceURL,
                                 String target)
                          throws IOException

Extracts a resource, if the size or last modified timestamp differs from what is in cache, and returns the cached File. If target is not null, creates instead a symbolic link where the resource would have been extracted.

Parameters:

resourceURL - the URL of the resource to extract and cache

target - of the symbolic link to create (must be null to have the resource actually extracted)

Returns:

the File object representing the extracted file from the cache

Throws:

IOException - if fails to extract resource properly

See Also:

extractResource(URL, File, String, String), cacheDir

extractResource

public static File extractResource(String name,
                                   File directory,
                                   String prefix,
                                   String suffix)
                            throws IOException

Extracts by name a resource using the ClassLoader of the caller.

Parameters:

name - the name of the resource passed to Class.getResource(String)

Throws:

IOException

See Also:

extractResource(URL, File, String, String)

extractResource

public static File extractResource(Class cls,
                                   String name,
                                   File directory,
                                   String prefix,
                                   String suffix)
                            throws IOException

Extracts by name a resource using the ClassLoader of the specified Class.

Parameters:

cls - the Class from which to load resources

name - the name of the resource passed to Class.getResource(String)

Throws:

IOException

See Also:

extractResource(URL, File, String, String)

extractResource

public static File extractResource(URL resourceURL,
                                   File directoryOrFile,
                                   String prefix,
                                   String suffix)
                            throws IOException

Extracts a resource into the specified directory and with the specified prefix and suffix for the filename. If both prefix and suffix are null, the original filename is used, so directoryOrFile must not be null.

Parameters:

resourceURL - the URL of the resource to extract

directoryOrFile - the output directory or file (null == System.getProperty("java.io.tmpdir"))

prefix - the prefix of the temporary filename to use

suffix - the suffix of the temporary filename to use

Returns:

the File object representing the extracted file

Throws:

IOException - if fails to extract resource properly

getCacheDir

public static File getCacheDir()

Creates and returns System.getProperty("org.bytedeco.javacpp.cachedir") or ~/.javacpp/cache/ when not set.

getTempDir

public static File getTempDir()

Creates a unique name for tempDir out of System.getProperty("java.io.tmpdir") and System.nanoTime().

Returns:

tempDir

isLoadLibraries

public static boolean isLoadLibraries()

Returns System.getProperty("org.bytedeco.javacpp.loadlibraries"). Flag set by the Builder to tell us not to try to load anything.

load

public static String load()

Returns load(getCallerClass(2), loadProperties(), false).

load

public static String load(boolean pathsFirst)

Loads native libraries associated with the Class of the caller.

Parameters:

pathsFirst - search the paths first before bundled resources

Returns:

load(getCallerClass(2), loadProperties(), pathsFirst)

See Also:

getCallerClass(int), load(Class, Properties, boolean)

load

public static String load(Class cls)

Returns load(cls, loadProperties(), false).

load

public static String load(Class cls,
                          Properties properties,
                          boolean pathsFirst)

Loads native libraries associated with the given Class.

Parameters:

cls - the Class to get native library information from

properties - the platform Properties to inherit

pathsFirst - search the paths first before bundled resources

Returns:

the full path to the main file loaded, or the library name if unknown (but if (!isLoadLibraries() || cls == null) { return null; })

Throws:

NoClassDefFoundError - on Class initialization failure

UnsatisfiedLinkError - on native library loading failure

See Also:

findLibrary(Class, ClassProperties, String, boolean), loadLibrary(URL[], String)

findLibrary

public static URL[] findLibrary(Class cls,
                                ClassProperties properties,
                                String libnameversion,
                                boolean pathsFirst)

Finds from where the library may be extracted and loaded among the Class resources. But in case that fails, and depending on the value of pathsFirst, either as a fallback or in priority over bundled resources, also searches the paths found in the "platform.preloadpath" and "platform.linkpath" class properties as well as the "java.library.path" system property, in that order.

Parameters:

cls - the Class whose package name and ClassLoader are used to extract from resources

properties - contains the directories to scan for if we fail to extract the library from resources

libnameversion - the name of the library + "@" + optional version tag + "#" + a second optional name used at extraction (or empty to prevent it)

pathsFirst - search the paths first before bundled resources

Returns:

URLs that point to potential locations of the library

loadLibrary

public static String loadLibrary(URL[] urls,
                                 String libnameversion)

Tries to load the library from the URLs in order, extracting resources as necessary. Finally, if all fails, falls back on System.loadLibrary(String).

Parameters:

urls - the URLs to try loading the library from

libnameversion - the name of the library + "@" + optional version tag + "#" + a second optional name used at extraction

Returns:

the full path of the file loaded, or the library name if unknown (but if (!isLoadLibraries) { return null; })

Throws:

UnsatisfiedLinkError - on failure

putMemberOffset

static Class putMemberOffset(String typeName,
                             String member,
                             int offset)
                      throws ClassNotFoundException

Called by native libraries to put offsetof() and sizeof() values in memberOffsets. Tries to load the Class object for typeName using the ClassLoader of the Loader.

Parameters:

typeName - the name of the peer Class acting as interface to the native type

member - the name of the native member variable (can be null to retrieve the Class object only)

offset - the value of offsetof() (or sizeof() when member.equals("sizeof"))

Returns:

Class.forName(typeName, false)

Throws:

ClassNotFoundException - on Class initialization failure

putMemberOffset

static void putMemberOffset(Class<? extends Pointer> type,
                            String member,
                            int offset)

Called by native libraries to put offsetof() and sizeof() values in memberOffsets.

Parameters:

type - the peer Class acting as interface to the native type

member - the name of the native member variable

offset - the value of offsetof() (or sizeof() when member.equals("sizeof"))

offsetof

public static int offsetof(Class<? extends Pointer> type,
                           String member)

Gets offsetof() values from memberOffsets filled by native libraries.

Parameters:

type - the peer Class acting as interface to the native type

member - the name of the native member variable

Returns:

memberOffsets.get(type).get(member)

sizeof

public static int sizeof(Class<? extends Pointer> type)

Gets sizeof() values from memberOffsets filled by native libraries.

Parameters:

type - the peer Class acting as interface to the native type

Returns:

memberOffsets.get(type).get("sizeof")