maspack.fileutil
Class NativeLibraryManager

java.lang.Object
  extended by maspack.fileutil.NativeLibraryManager

public class NativeLibraryManager
extends java.lang.Object

Class to ensure that necessary native libraries are installed on this system. Native libraries that are not present, or which are out of date, can be downloaded from the ArtiSynth web server.

Normally, this class operates as a singleton and is accessed through the static methods verify() and load(). Native libraries are stored in a native-specific directory within a generic library directory that is specified using setLibDir(). This must be set in order to enable the downloading and updating of libraries. If this is not set, then verify and load will attempt to find the specified libraries in the system's load library path, but no attempt will be made to update or load them.

Libraries are specified generically using a name of the form

    
 
where is an optional string of the form ".I.J.K ..." with I, J, K, etc. being positive integers that specify version numbers. The first number I specifies the major version number, while the second number J, if present, specifies the minor version number. Less significant version numbers may be present but are not used by the library manager.

For example, solver.1.3 solver.1.3.77 both indicate a library with a basename of solver, a major version number of 1, and a minor version number of 3, while mesh.4 indicates a library with a basename of mesh, a major version number of 4, and no minor version.

Libraries with the same basename but different major version numbers are assumed to be incompatible. However, libraries with the same basename and major version are assumed to be backward compatible across minor version numbers. That means that if we need a library xxx.I.J, then any library xxx.I.K will suffice as long as K >= J. If a library is requested and it is not present and cannot be downloaded, but a compatible library with a higher minor version number is present, then that compatible library will be used instead.

Generic library names are converted into library file names appropriate for the current native system. For example, solver.1.3, would be converted into the following native file names:

   libsolver.so.1.3     // Linux
   libsolver.1.3.dylib  // MacOS
   solver.1.3.dll       // Windows
 

Alternative, it is also possible to specify an actual system-specific library file name to a verify() or load() request. In that case, the system type is determined from the name, and the request is carried out only if this matches the actual current system.


Nested Class Summary
static class NativeLibraryManager.SystemType
          Indicates the system type.
 
Field Summary
static int UPDATE
          Flag to indicate that when checking a library, we see if it matches the latest version on the server, and if not, download the latest version from the server.
static int VERBOSE
          Flag to enable messages to be printed to console.
 
Method Summary
static java.lang.String getFileName(java.lang.String libName)
          Returns the system-specific file name for the named library.
static FileTransferListener getFileTransferListener()
          Returns the application-specified file transfer listener for this library manager, if any.
static int getFlags()
          Returns the currently active flags for the library manager.
static java.lang.String getLibDir()
          Returns the main library directory which currently set (or null if no directory is set).
static java.lang.String getPathName(java.lang.String libName)
          Returns the full path name for the specified library file on this system.
static NativeLibraryManager.SystemType getSystemType()
          Returns the current system type.
static void load(java.lang.String libName)
          Loads a Java native library specified by libName.
static void main(java.lang.String[] args)
           
static void setFileTransferListener(FileTransferListener l)
          Sets a file transfer listener for the library manager, to monitor the progress of file transfers from the server.
static void setFlags(int flags)
          Sets the currently active flags for the library manager.
static void setLibDir(java.lang.String libBaseName)
          Sets the main library directory which contains the native directory.
static void setSystemType(NativeLibraryManager.SystemType type)
          Explicitly sets the current system type.
static void verify(java.lang.String libName)
          Verifies that the indicated native library is present, downloading or updating it from the server if necessary.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UPDATE

public static int UPDATE
Flag to indicate that when checking a library, we see if it matches the latest version on the server, and if not, download the latest version from the server.


VERBOSE

public static int VERBOSE
Flag to enable messages to be printed to console.

Method Detail

setFileTransferListener

public static void setFileTransferListener(FileTransferListener l)
Sets a file transfer listener for the library manager, to monitor the progress of file transfers from the server. If set, this overrides the default transfer listener that displays progress by writing to the console. An application-specified listener can be used to drive a GUI-based progress bar.

See Also:
getFileTransferListener()

getFileTransferListener

public static FileTransferListener getFileTransferListener()
Returns the application-specified file transfer listener for this library manager, if any.

See Also:
setFileTransferListener(maspack.fileutil.FileTransferListener)

getSystemType

public static NativeLibraryManager.SystemType getSystemType()
Returns the current system type.


setSystemType

public static void setSystemType(NativeLibraryManager.SystemType type)
Explicitly sets the current system type.


getFileName

public static java.lang.String getFileName(java.lang.String libName)
Returns the system-specific file name for the named library. For example, on Linux,
 getFileName ("foo.1.4"); 
will return libfoo.so.1.4. See the discussion in the class header for more information about how the library name is formatted.

Parameters:
libName - name of the library.

setLibDir

public static void setLibDir(java.lang.String libBaseName)
Sets the main library directory which contains the native directory. This must be set in order to enable downloading and updating of libraries from the server.

Parameters:
libBaseName - full path name of the base directory containing the native library directory.

getLibDir

public static java.lang.String getLibDir()
Returns the main library directory which currently set (or null if no directory is set).


verify

public static void verify(java.lang.String libName)
Verifies that the indicated native library is present, downloading or updating it from the server if necessary. If the library cannot be found or obtained from the server, an exception is thrown. See the discussion in the class header for more information about how the library name is formatted.

Parameters:
libName - name of the library.
Throws:
NativeLibraryException - if the required library is not present and cannot be obtained.

setFlags

public static void setFlags(int flags)
Sets the currently active flags for the library manager. At present, possible flags consist of an or-ed collection of VERBOSE or UPDATE.

See Also:
getFlags()

getFlags

public static int getFlags()
Returns the currently active flags for the library manager.

See Also:
setFlags(int)

getPathName

public static java.lang.String getPathName(java.lang.String libName)
Returns the full path name for the specified library file on this system. See the discussion in the class header for more information about how the library name is formatted.

Parameters:
libName - name of the library.
Throws:
java.lang.IllegalStateException - if the main library directory has not been set using setLibDir().

load

public static void load(java.lang.String libName)
Loads a Java native library specified by libName. This is a wrapper for System.load() that first attempts to locate the library file, if necessary downloading or updating it from the server. See the discussion in the class header for more information about how the library name is formatted.

Parameters:
libName - name of the library.

main

public static void main(java.lang.String[] args)