Release:

JDK 1.4

Problem:

The direct buffer facilities being added to 1.4 in the java.nio
package allow this package fast access to memory outside the Java
heap, providing substantial speedups to I/O code. We request a
standardized mechanism for instantiating a direct buffer and finding
the memory region associated with a direct buffer. Having such a
standard API will allow privileged code to safely and rapidly access
memory outside the heap in a JVM-independent manner, providing similar
speedups in domains such as JDBC driver implementation and 3D
graphics.

Requesters (Must include team responsible for code which will be
changed and any major customers):

  HotSpot group
  NIO (JSR-51) team
  NearLife, Inc. (http://www.nearlife.com/)
  SAS
  Siemens
  Other external vendors writing JDBC drivers

Proposed API change:

Three new entry points in the JNI interface. (Note that the "capacity"
routine is not strictly necessary since that information is already
accessible from Java, and could be removed if necessary to make the
interface simpler.)

/** Allocates a new "direct" java.nio.ByteBuffer. This buffer refers
    to the range of bytes starting at <I>address</I> and extending to
    and including <I>address + capacity - 1</I>. The caller is
    responsible for managing the underlying region of memory when the
    last Java reference to it is released; this can be done, for
    example, by creating a java.lang.ref.PhantomReference for the
    returned ByteBuffer object. */

jobject (JNICALL *NewDirectByteBuffer)
  (JNIEnv* env, jlong address, jint capacity);

/** Returns the address for a "direct" java.nio.Buffer, which is the
    start of the address range to which this buffer refers. If the
    given object is null or is not a "direct" java.nio.Buffer, returns
    0 and causes a NullPointerException or IllegalArgumentException,
    respectively, to be thrown. */

jlong (JNICALL *GetDirectBufferAddress)
  (JNIEnv* env, jobject buf);

/** Returns the capacity of a "direct" java.nio.Buffer in the units
    defined by the method java.nio.Buffer.capacity(). If the given
    object is null or is not a "direct" java.nio.Buffer, returns -1
    and causes a NullPointerException or IllegalArgumentException,
    respectively, to be thrown. */

jint (JNICALL *GetDirectBufferCapacity)
  (JNIEnv* env, jobject buf);


 Also a sentence in the nio specification stating the following:

If a view, B, is created of a direct byte buffer A, then B is
guaranteed to maintain a strong reference to A; that is, when A is
reclaimed (and notification posted, for example, through a
java.lang.ref.PhantomReference), it is safe to deallocate or unmap the
underlying storage for A. (Without this guarantee, it would be
necessary to maintain such references in user code.)


API reviewed and approved by:

  Mark.Reinhold@eng
  Robert.Griesemer@eng

Implementation:
   - Engineer who made (or will make) the changes: Kenneth.Russell@eng
   - Date at which changes will be complete: 12/7/2000
   - Number of lines of new or modified code:
        + Java: 0
        + Native: ~50
   - Code reviewed (or will be reviewed) by: Mark.Reinhold@eng
                                                   Robert.Griesemer@eng

Risk assessment:

  Low risk; requires ability to run native code to access these APIs.

SQE (product testing) impact; contact ###@###.###:

   - Name of person who approved change and committed to add/modify
     tests:

   Satya.Dodda@eng

JCK (compatibility testing) impact; contact jck-ccc@eng:
  (JCK would like javadoc comments to be submitted as a soft copy or
   as an e-mail attachment. Please do not submit URL pointers to javadoc
   comments.)

   - Name of person who approved change and committed to write JCK
     tests:

   Satya.Dodda@eng

Doc impact (contact Alan.Sommerer@eng if you don't know your contact):

   - Name of person committed to add/modify documents:

  TBD: have not yet discussed this with Alan.Sommerer@eng

Localization impact: Yes/No

  No impact.

Internationalization impact: Yes/No

  No impact.

Security impact: Yes/No

  Since accessing these APIs requires the ability to run native code,
  there is no additional security impact.

Compatibility impact: Yes/No

  No compatibility impact; the new entry points will be added to the
  end of the existing JNI interface structure to avoid binary
  compatibility problems with existing JNI code.

Legal impact: Yes/No

  No impact.

For feature changes, Product Marketing approval:

  N/A