Class Loader

java.lang.Object
org.bytedeco.javacpp.Loader
@Properties(inherit=javacpp.class) 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().

  • Field Details

    • 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() and initialized with Loader.Detector.getPlatform().

    • WINDOWS

      private static final boolean WINDOWS

    • platformProperties

      private static Properties platformProperties
      Default platform properties loaded and returned by loadProperties().

    • classStack

      private static final ThreadLocal<Deque<Class<?>>> classStack
      The stack of classes currently being loaded to support more than one class loader.

    • cacheDir

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

    • tempDir

      static File tempDir
      Temporary directory set and returned by getTempDir().

    • foundLibraries

      static Map<String,URL[]> foundLibraries
      Contains all the URLs of native libraries that we found to avoid searching for them again.

    • loadedLibraries

      static Map<String,String> loadedLibraries
      Contains all the native libraries that we have loaded to avoid reloading them.

    • pathsFirst

      static boolean pathsFirst
      Default value for load(..., pathsFirst) set via "org.bytedeco.javacpp.pathsFirst" system property.

    • cacheLibraries

      static boolean cacheLibraries
      Whether to extract libraries to cacheDir, set via "org.bytedeco.javacpp.cacheLibraries" system property.

    • findLibraries

      static boolean findLibraries
      Whether to search libraries in class, module, and library paths, set via "org.bytedeco.javacpp.findLibraries" system property.

    • 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 Details

    • Loader

      public Loader()

  • Method Details

    • getPlatform

      public static String getPlatform()
      Returns PLATFORM.

    • getCanonicalPath

      public static String getCanonicalPath(File file) throws IOException
      Returns file.getCanonicalPath() or file.toPath().toRealPath().toString() on Windows.
      Returns:
      The canonical pathname string denoting the same file or directory as that abstract pathname.
      Throws:
      IOException - if an I/O error occurs
      See Also:

    • getCanonicalFile

      public static File getCanonicalFile(File file) throws IOException
      Returns file.getCanonicalFile() or file.toPath().toRealPath().toFile() on Windows.
      Returns:
      The canonical file denoting the same file or directory as that abstract pathname.
      Throws:
      IOException - if an I/O error occurs
      See Also:

    • loadProperties

      public static Properties loadProperties()
      Returns loadProperties(false).

    • loadProperties

      public static Properties loadProperties(boolean forceReload)
      Loads the Properties associated with the default getPlatform().
      Parameters:
      forceReload - to reset cached platformProperties even when not null
      Returns:
      loadProperties(getPlatform(), null)
      See Also:

    • 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". Also picks up system properties starting with "org.bytedeco.javacpp.platform.", which can be used to override default platform properties.
      Parameters:
      name - the platform name
      defaults - the fallback platform name (null == "generic")
      Returns:
      the Properties from resources

    • checkVersion

      public static boolean checkVersion(String groupId, String artifactId)
      Returns checkVersion(groupId, artifactId, "-", true, getCallerClass(2)).

    • checkVersion

      public 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. Also calls Logger.warn(String) on error when logWarnings && isLoadLibraries().

    • getVersion

      public static String getVersion() throws IOException
      Returns getVersion("org.bytedeco", "javacpp").
      Throws:
      IOException

    • getVersion

      public static String getVersion(String groupId, String artifactId) throws IOException
      Returns getVersion(groupId, artifactId, getCallerClass(2)).
      Throws:
      IOException

    • getVersion

      public static String getVersion(String groupId, String artifactId, Class cls) throws IOException
      Returns version property from cls.getResource("META-INF/maven/" + groupId + "/" + artifactId + "/pom.properties").
      Throws:
      IOException

    • 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:

    • 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

      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

      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:

    • 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

      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

      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. Directories from JAR files are extracted recursively.
      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

      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

      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:

    • 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

      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

      public static File extractResource(URL resourceURL, File directoryOrFile, String prefix, String suffix) throws IOException
      Returns extractResource(resourceURL, directoryOrFile, prefix, suffix, false).
      Throws:
      IOException

    • extractResource

      public static File extractResource(URL resourceURL, File directoryOrFile, String prefix, String suffix, boolean cacheDirectory) 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. Directories from JAR files are extracted recursively.
      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
      cacheDirectory - to extract files from directories only when size or last modified timestamp differs
      Returns:
      the File object representing the extracted file
      Throws:
      IOException - if fails to extract resource properly

    • findResource

      public static URL findResource(Class cls, String name) throws IOException
      Returns findResources(cls, name, 1)[0] or null if none.
      Throws:
      IOException

    • findResources

      public static URL[] findResources(Class cls, String name) throws IOException
      Returns findResources(cls, name, -1).
      Throws:
      IOException

    • findResources

      public static URL[] findResources(Class cls, String name, int maxLength) throws IOException
      Finds by name resources using the 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.
      Parameters:
      cls - the Class from whose ClassLoader to load resources
      name - of the resources passed to Class.getResource(String) and ClassLoader.getResources(String)
      maxLength - of the array to return, or -1 for no limit
      Returns:
      URLs to the resources
      Throws:
      IOException

    • deleteDirectory

      public static void deleteDirectory(File directory) throws IOException
      Deletes the directory and all the files in it.
      Throws:
      IOException

    • clearCacheDir

      public static void clearCacheDir() throws IOException
      Calls deleteDirectory(getCacheDir()).
      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

    • getLoadedLibraries

      public static Map<String,String> getLoadedLibraries()
      Returns a Map that relates each library name to the path of the loaded file.

    • 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.

    • checkPlatform

      public static boolean checkPlatform(Class<?> cls, Properties properties)

    • checkPlatform

      public static boolean checkPlatform(Class<?> cls, Properties properties, boolean acceptAllExtensions)

    • checkPlatform

      public static boolean checkPlatform(Platform platform, Properties properties)

    • checkPlatform

      public static boolean checkPlatform(Platform platform, Properties properties, boolean acceptAllExtensions, String... defaultNames)

    • load

      public static String[] load(Class... classes)
      Returns load(classes, true).

    • load

      public static String[] load(Class[] classes, boolean logMessages)
      Calls load(Class) on all top-level enclosing classes found in the array.
      Parameters:
      classes - to try to load
      logMessages - on load or fail silently
      Returns:
      filenames from each successful call to load(Class) or null otherwise

    • load

      public static String load()
      Returns load(getCallerClass(2), loadProperties(), Loader.pathsFirst).

    • load

      public static String load(boolean pathsFirst)
      Loads native libraries associated with the Class of the caller and initializes it.
      Parameters:
      pathsFirst - search the library paths first before bundled resources
      Returns:
      load(getCallerClass(2), loadProperties(), pathsFirst)
      See Also:

    • load

      public static String load(Class cls)
      Returns load(cls, loadProperties(), Loader.pathsFirst).

    • load

      public static String load(Class cls, String executable)
      Returns load(cls, loadProperties(), Loader.pathsFirst, executable).

    • load

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

    • load

      public static String load(Class cls, Properties properties, boolean pathsFirst, String executable)
      Loads native libraries or executables associated with the given Class and initializes it.
      Parameters:
      cls - the Class to get native library and executable information from and to initialize
      properties - the platform Properties to inherit
      pathsFirst - search the library paths first before bundled resources
      executable - the executable name whose path to return, or the first one found when null
      Returns:
      the full path to the main file loaded, or the library name if unknown (but if (!isLoadLibraries() || cls == null) { return null; }), while in the case of optional libraries or executables, it may return null when not found
      Throws:
      NoClassDefFoundError - on Class initialization failure
      UnsatisfiedLinkError - on native library loading failure or when interrupted
      IllegalArgumentException - when executable is specified for a class without executables
      See Also:

    • findLibrary

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

    • 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 "sun.boot.library.path" and "java.library.path" system properties if pathsFirst || !loadLibraries), 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 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 globally
      pathsFirst - search the library paths first before bundled resources
      Returns:
      URLs that point to potential locations of the library

    • loadLibrary

      public static String loadLibrary(String libnameversion, String... preloaded)
      Returns loadLibrary(getCallerClass(2), libnameversion, preloaded).

    • loadLibrary

      public static String loadLibrary(Class<?> cls, String libnameversion, String... preloaded)
      Returns loadLibrary(findResources(cls, libnameversion), libnameversion, preloaded).

    • loadLibrary

      public static String loadLibrary(URL[] urls, String libnameversion, String... preloaded)
      Returns loadLibrary(null, urls, libnameversion, preloaded).

    • loadLibrary

      public 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. Finally, if all fails, falls back on System.loadLibrary(String)RESTRICTED.
      Parameters:
      cls - the Class whose ClassLoader is used to load the library, may be null
      urls - the URLs to try loading the library from
      libnameversion - 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 globally
      preloaded - libraries for which to create symbolic links in same cache directory
      Returns:
      the full path of the file loaded, or the library name if unknown (but if (!isLoadLibraries) { return null; })
      Throws:
      UnsatisfiedLinkError - on failure or when interrupted

    • createLibraryLink

      public static String createLibraryLink(String filename, ClassProperties properties, String libnameversion, String... paths)
      Creates a version-less symbolic link to a library file, if needed. Also creates symbolic links in given paths, with and without version.
      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, String...) (can be null)
      paths - where to create links, in addition to the parent directory of filename
      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")

    • totalProcessors

      public static int totalProcessors()
      Returns Loader.Helper.totalProcessors().

    • totalCores

      public static int totalCores()
      Returns Loader.Helper.totalCores().

    • totalChips

      public static int totalChips()
      Returns Loader.Helper.totalChips().

    • addressof

      public static Pointer addressof(String symbol)
      Returns Loader.Helper.addressof(String).

    • loadGlobal

      public static void loadGlobal(String filename)
      Calls Loader.Helper.loadGlobal(String).

    • getJavaVM

      public static Pointer getJavaVM()
      Returns Loader.Helper.getJavaVM().

    • newGlobalRef

      public static Pointer newGlobalRef(Object object)
      Returns Loader.Helper.newGlobalRef(Object).

    • accessGlobalRef

      public static Object accessGlobalRef(Pointer globalRef)
      Returns Loader.Helper.accessGlobalRef(Pointer).

    • deleteGlobalRef

      public static void deleteGlobalRef(Pointer globalRef)
      Calls Loader.Helper.deleteGlobalRef(Pointer).