Native libraries are platform-specific library files, including .dll, .so,
or *SRVPGM objects, that can be configured within shared libraries. Native
libraries are visible to an application class loader whenever the shared library
is associated with an application. Similarly, native libraries are visible
to an application server class loader whenever the shared library is associated
with an application server.
Before you begin
When designing a shared library, consider the following conditions
regarding Java native library support:
- The Java virtual machine (JVM) allows only one class loader to load a
particular native library.
- There is no application programming interface (API) to unload a native
library from a class loader.
Native libraries are unloaded by the JVM when
the class loader that found the library is collected from the heap during
garbage collection.
- Application server class loaders persist for the duration of the application
server.
- Application class loaders persist until an application is stopped or dynamically
reloaded.
If a shared library that is configured with a native library path
is associated with an application, whenever the application is restarted or
dynamically reloaded the application might fail with an UnsatisfiedLinkError
indicating that the library is already loaded. The error occurs because, when
the application restarts, it invokes the shared library class to reload the
native library. The native library, however, is still loaded in memory because
the application class loader which previously loaded the native library has
not yet been garbage collected.
- Only the JVM class loader can load a dependent native library.
For example,
if NativeLib1 is dependent on NativeLib2, then NativeLib2 must
be visible to the JVM class loader. The path containing NativeLib2 must
be specified on Java library path defined by the LIBPATH environment variable.
If a native library configured in a shared library is dependent on other native
libraries, the dependent libraries must be configured on the LIBPATH of the
JVM hosting the application server in order for that library to load successfully.
About this task
When configuring a shared library on a
shared
library settings page, if you specify a value for
Native Library
Path, the native libraries on this path are not located by the
WebSphere Application Server application
or shared library class loaders unless the class which loads the native library
was itself loaded by the same class loader.
Because a native library cannot
be loaded more than once by a class loader, it is preferable for native libraries
to be loaded within shared libraries associated with the class loader of an
application server, because these class loaders persist for the lifetime of
the server.
Procedure
- Implement a static method in the class that loads the native library.
In the class that loads the native library, call System.loadLibrary(native_library) in
a static block. For example:
static {System.loadLibrary("native_library");
native_library loads
during the static initialization of the class, which occurs exactly once when
the class loads.
- On the shared library settings
page, set values for Classpath and Native Library Path that
enable the shared library to load the native library.
- Associate the
shared library with the class loader of an application server.
Associating a shared library with the class loader of an application
server, rather than with an application, ensures that the shared library is
loaded exactly once by the application server class loader, even though applications
on the server are restarted or dynamically reloaded. Because the native library
is loaded within a static block, the native library is never loaded more than
once.