Please review this JEP I'd like to propose for Java SE 8.

Tue Jan 29 11:44:32 PST 2013

Resending, mailer stripped out my attachment.

Bob Vandette
Java SE Embedded Architect

--------------------------------------------------------------------------------------------

Title: Add support for static JNI libraries
Author: Bob Vandette
Organization: Oracle Java SE Embedded
Owner: Bob Vandette
Created: 2913/01/23
Type: Feature
State: Draft
Exposure: Open
Component: core/libs
Scope: SE
RFE: 8005716
Discussion: jdk8 dash dev at openjdk dot java dot net
Start: 2013/Q1
Effort: XS
Duration: XS
Template: 1.0
Reviewed-by: Alan Bateman
Endorsed-by: Michael Vidsted
Funded-by: Oracle Java SE

Summary
-------

The JNI specification doesn't fully support or specify how to use statically
linked native libraries.  There are at least two possible uses for this.

1. Native applications that embedded the JRE may wish to use statically linked
JNI code rather than dynamically linked libraries.

2. Java applications that are developed for devices where shared libraries are
not supported.  On this type of platform, the JRE and all of it's supported JNI
native code would be linked into a single application binary.

At least two problems need to be addressed:

1. The current Java APIs that are used to initiate the loading process and as
a result allow the native library entrypoints to be recognized need to be
enhanced to support build-in libraries. A Java application wishing to use a
build-in JNI library need a mechanism for notifying the VM that this library
code is already included in the application image. In this situation, a
System.loadLibrary request for a built-in library should avoid the platform
native load but process the library as if the load succeeded.

The current JNI specification alludes to this type of support but the currentHotspot VM does not support this behavior.  "If the underlying operating system
does not support dynamic linking, all native methods must be prelinked with the
VM. In this case, the VM completes the System.loadLibrary call without actually
loading the library."

2. The JNI_OnLoad and JNI_OnUnload function interface need to be enhanced to
support library specific names since only a single function name can exist
within an application.  This could be implemented by appending the library name
to these well-known-names. For example libnet.so could use JNI_OnLoad_net,
JNI_OnUnload_net.

Goals
-----

1. Modify the specification and implementation of Java SE in order to enable
developers to build a java runtime into a single Java application binary
without requiring the use of shared libraries.

2. Maintain Java source level compatibility.
For example:  System.loadLibrary("foobar") APIs should be able to transparently
load dynamic or static libraries.

3. Support Java applications that use a combination of static and/or dynamic
libraries.

4. Static libraries must be in memory prior to the initialization of the VM.
Static libraries should not be linked with other dynamic shared libraries.

Non-Goals
---------

Complete native C/C++ source compatibility in not expected.  It is expected that
some minimal source changes will be required in order to rename the JNI_OnLoad
and JNI_OnUnLoad functions in order to allow multiple static libraries to
co-exist.

Success Metrics
---------------

This feature will be successful when there is support for static linkingand mixed static/dynamic linking in a Java runtime.

Motivation
----------

Having the ability to link JNI static libraries within Java applications
provides multiple benefits:

1. Enables the Link Time Optimization supported by most linkers to perform
optimizations across the entire application.  This results in smaller  and
faster executable.

2. Allows for the possibility of supporting Java SE on platforms that limit or
do not support dynamic shared libraries.

Description
-----------

This change requires specification changes to both the Java SE library
loading APIs and the JNI specification.  Here is an initial draft of the
specification updates in both areas:

JAVA LIBRARY API CHANGES

System.load, Runtime.load method Changes

The System.load and Runtime.load specification descriptions will be change in to:

Loads the native library specified by the filename argument.  The filename
argument must be an absolute path name.

If the filename argument, when stripped of any platform-specific library prefix,
path, and file extension, indicates a library whose name is L, and a native
library called L is statically linked with the VM, then the JNI_OnLoad_L
function exported by the library is invoked rather than attempting to load a
dynamic library.  A filename matching the argument does not have to exist in
the file system.   See the JNI Specification for more details.

Otherwise, the filename argument is mapped to a native library image in an
implementation-dependent manner.

The UnsatisfiedLinkError - if either the filename is not an absolute path name,
the native library is not statically linked with the VM,  or the library cannot
be mapped to a native library image by the host system.

System.loadLibrary, Runtime.loadLibrary changes

The System.loadLibrary and Runtime.loadLibrary specification descriptions will
be changed to:

Loads the native library specified by the libname argument.  The libname
argument must not contain any platform specific prefix, file extension or path.

If a native library called libname is statically linked with the VM, then the
JNI_OnLoad_libname function exported by the library is invoked. See the JNI
Specification for more details.

Otherwise, the libname argument is loaded from a system library location and
mapped to a native library image in an implementation-dependent manner.

The UnsatisfiedLinkError - if either the libname argument contains a file path,
the native library is not statically linked with the VM,  or the library
cannot be mapped to a native library image by the host system.

JNI SPECIFICATION CHANGE

- A native library may be statically linked with the VM.  The manner in which
the library and VM image are combined is implementation-dependent.

- A System.loadLibrary or equivalent API must succeed for this library to be
considered loaded.

- A library L whose image has been combined with the VM is defined as
_statically linked_ if and only if the library exports a function called
JNI_OnLoad_L.

- If a _statically linked_ library L exports a function called JNI_OnLoad_L
_and_ a function called JNI_OnLoad, the JNI_OnLoad function will be ignored.

- If a library L is _statically linked_, then upon the first invocation of
System.loadLibrary("L") or equivalent API, the Java runtime will invoke the
JNI_OnLoad_L function with the same arguments and expected return value as
specified for the JNI_OnLoad function.

- A library L that is _statically linked_ will prohibit a library of the same
name from being loaded dynamically.

- When the class loader containing a _statically linked_ native library L is
garbage collected, the VM will invoke the JNI_OnUnload_L function of the
library if such a function is exported.

- If a _statically linked_ library L exports a function called JNI_OnUnLoad_L
_and_ a function called JNI_OnUnLoad, the JNI_OnUnLoad function will be ignored.

The JNI version specification will be incremented to JNI_VERSION_1_8.
This new functionality will only be supported in JNI_VERSION_1_8 or greater.

Alternatives
------------

There are no alternatives.

Testing
-------

The JNI TCK tests need to be enhanced to validate native static
libraries in addition to the currently supported dynamic libraries.

Impact
------

  - Compatibility: New configuration no issues with existing dynamic libraries
  - Portability:   JNI native sources require function name changes when
                   built static
  - Documentation: javadoc for impacted java/lang APIS and JNI specification
  - TCK:           TCK JNI native library will need to be ported as a static lib