Set native libraries in shared libraries

 

+

Search Tips   |   Advanced Search

Overview

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.

The JVM allows only one class loader to load a particular native library.

There is no 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.

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 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. Associate the native library with the application server class loader to avoid this issue.

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.

When configuring a shared library on a shared library settings page, if we specify a value for Native library path, the native libraries on this path are not located by the WAS 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

1. Implement a static method in the class that loads the native library...

   static {System.loadLibrary("native_library");

   ...where native_library loads during the static initialization of the class, which occurs exactly once when the class loads.

2. On the shared library settings page, set values for Classpath and Native library path that enable the shared library to load the native library.

   To associate the shared library with an application or module, also select...

   Use an isolated class loader for this shared library

   If we do not enable this setting, associate the shared library with an application server.

3. Associate the shared library.

   • If we 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 we 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 we want a separate class loader for a shared library. If we associate the shared library with a server, WAS 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, we can use an isolated shared library to avoid errors resulting from reloading of native libraries.

 

Next steps

To verify that an application can use a shared library, test the application or examine the class loader in the Class loader viewer. Go to...

Troubleshooting | Class loader viewer|; module_name | Table View

The classpath of the application module class loader lists the classes used by the shared library.

 

Related concepts

Class loaders

 

Related tasks

Manage shared libraries
Deploy enterprise apps
Create shared libraries

 

Related

Shared library settings
Troubleshooting class loaders
Class loader viewer settings