All Packages  This Package  Class Hierarchy  Class Search  Index

java.lang.Object
   |
   +----glguerin.util.LibLoader

Summary

public class  LibLoader
     extends java.lang.Object
{
          // Fields 2
     protected final File dirFallback;
     public static boolean isVerbose;

          // Constructors 1
     public LibLoader();

          // Methods 7
     public static synchronized LibLoader getLoader();
     public static LibLoader makeLoader();

     protected void blab();
     protected void load(String, File);
     public void loadLibrary(String);
     protected File makeFallbackDir();
     public String toString();
}

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.

Cross Reference

Returned By:

LibLoader.getLoader(), LibLoader.makeLoader()

   public static boolean isVerbose

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.

   protected final File dirFallback

Passed to load(String,File) as location to look in for fallback strategy. This will be null if makeFallbackDir() returns null.

Constructors

· LibLoader

Summary  |  Top

   public LibLoader() 

A default LibLoader has a fallback strategy appropriate for Cocoa-Java on Mac OS X.

   public static synchronized LibLoader getLoader() 

Get a LibLoader appropriate to the configuration. It will reuse a known singleton, or make one if no singleton is known.

   public static LibLoader makeLoader() 

Make a LibLoader appropriate to the configuration. Not synchronized because it doesn't refer to any static variables.

   protected void blab() 

Called from constructor, an overridable diagnostic emitting dirFallback.

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

   protected void load(String libName,
                       File location) 

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.dylib". 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.

Throws: UnsatisfiedLinkError

thrown when the named library could not be loaded. Any overriding implementation of this method must throw this error on failure.

   protected File makeFallbackDir() 

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.

   public String toString() 

Return a String telling something about how libs are loaded.

Overrides:

toString in class Object

All Packages  This Package  Class Hierarchy  Class Search  Index