glguerin.util.LibLoader Class Reference
List of all members.Detailed Description
A LibLoader encapsulates different ways to call System.load() or loadLibrary(), using one or more fallback locations as places to look for JNI libraries.This implementation is specifically designed for use with Cocoa-Java, which won't normally search for JNI libs in the Contents/Resources/Java section of an app-bundle.
Although designed for Cocoa-Java, it will work in any situation, since it relies first on System.loadLibrary(), and only after that fails does it resort to any fallback strategies. Also, this class will work on non-Mac platforms, because it always uses reflection to refer to any Mac-specific classes and methods. This makes the code more difficult to understand, but is much safer. Reflection is only used in LibLoader's constructor. Thereafter, a File is used, so there is no ongoing performance cost for the fact that reflection is used.
USAGE
In general, call the static method getLoader() or makeLoader(), rather than instantiating a new LibLoader directly. Calling getLoader() will instantiate a LibLoader as needed, managing a private singleton thread-safely. Calling makeLoader() always makes a new LibLoader. In either case, the class instantiated may be controlled with the "glguerin.util.LibLoader.imp" property, which should be a fully qualified class name of a concrete LibLoader implementation. Normally, you won't have to set the property.
The principal method in LibLoader is loadLibrary(). It calls System.loadLibrary() first, then its own fallback load() method if that fails. Only when System.loadLibrary() fails do any fallback strategies come into play. If there are no fallbacks in place, or none are necessary, then LibLoader.loadLibrary() is equivalent to System.loadLibrary(). If the fallback strategy fails, an UnsatisfiedLinkError is thrown, just as System.loadLibrary() does.
This typical invocation:
LibLoader.getLoader().loadLibrary( "SomeLib" );
corresponds to:
System.loadLibrary( "SomeLib" );
Properties used:
glguerin.util.LibLoader.imp -- The fully qualified class name of a LibLoader implementation used by makeLoader(), which is also called by getLoader().
glguerin.util.LibLoader.debug -- A boolean ("true" or "false") controls whether diagnostics are printed to System.err by load() and makeFallbackDir(). Default is false.
Definition at line 77 of file LibLoader.java.
Public Member Functions | |
| LibLoader () | |
| A default LibLoader has a fallback strategy appropriate for Cocoa-Java on Mac OS X. | |
| void | loadLibrary (String libName) |
| Load the library, using normal and fallback strategies. | |
| String | toString () |
| Return a String telling something about how libs are loaded. | |
Static Public Member Functions | |
| static synchronized LibLoader | getLoader () |
| Get a LibLoader appropriate to the configuration. | |
| static LibLoader | makeLoader () |
| Make a LibLoader appropriate to the configuration. | |
Static Public Attributes | |
| static boolean | isVerbose = Boolean.getBoolean( "glguerin.util.LibLoader.debug" ) |
| Set this flag to T for all LibLoader's to be verbose on System.err stream. | |
Protected Member Functions | |
| void | blab () |
| Called from constructor, an overridable diagnostic emitting dirFallback. | |
| void | load (String libName, File location) |
| Try to load a JNI library from a fallback location represented as a directory File. | |
| File | makeFallbackDir () |
| Create a File representing a directory from which load(String,File) will load JNI libs. | |
Protected Attributes | |
| final File | dirFallback |
| Passed to load(String,File) as location to look in for fallback strategy. | |
Constructor & Destructor Documentation
| glguerin.util.LibLoader.LibLoader | ( | ) |
A default LibLoader has a fallback strategy appropriate for Cocoa-Java on Mac OS X.
Definition at line 147 of file LibLoader.java.
Member Function Documentation
| static synchronized LibLoader glguerin.util.LibLoader.getLoader | ( | ) | [static] |
Get a LibLoader appropriate to the configuration.
It will reuse a known singleton, or make one if no singleton is known.
Definition at line 96 of file LibLoader.java.
| static LibLoader glguerin.util.LibLoader.makeLoader | ( | ) | [static] |
Make a LibLoader appropriate to the configuration.
Not synchronized because it doesn't refer to any static variables.
Definition at line 112 of file LibLoader.java.
| void glguerin.util.LibLoader.blab | ( | ) | [protected] |
Called from constructor, an overridable diagnostic emitting dirFallback.
Definition at line 155 of file LibLoader.java.
| void glguerin.util.LibLoader.loadLibrary | ( | String | libName | ) |
Load the library, using normal and fallback strategies.
May be overridden in subclasses. The fallback strategies may be altered by overriding load(). The load() method should return normally on success, or throw an UnsatisfiedLinkError on failure.
- See also:
- load
Definition at line 171 of file LibLoader.java.
| void glguerin.util.LibLoader.load | ( | String | libName, | |
| File | location | |||
| ) | [protected] |
Try to load a JNI library from a fallback location represented as a directory File.
Return normally on success, or throw an UnsatisfiedLinkError on failure. May be overridden in subclasses.
The File may be null, which this method may elect to handle or throw an UnsatisfiedLinkError. This imp throws an UnsatisfiedLinkError when File is null.
This imp takes a File designating a directory location, and hand-makes a path-name that follows the Mac OS X convention for JNI library names: "Foo" loads "libFoo.jnilib". It then calls System.load() to load the resulting absolute pathname. For other platforms or situations, override this method and assemble a library-name under your target platform's conventions. On purely Java 2 platforms, you can use System.mapLibraryName(). This implementation can't do that because it is 1.1-compatible.
- Exceptions:
-
java.lang.UnsatisfiedLinkError thrown when the named library could not be loaded. Any overriding implementation of this method must throw this error on failure.
Definition at line 202 of file LibLoader.java.
| File glguerin.util.LibLoader.makeFallbackDir | ( | ) | [protected] |
Create a File representing a directory from which load(String,File) will load JNI libs.
May return null if there is no fallback directory in which to look for JNI libs. Called from constructor to get a File, assigning it to dirFallback.
This imp uses reflection to attempt to load a Cocoa NSBundle class. On success, it returns a File referring to the "Java" sub-dir of the bundle's resources dir. On failure, it returns null so load(String,File) will fail.
Definition at line 228 of file LibLoader.java.
| String glguerin.util.LibLoader.toString | ( | ) |
Return a String telling something about how libs are loaded.
Definition at line 278 of file LibLoader.java.
Member Data Documentation
boolean glguerin.util.LibLoader.isVerbose = Boolean.getBoolean( "glguerin.util.LibLoader.debug" ) [static] |
Set this flag to T for all LibLoader's to be verbose on System.err stream.
The flag is initialized from the property "glguerin.util.LibLoader.debug", but can be changed programmatically, as well.
Definition at line 84 of file LibLoader.java.
final File glguerin.util.LibLoader.dirFallback [protected] |
Passed to load(String,File) as location to look in for fallback strategy.
This will be null if makeFallbackDir() returns null.
Definition at line 143 of file LibLoader.java.
The documentation for this class was generated from the following file:
- org/gecode/gist/cocoa/LibLoader.java