Logo Search packages:      
Sourcecode: icedtea-java7 version File versions

java::nio::ByteBuffer Class Reference

Inheritance diagram for java::nio::ByteBuffer:

java::nio::HeapByteBuffer java::nio::HeapByteBufferR

List of all members.


Detailed Description

A byte buffer.

This class defines six categories of operations upon byte buffers:

Byte buffers can be created either by allocation, which allocates space for the buffer's

content, or by wrapping an existing byte array into a buffer.

Direct vs. non-direct buffers

A byte buffer is either direct or non-direct. Given a direct byte buffer, the Java virtual machine will make a best effort to perform native I/O operations directly upon it. That is, it will attempt to avoid copying the buffer's content to (or from) an intermediate buffer before (or after) each invocation of one of the underlying operating system's native I/O operations.

A direct byte buffer may be created by invoking the allocateDirect factory method of this class. The buffers returned by this method typically have somewhat higher allocation and deallocation costs than non-direct buffers. The contents of direct buffers may reside outside of the normal garbage-collected heap, and so their impact upon the memory footprint of an application might not be obvious. It is therefore recommended that direct buffers be allocated primarily for large, long-lived buffers that are subject to the underlying system's native I/O operations. In general it is best to allocate direct buffers only when they yield a measureable gain in program performance.

A direct byte buffer may also be created by mapping a region of a file directly into memory. An implementation of the Java platform may optionally support the creation of direct byte buffers from native code via JNI. If an instance of one of these kinds of buffers refers to an inaccessible region of memory then an attempt to access that region will not change the buffer's content and will cause an unspecified exception to be thrown either at the time of the access or at some later time.

Whether a byte buffer is direct or non-direct may be determined by invoking its isDirect method. This method is provided so that explicit buffer management can be done in performance-critical code.

Access to binary data

This class defines methods for reading and writing values of all other primitive types, except boolean. Primitive values are translated to (or from) sequences of bytes according to the buffer's current byte order, which may be retrieved and modified via the order methods. Specific byte orders are represented by instances of the ByteOrder class. The initial order of a byte buffer is always BIG_ENDIAN.

For access to heterogeneous binary data, that is, sequences of values of different types, this class defines a family of absolute and relative get and put methods for each type. For 32-bit floating-point values, for example, this class defines:

<blockquote>

 float  getFloat()
 float   getFloat(int index)
  void   putFloat(float f)
  void   putFloat(int index, float f)
</blockquote>

Corresponding methods are defined for the types char, short, int, long, and double. The index parameters of the absolute get and put methods are in terms of bytes rather than of the type being read or written.

For access to homogeneous binary data, that is, sequences of values of the same type, this class defines methods that can create views of a given byte buffer. A view buffer is simply another buffer whose content is backed by the byte buffer. Changes to the byte buffer's content will be visible in the view buffer, and vice versa; the two buffers' position, limit, and mark values are independent. The asFloatBuffer method, for example, creates an instance of the FloatBuffer class that is backed by the byte buffer upon which the method is invoked. Corresponding view-creation methods are defined for the types char, short, int, long, and double.

View buffers have three important advantages over the families of type-specific get and put methods described above:

The byte order of a view buffer is fixed to be that of its byte buffer at the time that the view is created.

Invocation chaining

Methods in this class that do not otherwise have a value to return are specified to return the buffer upon which they are invoked. This allows method invocations to be chained.

The sequence of statements

<blockquote>

 bb.putInt(0xCAFEBABE);
 bb.putShort(3);
 bb.putShort(45);
</blockquote>

can, for example, be replaced by the single statement

<blockquote>

 bb.putInt(0xCAFEBABE).putShort(3).putShort(45);
</blockquote>

Author:
Mark Reinhold

JSR-51 Expert Group

Version:
1.69, 07/05/05
Since:
1.4

Definition at line 258 of file ByteBuffer.java.


Public Member Functions

final byte[] array ()
final int arrayOffset ()
abstract CharBuffer asCharBuffer ()
abstract DoubleBuffer asDoubleBuffer ()
abstract FloatBuffer asFloatBuffer ()
abstract IntBuffer asIntBuffer ()
abstract LongBuffer asLongBuffer ()
abstract ByteBuffer asReadOnlyBuffer ()
abstract ShortBuffer asShortBuffer ()
abstract ByteBuffer compact ()
int compareTo (ByteBuffer that)
abstract ByteBuffer duplicate ()
boolean equals (Object ob)
ByteBuffer get (byte[] dst)
ByteBuffer get (byte[] dst, int offset, int length)
abstract byte get (int index)
abstract byte get ()
abstract char getChar (int index)
abstract char getChar ()
abstract double getDouble (int index)
abstract double getDouble ()
abstract float getFloat (int index)
abstract float getFloat ()
abstract int getInt (int index)
abstract int getInt ()
abstract long getLong (int index)
abstract long getLong ()
abstract short getShort (int index)
abstract short getShort ()
final boolean hasArray ()
int hashCode ()
abstract boolean isDirect ()
final ByteBuffer order (ByteOrder bo)
final ByteOrder order ()
final ByteBuffer put (byte[] src)
ByteBuffer put (byte[] src, int offset, int length)
ByteBuffer put (ByteBuffer src)
abstract ByteBuffer put (int index, byte b)
abstract ByteBuffer put (byte b)
abstract ByteBuffer putChar (int index, char value)
abstract ByteBuffer putChar (char value)
abstract ByteBuffer putDouble (int index, double value)
abstract ByteBuffer putDouble (double value)
abstract ByteBuffer putFloat (int index, float value)
abstract ByteBuffer putFloat (float value)
abstract ByteBuffer putInt (int index, int value)
abstract ByteBuffer putInt (int value)
abstract ByteBuffer putLong (int index, long value)
abstract ByteBuffer putLong (long value)
abstract ByteBuffer putShort (int index, short value)
abstract ByteBuffer putShort (short value)
abstract ByteBuffer slice ()
String toString ()

Static Public Member Functions

static ByteBuffer allocate (int capacity)
static ByteBuffer allocateDirect (int capacity)
static ByteBuffer wrap (byte[] array)
static ByteBuffer wrap (byte[] array, int offset, int length)

Package Functions

abstract byte _get (int i)
abstract void _put (int i, byte b)
 ByteBuffer (int mark, int pos, int lim, int cap)
 ByteBuffer (int mark, int pos, int lim, int cap, byte[] hb, int offset)

Package Attributes

boolean bigEndian = true
final byte[] hb
boolean isReadOnly
boolean nativeByteOrder = (Bits.byteOrder() == ByteOrder.BIG_ENDIAN)
final int offset

The documentation for this class was generated from the following file:

Generated by  Doxygen 1.6.0   Back to index