Managing native method libraries

To use native method libraries, especially when you want to manage multiple versions of a native method library on your IBM® i server, you need to understand both the Java™ library naming conventions and the library search algorithm.

Note: The term native library or native method library refers to integrated language environment (ILE) service programs when used in the context of ILE native methods, and AIX® static or shared libraries when used in the context of PASE for i native methods.

The Java method System.loadLibrary() is used to load a native library given a library name. IBM i uses the first native method library that matches the name of the library that the Java virtual machine (JVM) loads. In order to ensure that IBM i finds the correct native methods, you must avoid library name clashes and confusion about which native method library the JVM uses.

Native library naming conventions

You need to be aware of the following library naming conventions:
  • If the native methods are ILE native methods and the Java code loads a library named Sample, the corresponding executable file must be an ILE service program named SAMPLE.
  • If the native methods are PASE for i native methods and the Java code loads a library named Sample, the corresponding executable file must be an AIX library named either libSample.a or libSample.so.

Java library search order

To locate a native library, Java uses the java.library.path property to determine the search path. By default, the java.library.path property is set to a value that is a result of the concatenation of two lists (in the following order):

  1. IBM i library list
  2. The value of the LIBPATH environment variable

In order to perform the search, IBM i converts the library list to the integrated file system format. QSYS file system objects have equivalent names in the integrated file system, but some integrated file system objects do not have equivalent QSYS file system names. Because the library loader looks for objects in both the QSYS file system and in the integrated file system, IBM i uses the integrated file system format to search for native method libraries.

The following table shows how IBM i converts entries in the library list to the integrated file system format:

Library list entry Integrated file system format
QSYS /qsys.lib
QSYS2 /qsys.lib/qsys2.lib
QGPL /qsys.lib/qgpl.lib
QTEMP /qsys.lib/qtemp.lib

Example: Searching for the Sample2 library

In this example, the LIBPATH environment variable is set to /home/user1/lib32:/samples/lib32. The following table, when read from top to bottom, indicates the full search path:

Source Integrated file system directories
Library list 
/qsys.lib
/qsys.lib/qsys2.lib
/qsys.lib/qgpl.lib
/qsys.lib/qtemp.lib
LIBPATH 
/home/user1/lib32
/samples/lib32
Note: Uppercase and lowercase characters are significant only in the /QOpenSys path.

In order to search for library Sample2, the Java library loader searches for file candidates in the following order:

  1. /qsys.lib/sample2.srvpgm
  2. /qsys.lib/libSample2.a
  3. /qsys.lib/libSample2.so
  4. /qsys.lib/qsys2.lib/sample2.srvpgm
  5. /qsys.lib/qsys2.lib/libSample2.a
  6. /qsys.lib/qsys2.lib/libSample2.so
  7. /qsys.lib/qgpl.lib/sample2.srvpgm
  8. /qsys.lib/qgpl.lib/libSample2.a
  9. /qsys.lib/qgpl.lib/libSample2.so
  10. /qsys.lib/qtemp.lib/sample2.srvpgm
  11. /qsys.lib/qtemp.lib/libSample2.a
  12. /qsys.lib/qtemp.lib/libSample2.so
  13. /home/user1/lib32/sample2.srvpgm
  14. /home/user1/lib32/libSample2.a
  15. /home/user1/lib32/libSample2.so
  16. /samples/lib32/sample2.srvpgm
  17. /samples/lib32/libSample2.a
  18. /samples/lib32/libSample2.so
IBM i loads the first candidate in the list that actually exists into the JVM as a native method library.
Note: You can create arbitrary symbolic links from integrated file system directories to IBM i objects in the QSYS file system. As a result, valid file candidates can include files such as /home/user1/lib32/sample2.srvpgm.
Parent topic: Native methods and the Java Native Interface