@Properties(inherit=javacpp.class) public class Loader extends Object
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()
.Modifier and Type | Field and Description |
---|---|
(package private) static File |
cacheDir
User-specified cache directory set and returned by
getCacheDir() . |
private static ThreadLocal<Deque<Class<?>>> |
classStack
The stack of classes currently being loaded to support more than one class loader.
|
(package private) static Map<String,URL[]> |
foundLibraries
Contains all the URLs of native libraries that we found to avoid searching for them again.
|
(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 . |
(package private) static boolean |
pathsFirst |
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 and Description |
---|
Loader() |
Modifier and Type | Method and Description |
---|---|
static Pointer |
addressof(String symbol)
Returns the address found under the given name in the "dynamic symbol tables" (Linux, Mac OS X, etc)
or the "export tables" (Windows) of all libraries loaded, or null if not found.
|
static File |
cacheResource(Class cls,
String name)
|
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 boolean |
checkPlatform(Class<?> cls,
Properties properties) |
static boolean |
checkPlatform(Platform platform,
Properties properties,
String... defaultNames) |
static boolean |
checkVersion(String groupId,
String artifactId)
Returns
checkVersion(groupId, artifactId, "-", true, getCallerClass(2)) . |
static boolean |
checkVersion(String groupId,
String artifactId,
String separator,
boolean logWarnings,
Class cls)
Returns
getVersion(groupId, artifactId, cls).split(separator)[n].equals(getVersion().split(separator)[0])
where n = versions.length - (versions[versions.length - 1].equals("SNAPSHOT") ? 2 : 1) or false on error. |
static String |
createLibraryLink(String filename,
ClassProperties properties,
String libnameversion,
String... paths)
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)
Returns
extractResource(resourceURL, directoryOrFile, prefix, suffix, false) . |
static File |
extractResource(URL resourceURL,
File directoryOrFile,
String prefix,
String suffix,
boolean cacheDirectory)
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)
Returns
findLibrary(cls, properties, libnameversion, Loader.pathsFirst) . |
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 |
findResource(Class cls,
String name)
Returns
findResources(cls, name, 1)[0] or null if none. |
static URL[] |
findResources(Class cls,
String name)
Returns
findResources(cls, name, -1) . |
static URL[] |
findResources(Class cls,
String name,
int maxLength)
Finds by name resources using the
Class and its ClassLoader . |
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 Pointer |
getJavaVM()
Returns the JavaVM JNI object, as required by some APIs for initialization.
|
static Map<String,String> |
getLoadedLibraries()
Returns a Map that relates each library name to the path of the loaded file.
|
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 String |
getVersion()
Returns
getVersion("org.bytedeco", "javacpp") . |
static String |
getVersion(String groupId,
String artifactId)
Returns
getVersion(groupId, artifactId, getCallerClass(2)) . |
static String |
getVersion(String groupId,
String artifactId,
Class cls)
Returns version property from
cls.getResource("META-INF/maven/" + groupId + "/" + artifactId + "/pom.properties") . |
static boolean |
isLoadLibraries()
Returns
System.getProperty("org.bytedeco.javacpp.loadlibraries") . |
static String |
load()
Returns
load(getCallerClass(2), loadProperties(), Loader.pathsFirst) . |
static String |
load(boolean pathsFirst)
Loads native libraries associated with the
Class of the caller and initializes it. |
static String[] |
load(Class... classes)
Returns
load(classes, true) . |
static String |
load(Class cls)
Returns
load(cls, loadProperties(), Loader.pathsFirst) . |
static String[] |
load(Class[] classes,
boolean logMessages)
Calls
load(Class) on all top-level enclosing classes found in the array. |
static String |
load(Class cls,
Properties properties,
boolean pathsFirst)
Loads native libraries associated with the given
Class and initializes it. |
static void |
loadGlobal(String filename)
Loads all symbols from a library globally, that is
dlopen(filename, RTLD_LAZY | RTLD_GLOBAL) ,
or simply by default with LoadLibrary(filename) on Windows. |
static String |
loadLibrary(Class<?> cls,
String libnameversion,
String... preloaded)
Returns
loadLibrary(findResources(cls, libnameversion), libnameversion, preloaded) . |
static String |
loadLibrary(Class<?> cls,
URL[] urls,
String libnameversion,
String... preloaded)
Tries to load the library from the URLs in order, extracting resources as necessary.
|
static String |
loadLibrary(String libnameversion,
String... preloaded)
Returns
loadLibrary(getCallerClass(2), libnameversion, preloaded) . |
static String |
loadLibrary(URL[] urls,
String libnameversion,
String... preloaded)
Returns
loadLibrary(null, urls, libnameversion, preloaded) . |
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)
|
(package private) static Class |
putMemberOffset(String typeName,
String member,
int offset)
|
static int |
sizeof(Class<? extends Pointer> type)
Gets
sizeof() values from memberOffsets filled by native libraries. |
static int |
totalChips()
Returns the number of CPU chips installed according to the operating system, or 0 if unknown.
|
static int |
totalCores()
Returns the number of CPU cores usable according to the operating system, or 0 if unknown.
|
static int |
totalProcessors()
Returns the number of processors configured according to the operating system, or 0 if unknown.
|
private static final Logger logger
private static final String PLATFORM
getPlatform()
as default.private static Properties platformProperties
loadProperties()
.private static final ThreadLocal<Deque<Class<?>>> classStack
static File cacheDir
getCacheDir()
.static File tempDir
getTempDir()
.static Map<String,URL[]> foundLibraries
static Map<String,String> loadedLibraries
static boolean pathsFirst
static WeakHashMap<Class<? extends Pointer>,HashMap<String,Integer>> memberOffsets
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.public static String getPlatform()
PLATFORM
when the former is not set.System.getProperty("org.bytedeco.javacpp.platform", platform)
PLATFORM
public static Properties loadProperties()
Properties
associated with the default getPlatform()
.loadProperties(getPlatform(), null)
loadProperties(String, String)
public static Properties loadProperties(String name, String defaults)
Properties
of the specified platform name.
The resource must be at "org/bytedeco/javacpp/properties/" + name + ".properties"
.name
- the platform namedefaults
- the fallback platform name (null == "generic")public static boolean checkVersion(String groupId, String artifactId)
checkVersion(groupId, artifactId, "-", true, getCallerClass(2))
.public static boolean checkVersion(String groupId, String artifactId, String separator, boolean logWarnings, Class cls)
getVersion(groupId, artifactId, cls).split(separator)[n].equals(getVersion().split(separator)[0])
where n = versions.length - (versions[versions.length - 1].equals("SNAPSHOT") ? 2 : 1)
or false on error.
Also calls Logger.warn(String)
on error when logWarnings && isLoadLibraries()
.public static String getVersion() throws IOException
getVersion("org.bytedeco", "javacpp")
.IOException
public static String getVersion(String groupId, String artifactId) throws IOException
getVersion(groupId, artifactId, getCallerClass(2))
.IOException
public static String getVersion(String groupId, String artifactId, Class cls) throws IOException
cls.getResource("META-INF/maven/" + groupId + "/" + artifactId + "/pom.properties")
.IOException
public static Class getEnclosingClass(Class cls)
cls
- the Class to start the search fromPlatform
,
Properties
public static ClassProperties loadProperties(Class[] cls, Properties properties, boolean inherit)
public static ClassProperties loadProperties(Class cls, Properties properties, boolean inherit)
Properties.inherit()
annotation recursively via the inherit argument.cls
- the Class of which to return Propertiesproperties
- the platform Properties to inheritinherit
- indicates whether or not to inherit properties from other classespublic static Class getCallerClass(int i)
Class
object that contains a caller's method.i
- the offset on the call stack of the method of interestnull
if not foundpublic static File cacheResource(String name) throws IOException
ClassLoader
of the caller class,
and returns the cached File
.name
- the name of the resource passed to Class.getResource(String)
IOException
cacheResource(Class, String)
public static File cacheResource(Class cls, String name) throws IOException
cls
- the Class from which to load resourcesname
- the name of the resource passed to Class.getResource(String)
IOException
cacheResource(URL)
public static File[] cacheResources(String name) throws IOException
ClassLoader
of the caller class,
and returns the cached File
objects.name
- of the resources passed to findResources(Class, String)
IOException
cacheResources(Class, String)
public static File[] cacheResources(Class cls, String name) throws IOException
ClassLoader
of the specified Class
,
and returns the cached File
objects.cls
- the Class from which to load resourcesname
- of the resources passed to findResources(Class, String)
IOException
cacheResource(URL)
public static File cacheResource(URL resourceURL) throws IOException
cacheResource(resourceUrl, null)
IOException
public static File cacheResource(URL resourceURL, String target) throws IOException
File
. If target is not null, creates instead a symbolic link
where the resource would have been extracted.resourceURL
- the URL of the resource to extract and cachetarget
- of the symbolic link to create (must be null to have the resource actually extracted)IOException
- if fails to extract resource properlyextractResource(URL, File, String, String)
,
cacheDir
public static File extractResource(String name, File directory, String prefix, String suffix) throws IOException
ClassLoader
of the caller.name
- the name of the resource passed to Class.getResource(String)
IOException
extractResource(URL, File, String, String)
public static File extractResource(Class cls, String name, File directory, String prefix, String suffix) throws IOException
ClassLoader
of the specified Class
.cls
- the Class from which to load resourcesname
- the name of the resource passed to Class.getResource(String)
IOException
extractResource(URL, File, String, String)
public static File[] extractResources(String name, File directory, String prefix, String suffix) throws IOException
ClassLoader
of the caller.name
- of the resources passed to findResources(Class, String)
IOException
extractResources(Class, String, File, String, String)
public static File[] extractResources(Class cls, String name, File directory, String prefix, String suffix) throws IOException
ClassLoader
of the specified Class
.cls
- the Class from which to load resourcesname
- of the resources passed to findResources(Class, String)
IOException
extractResource(URL, File, String, String)
public static File extractResource(URL resourceURL, File directoryOrFile, String prefix, String suffix) throws IOException
extractResource(resourceURL, directoryOrFile, prefix, suffix, false)
.IOException
public static File extractResource(URL resourceURL, File directoryOrFile, String prefix, String suffix, boolean cacheDirectory) throws IOException
null
,
the original filename is used, so directoryOrFile must not be null
.resourceURL
- the URL of the resource to extractdirectoryOrFile
- the output directory or file (null == System.getProperty("java.io.tmpdir")
)prefix
- the prefix of the temporary filename to usesuffix
- the suffix of the temporary filename to usecacheDirectory
- to extract files from directories only when size or last modified timestamp differsIOException
- if fails to extract resource properlypublic static URL findResource(Class cls, String name) throws IOException
findResources(cls, name, 1)[0]
or null if none.IOException
public static URL[] findResources(Class cls, String name) throws IOException
findResources(cls, name, -1)
.IOException
public static URL[] findResources(Class cls, String name, int maxLength) throws IOException
Class
and its ClassLoader
.
Names not prefixed with '/' are considered in priority relative to the Class,
but parent packages, including the default one, also get searched.cls
- the Class from whose ClassLoader to load resourcesname
- of the resources passed to Class.getResource(String)
and ClassLoader.getResources(String)
maxLength
- of the array to return, or -1 for no limitIOException
public static File getCacheDir() throws IOException
System.getProperty("org.bytedeco.javacpp.cachedir")
or ~/.javacpp/cache/
when not set.IOException
public static File getTempDir()
tempDir
out of
System.getProperty("java.io.tmpdir")
and System.nanoTime()
.tempDir
public static Map<String,String> getLoadedLibraries()
public static boolean isLoadLibraries()
System.getProperty("org.bytedeco.javacpp.loadlibraries")
.
Flag set by the Builder
to tell us not to try to load anything.public static boolean checkPlatform(Class<?> cls, Properties properties)
public static boolean checkPlatform(Platform platform, Properties properties, String... defaultNames)
public static String[] load(Class[] classes, boolean logMessages)
load(Class)
on all top-level enclosing classes found in the array.classes
- to try to loadlogMessages
- on load or fail silentlyload(Class)
or null otherwisepublic static String load()
load(getCallerClass(2), loadProperties(), Loader.pathsFirst)
.public static String load(boolean pathsFirst)
Class
of the caller and initializes it.pathsFirst
- search the paths first before bundled resourcesload(getCallerClass(2), loadProperties(), pathsFirst)
getCallerClass(int)
,
load(Class, Properties, boolean)
public static String load(Class cls, Properties properties, boolean pathsFirst)
Class
and initializes it.cls
- the Class to get native library information from and to initializeproperties
- the platform Properties to inheritpathsFirst
- search the paths first before bundled resourcesif (!isLoadLibraries() || cls == null) { return null; }
)NoClassDefFoundError
- on Class initialization failureUnsatisfiedLinkError
- on native library loading failure or when interruptedfindLibrary(Class, ClassProperties, String, boolean)
,
loadLibrary(URL[], String, String...)
public static URL[] findLibrary(Class cls, ClassProperties properties, String libnameversion)
findLibrary(cls, properties, libnameversion, Loader.pathsFirst)
.public static URL[] findLibrary(Class cls, ClassProperties properties, String libnameversion, boolean pathsFirst)
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 if pathsFirst || !loadLibraries
), in that order.cls
- the Class whose package name and ClassLoader
are used to extract from resourcesproperties
- contains the directories to scan for if we fail to extract the library from resourceslibnameversion
- the name of the library + ":" + optional exact path to library + "@" + optional version tag
+ "#" + a second optional name used at extraction (or empty to prevent it, unless it is a second "#")
+ "!" to load all symbols globallypathsFirst
- search the paths first before bundled resourcespublic static String loadLibrary(String libnameversion, String... preloaded)
loadLibrary(getCallerClass(2), libnameversion, preloaded)
.public static String loadLibrary(Class<?> cls, String libnameversion, String... preloaded)
loadLibrary(findResources(cls, libnameversion), libnameversion, preloaded)
.public static String loadLibrary(URL[] urls, String libnameversion, String... preloaded)
loadLibrary(null, urls, libnameversion, preloaded)
.public static String loadLibrary(Class<?> cls, URL[] urls, String libnameversion, String... preloaded)
System.loadLibrary(String)
.cls
- the Class whose ClassLoader
is used to load the library, may be nullurls
- the URLs to try loading the library fromlibnameversion
- the name of the library + ":" + optional exact path to library + "@" + optional version tag
+ "#" + a second optional name used at extraction (or empty to prevent it, unless it is a second "#")
+ "!" to load all symbols globallypreloaded
- libraries for which to create symbolic links in same cache directoryif (!isLoadLibraries) { return null; }
)UnsatisfiedLinkError
- on failure or when interruptedpublic static String createLibraryLink(String filename, ClassProperties properties, String libnameversion, String... paths)
filename
- of the probably versioned libraryproperties
- of the class associated with the librarylibnameversion
- the library name and version as with loadLibrary(URL[], String, String...)
(can be null)paths
- where to create links, in addition to the parent directory of filenamestatic Class putMemberOffset(String typeName, String member, int offset) throws ClassNotFoundException
offsetof()
and sizeof()
values in memberOffsets
.
Tries to load the Class object for typeName using the ClassLoader
of the Loader.typeName
- the name of the peer Class acting as interface to the native typemember
- 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")
)Class.forName(typeName, false)
ClassNotFoundException
- on Class initialization failurestatic void putMemberOffset(Class<? extends Pointer> type, String member, int offset)
type
- the peer Class acting as interface to the native typemember
- the name of the native member variableoffset
- the value of offsetof()
(or sizeof()
when member.equals("sizeof")
)public static int offsetof(Class<? extends Pointer> type, String member)
offsetof()
values from memberOffsets
filled by native libraries.type
- the peer Class acting as interface to the native typemember
- the name of the native member variablememberOffsets.get(type).get(member)
public static int sizeof(Class<? extends Pointer> type)
sizeof()
values from memberOffsets
filled by native libraries.type
- the peer Class acting as interface to the native typememberOffsets.get(type).get("sizeof")
@Name(value="JavaCPP_totalProcessors") public static int totalProcessors()
Runtime.availableProcessors()
and totalCores()
.@Name(value="JavaCPP_totalCores") public static int totalCores()
totalProcessors()
.@Name(value="JavaCPP_totalChips") public static int totalChips()
totalCores()
.@Name(value="JavaCPP_addressof") public static Pointer addressof(String symbol)
@Name(value="JavaCPP_loadGlobal") @Raw(withEnv=true) public static void loadGlobal(String filename)
dlopen(filename, RTLD_LAZY | RTLD_GLOBAL)
,
or simply by default with LoadLibrary(filename)
on Windows. If the library name passed to
one of the other load functions in this class ends with "!", this function will get called on them.Copyright © 2020. All rights reserved.