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, unlike the native JVM class
loader, only load native shared libraries that use the default operating
system extension for the current platform. For example, on AIX, native
shared libraries must end in .a when loaded by
application server class loaders. The JVM class loader loads files
ending in .a or .so.
The Java Web Start can load native shared
libraries with the .so file extension only. Rename any native shared
libraries so that they have the .so file extension before packaging
them in a Java archive (JAR) file for Java Web Start deployment.
- 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.
The LIBPATH (java.library.path) property
is configured using the process_name_region_libpath environment
variable, such as control_region_libpath, server_region_libpath,
or adjunct_region_libpath. For instructions on how
to set the region LIBPATH variables, see Changing the values of variables referenced in BBOM0001I messages.
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.