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.
If you want to associate your shared library with an application or module, also select
Use an isolated class loader for this shared library. If you do not enable
this setting, associate the shared library with an application server.
- Associate the shared library.
- If you did not enable Use an isolated class loader for this shared
library, associate the shared
library with 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.
- If you enabled Use an isolated class loader for this shared library,
associate the shared library with an application
or module.
Associating an isolated shared library file with an application or module loads
the classes represented by the shared library in a separate class loader created for that shared
library. Do not associate an isolated shared library file with a server if you want a separate class
loader for a shared library. If you associate the shared library with a server, the product ignores
the isolation setting and still adds files in the shared library to the application server class
loader. That is, associating an isolated shared library file with a server associates the file with
all applications on the server.
The class loader created for an isolated shared library does
not reload and, like a server class loader, exists for the lifetime of a server. For shared native
libraries, you can use an isolated shared library to avoid errors resulting from reloading of native
libraries.
What to do next
To verify that an application can use a shared library, test the application or examine the
class loader in the Class loader viewer. Click
. The classpath of the application module class
loader lists the classes used by the shared library.