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 Map<String,String>	loadedLibraries Contains all the native libraries that we have loaded to avoid reloading them.
(package private) static boolean	loadLibraries Flag set by the Builder to tell us not to try to load anything.
(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

Methods

Modifier and Type	Method and Description
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 directory, 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) Finds where the library may be extracted and loaded among the Class resources.
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()
static String	load() Loads native libraries associated with the Class of the caller.
static String	load(Class cls) 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) Loads from resources the default Properties of the specified platform name.
static void	main(String[] args)
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 void	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

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().

tempDir

static File tempDir

Temporary directory set and returned by getTempDir().

loadLibraries

static boolean loadLibraries

Flag set by the Builder to tell us not to try to load anything.

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().

See Also:

loadProperties(String)

loadProperties

public static Properties loadProperties(String name)

Loads from resources the default Properties of the specified platform name.

Parameters:

name - the platform name

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

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 directory,
                   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 the directory must not be null.

Parameters:

resourceURL - the URL of the resource to extract

directory - the output directory (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

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:

loadLibraries

load

public static String load()

Loads native libraries associated with the Class of the caller.

Returns:

load(getCallerClass(2))

See Also:

getCallerClass(int), load(Class)

load

public static String load(Class cls)

Loads native libraries associated with the given Class.

Parameters:

cls - the Class to get native library information from

Returns:

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

Throws:

NoClassDefFoundError - on Class initialization failure

UnsatisfiedLinkError - on native library loading failure

findLibrary

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

Finds where the library may be extracted and loaded among the Class resources. But in case that fails, also searches the paths found in the "platform.preloadpath" and "platform.linkpath" properties.

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

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

Returns:

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

Throws:

UnsatisfiedLinkError - on failure

main

public static void main(String[] args)

putMemberOffset

static void 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

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

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")