Native libraries

Plug-ins may use the Java™ Native Interface (JNI) to access native library code. Native libraries are by convention placed in a fragment specific to an operating system or architecture to the plug-in providing the Java classes (native libraries can all be placed within a single plug-in).

directory\fragment.xml
directory\os\<osgi.os>\<osgi.arch>\*.dll or *.so

Where directory is typically <fragment_name>_<fragment_version>

The value of the osgi.os value above is the value corresponding to the value of the Java System property, osgi.os. The value of the osgi.arch corresponds to the value of the Java System property, osgi.arch.

The osgi.os value is generally based on the os.name property value, although the value of osgi.os may alias a set of values for os.name. For example, the osgi.os value of win32 is used to represent an os.name value of Windows® 2000.

The osgi.arch value is generally based on the os.arch property value.

For the runtime environment, since it is targeting Windows 2000, Windows XP, and Linux®, the values of osgi.os would be either win32 or linux.

The value for arch will be x86.

As an example, the DB2® Everyplace® component requires native libraries. The plug-in id is com.ibm.db2e and the version is 8.2.0. The native libraries required for Windows reside in a fragment for this plug-in, com.ibm.db2e.win32_8.2.0. Within this fragment, the directory os\win32\x86 contains the DLLs required by DB2 Everyplace.

If there is a single native library required by the plug-in, and it is loaded via the System.loadLibrary() method, then packaging the fragment or plug-in in this organization is sufficient.

If there are multiple native libraries required by the plug-in, and each one is individually loaded by the System.loadLibrary() method, and the DLLs do not depend on each other or statically or dynamically load each other, this organization is sufficient.

If there are multiple native libraries required by the plug-in, and there are dependencies between the libraries such that a System.loadLibrary() method call loads one of the libraries, but that library statically or dynamically loads the other libraries, then an additional step is required. Because these directories are not provided on the System PATH or LIBPATH, the operating system is unable to handle the loading of the shared library. To cause these directories to be added to the system PATH or LIBPATH so that the operating system can load these libraries, update the rcpinstall.properties file to add the appropriate plug-in or fragment directory to the library.path.prepend or library.path.append properties.

As an example, there are multiple native libraries required for DB2 Everyplace. Because these libraries have dependencies between them, they must be present on the system PATH or LIBPATH. Therefore, the following fragment directory has been added to the library.path.append property in the rcpinstall.properties file:

C:/Program Files/IBM/Lotus/Expeditor/rcp/eclipse/plugins/com.ibm.db2e.win32.x86_8.2.1.20050620/os/win32/x86

Code that behaves differently between operating systems that are aliased to win32, such as Windows 2000 or Windows XP, should be handled within the native libraries, and should not be placed into separate plug-ins/fragments, or separate osgi.os directories, since changing the operating system name for the runtime environment will prevent proper loading of components such as DB2 Everyplace or SWT.