com.jniwrapper
Class Library

java.lang.Object
  extended by com.jniwrapper.Library

public class Library
extends java.lang.Object

This class provides operations with a native code library. The Library class is responsible for providing the Function class instances that are used for calling functions from native code libraries. Unlike standard functionality provided, a library can be dynamically loaded and unloaded.
To unload the library you can extend this class and use its unload() method.


Field Summary
static java.lang.String NATIVE_CODE
           
static java.lang.String NATIVE_NAME
           
 
Constructor Summary
Library(java.lang.String name)
          Constructs a library using its name.
Library(java.lang.String libraryName, byte callingConvention)
          Constructs a library using its name and default calling convention.
 
Method Summary
static void ensureNativeCode()
          Ensures that the native code implementation is loaded.
static LibraryLoader getDefaultLibraryLoader()
          Returns a library loader used in methods that do not take the library loader as an argument.
 Function getFunction(java.lang.String name)
          A convenience method for getting a function when parameter types do affect loaded function.
 Function getFunction(java.lang.String name, java.lang.Class[] paramTypes)
          This returns a Function object that reflects the exported native function from the library.
static Library getJNIWrapperLibrary()
          Returns the instance of loaded JNIWrapper library.
protected static java.util.List getJVMLibraries()
          Returns the list of libraries which were loaded by JVM.
 LibraryLoader getLibraryLoader()
          This method returns the loader of this library.
 java.lang.String getName()
          Returns the library name.
 void getVariable(java.lang.String name, Parameter variable)
          Maps variable to memory address of a global variable in library.
 boolean isLoaded()
          Returns loaded status of this library.
 void load()
          Loads a library by its name using default mechanism.
 void load(java.lang.ClassLoader classLoader)
          Special method for loading a library from the context of the specified class loader.
 void load(java.io.File directory)
          Loads a library from the passed directory.
 void load(LibraryLoader loader)
          Loads a library using a given library loader.
static void loadNativeCode()
          Initializes the native support library using standard library search behavior and predefined native library name.
static void loadNativeCode(LibraryLoader loader)
          Loads a native support library using a specified library loader.
static void loadNativeCode(java.lang.String nativeSupportPath)
          Loads a native support library from the passed full file name.
static void setDefaultLibraryLoader(LibraryLoader libraryLoader)
          Sets a library loader used in methods that do not take the library loader as an argument.
protected  void unload()
          This method is designed for unloading an unused library.
static java.lang.String unloadNativeCode()
          Unloads JNI library from the Java classloader.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NATIVE_CODE

public static final java.lang.String NATIVE_CODE

NATIVE_NAME

public static final java.lang.String NATIVE_NAME
Constructor Detail

Library

public Library(java.lang.String libraryName,
               byte callingConvention)
Constructs a library using its name and default calling convention.

Parameters:
libraryName - the name of the library
callingConvention - specifies the calling convention for all functions from this library

Library

public Library(java.lang.String name)
Constructs a library using its name. This name does not contain the full path to the library file.

Parameters:
name - library name
Method Detail

getJNIWrapperLibrary

public static Library getJNIWrapperLibrary()
Returns the instance of loaded JNIWrapper library.

Returns:
JNIWrapper library

getJVMLibraries

protected static java.util.List getJVMLibraries()
Returns the list of libraries which were loaded by JVM.

Returns:
list of Library objects

unloadNativeCode

public static java.lang.String unloadNativeCode()
Unloads JNI library from the Java classloader. This method is called by NativeResourceCollector on shutdown and shall not be called explicitly during usage of JNIWrapper

Returns:
- The absolute path to the unloaded library.

loadNativeCode

public static void loadNativeCode(LibraryLoader loader)
                           throws java.lang.SecurityException,
                                  java.lang.UnsatisfiedLinkError
Loads a native support library using a specified library loader.

Throws:
java.lang.SecurityException
java.lang.UnsatisfiedLinkError

loadNativeCode

public static void loadNativeCode(java.lang.String nativeSupportPath)
                           throws java.lang.SecurityException,
                                  java.lang.UnsatisfiedLinkError
Loads a native support library from the passed full file name.

Throws:
java.lang.SecurityException
java.lang.UnsatisfiedLinkError

loadNativeCode

public static void loadNativeCode()
                           throws java.lang.SecurityException,
                                  java.lang.UnsatisfiedLinkError
Initializes the native support library using standard library search behavior and predefined native library name.

Throws:
java.lang.SecurityException
java.lang.UnsatisfiedLinkError

ensureNativeCode

public static void ensureNativeCode()
Ensures that the native code implementation is loaded. If native code is not loaded yet, loads default implementation.


load

public void load()
          throws LibraryNotFoundException
Loads a library by its name using default mechanism.

Throws:
LibraryNotFoundException

load

public void load(java.io.File directory)
          throws LibraryNotFoundException
Loads a library from the passed directory.

Throws:
LibraryNotFoundException

load

public void load(LibraryLoader loader)
          throws LibraryNotFoundException
Loads a library using a given library loader.

Throws:
LibraryNotFoundException

load

public void load(java.lang.ClassLoader classLoader)
Special method for loading a library from the context of the specified class loader. This methods creates a special LibraryLoader, which can be retrieved using the getLibraryLoader function.

Parameters:
classLoader - a class loader is the context to load the native library from

unload

protected void unload()
This method is designed for unloading an unused library. It's been made protected intentionally.
To invoke this method you can use either reflection mechanism or you can just extend the Library class and make this method public. You need to do this only if unloading of the library is required for your applications.


isLoaded

public boolean isLoaded()
Returns loaded status of this library.


getName

public java.lang.String getName()
Returns the library name.


getFunction

public Function getFunction(java.lang.String name,
                            java.lang.Class[] paramTypes)
                     throws NoSuchFunctionException,
                            LibraryNotFoundException
This returns a Function object that reflects the exported native function from the library.

Throws:
NoSuchFunctionException
LibraryNotFoundException

getFunction

public Function getFunction(java.lang.String name)
                     throws NoSuchFunctionException,
                            LibraryNotFoundException
A convenience method for getting a function when parameter types do affect loaded function. Use this method on Win32.

Throws:
NoSuchFunctionException
LibraryNotFoundException

getVariable

public void getVariable(java.lang.String name,
                        Parameter variable)
                 throws NoSuchVariableException
Maps variable to memory address of a global variable in library.
NOTE: This method is not designed to load inlined constants, which are defined using the #define operator in a header file, but only those variables, which are specially declared as global variables, for example:
      extern "C" __declspec(dllexport) Type Name; 

Parameters:
name - a variable name
variable - a variable to load
Throws:
NoSuchVariableException

getLibraryLoader

public LibraryLoader getLibraryLoader()
This method returns the loader of this library.

Returns:
a loader of this library

getDefaultLibraryLoader

public static LibraryLoader getDefaultLibraryLoader()
Returns a library loader used in methods that do not take the library loader as an argument.


setDefaultLibraryLoader

public static void setDefaultLibraryLoader(LibraryLoader libraryLoader)
Sets a library loader used in methods that do not take the library loader as an argument.