Loader (JavaCPP 1.3.1 API)

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

Constructors
Constructor and Description
`Loader()`

Method Summary

All Methods Static Methods Concrete Methods
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[]`	`cacheResources(Class cls, String name)` Extracts resources using the `ClassLoader` of the specified `Class`, and returns the cached `File` objects.
`static File[]`	`cacheResources(String name)` Extracts resources using the `ClassLoader` of the caller class, and returns the cached `File` objects.
`static String`	`createLibraryLink(String filename, ClassProperties properties, String libnameversion)` Creates a version-less symbolic link to a library file, if needed.
`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 File[]`	`extractResources(Class cls, String name, File directory, String prefix, String suffix)` Extracts by name resources using the `ClassLoader` of the specified `Class`.
`static File[]`	`extractResources(String name, File directory, String prefix, String suffix)` Extracts by name resources using the `ClassLoader` of the caller.
`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 URL[]`	`findResources(Class cls, String name)` Finds by name resources using the `ClassLoader` of the specified `Class`.
`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)
  - cacheResources
```
public static File[] cacheResources(String name)
                             throws IOException
```
    Extracts resources using the ClassLoader of the caller class, and returns the cached File objects.
    
    Parameters:
    
    name - of the resources passed to findResources(Class, String)
    
    Throws:
    
    IOException
    
    See Also:
    
    cacheResources(Class, String)
  - cacheResources
```
public static File[] cacheResources(Class cls,
                                    String name)
                             throws IOException
```
    Extracts resources using the ClassLoader of the specified Class, and returns the cached File objects.
    
    Parameters:
    
    cls - the Class from which to load resources
    
    name - of the resources passed to findResources(Class, 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)
  - extractResources
```
public static File[] extractResources(String name,
                                      File directory,
                                      String prefix,
                                      String suffix)
                               throws IOException
```
    Extracts by name resources using the ClassLoader of the caller.
    
    Parameters:
    
    name - of the resources passed to findResources(Class, String)
    
    Throws:
    
    IOException
    
    See Also:
    
    extractResources(Class, String, File, String, String)
  - extractResources
```
public static File[] extractResources(Class cls,
                                      String name,
                                      File directory,
                                      String prefix,
                                      String suffix)
                               throws IOException
```
    Extracts by name resources using the ClassLoader of the specified Class.
    
    Parameters:
    
    cls - the Class from which to load resources
    
    name - of the resources passed to findResources(Class, 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
  - findResources
```
public static URL[] findResources(Class cls,
                                  String name)
                           throws IOException
```
    Finds by name resources using the ClassLoader of the specified Class. Names not prefixed with '/' are considered relative to the Class.
    
    Parameters:
    
    cls - the Class from whose ClassLoader to load resources
    
    name - of the resources passed to ClassLoader.getResources(String)
    
    Returns:
    
    URLs to the resources
    
    Throws:
    
    IOException
  - getCacheDir
```
public static File getCacheDir()
                        throws IOException
```
    Creates and returns System.getProperty("org.bytedeco.javacpp.cachedir") or ~/.javacpp/cache/ when not set.
    
    Throws:
    
    IOException
  - 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
  - createLibraryLink
```
public static String createLibraryLink(String filename,
                                       ClassProperties properties,
                                       String libnameversion)
```
    Creates a version-less symbolic link to a library file, if needed.
    
    Parameters:
    
    filename - of the probably versioned library
    
    properties - of the class associated with the library
    
    libnameversion - the library name and version as with loadLibrary(URL[], String)
    
    Returns:
    
    the version-less filename (or null on failure), a symbolic link only if needed
  - 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")

Class Loader

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

logger

PLATFORM

platformProperties

cacheDir

tempDir

loadedLibraries

memberOffsets

Constructor Detail

Loader

Method Detail

getPlatform

loadProperties

loadProperties

getEnclosingClass

loadProperties

loadProperties

getCallerClass

cacheResource

cacheResource

cacheResources

cacheResources

cacheResource

cacheResource

extractResource

extractResource

extractResources

extractResources

extractResource

findResources

getCacheDir

getTempDir

isLoadLibraries

load

load

load

load

findLibrary

loadLibrary

createLibraryLink

putMemberOffset

putMemberOffset

offsetof

sizeof