com.jniwrapper
Class Library

java.lang.Object
  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.