ByteBuffer holds a sequence of bytes for use in an
I/O operation. ByteBuffer is an abstract class, so
you cannot instantiate one by calling a constructor. Instead, you
must use allocate( )
,
allocateDirect( ), or wrap( ).
allocate( ) returns a
ByteBuffer with the specified capacity. The
position of this new buffer is zero, and its limit is set to its
capacity. allocateDirect( ) is like
allocate( ) except that it attempts to allocate a
buffer that the underlying operating system can use
"directly." Such
direct
buffers" may be substantially more efficient for
low-level I/O operations than normal buffers, but may also have
significantly larger allocation costs.
If you have already allocated an array of bytes, you can use the
wrap( ) method to create a
ByteBuffer that uses the byte array as its
storage. In the one-argument version of wrap( )
you specify only the array; the buffer capacity and limit are set to
the array length, and the position is set to zero. In the other form
of wrap( ) you specify the array, as well as an
offset and length that specify a portion of that array. The capacity
of the resulting ByteBuffer is again set to the
total array length, but its position is set to the specified offset,
and its limit is set to the offset plus length.
Once you have obtained a ByteBuffer, you can use
the various get( )
and put( ) methods
to read data from it or write data into it. Several versions of these
methods exist to read and write single bytes or arrays of bytes. The
single-byte methods come in two forms. Relative get(
) and put( ) methods query or set the
byte at the current position and then increment the position. The
absolute forms of the methods take an additional arguement that
specifies the buffer element that is to be read or written and do not
affect the buffer position. Two other relative forms of the
get( ) method exist to read as sequence of bytes
(starting at and incrementing the buffer's position)
into a specified byte array or a specified sub-array. These methods
throw a BufferUnderflowException if there are not
enough bytes left in the buffer. Two relative forms of the
put( ) method copy bytes from a specified array or
sub-array into the buffer (starting at and incrementing the
buffer's position). They throw a
BufferOverflowException if there is not enough
room left in the buffer to hold the bytes. One final form of the
put( ) method transfers all the remaining bytes
from one ByteBuffer into this buffer, incrementing
the positions of both buffers.
In addition to the get( ) and put(
) methods, ByteBuffer also defines
another operation that affect the buffer's content.
compact( )
discards any bytes before the buffer position, and copies all bytes
between the position and limit to the beginning of the buffer. The
position is then set to the new limit, and the limit is set to the
capacity. This method compacts a buffer by discarding elements that
have already been read, and then prepares the buffer for appending
new elements to those that remain.
All Buffer subclasses, such as
CharBuffer, IntBuffer and
FloatBuffer have analogous methods which are just
like these get( ) and put( )
methods except that they operate on different data types.
ByteBuffer is unique among
Buffer subclasses in that it has additional
methods for reading and writing values of other primitive types from
and into the byte buffer. These methods have names like
getInt( ) and putChar( ), and
there are methods for all primitive types except
byte and boolean. Each method
reads or writes a single primitive value. Like the get(
) and put( ) methods, they come in
relative and absolute variations: the relative methods start with the
byte at the buffer's position, and increment the
position by the appropriate number of bytes (two bytes for a
char, four bytes for an int,
eight bytes for a double, etc.). The absolute
methods take an buffer index (it is a byte index and is not
multiplied by the size of the primitive value) as an argument and do
not modify the buffer position. The encoding of multi-byte primitive
values into a byte buffer can be done most-significant byte to
least-significant byte ("big-endian byte
order") or the reverse
("little-endian byte order"). The
byte order used by these primitive-type get and put methods is
specified by a ByteOrder object. The byte order
for a ByteBuffer can be queried and set with the
two forms of the order(
) method. The default byte order for
all newly-created ByteBuffer objects is
ByteOrder.BIG_ENDIAN.
Other methods that are unique
to ByteBuffer( ) are a set of
methods that
allow a buffer of bytes to be viewed as a buffer of other primitive
types. asCharBuffer( ), asIntBuffer(
) and related methods return "view
buffers" that allow the bytes between the position
and the limit of the underlying ByteBuffer to be
viewed as a sequence of characters, integers, or other primitive
values. The returned buffers have position, limit, and mark values that
are independent of those of the underlying buffer. The initial
position of the returned buffer is zero, and the limit and capacity
are the number of bytes between the position and limit of the
original buffer divided by the size in bytes of the relevant
primitive type (two for char and
short, four for int and
float, and eight for long and
double). Note that the returned view buffer is a
view of the bytes between the position and limit of the byte buffer.
Subsequent changes to the position and limit of the byte buffer do
not change the size of the view buffer, but changes to the bytes
themselves to change the values that are viewed through the view
buffer. View buffers use the byte ordering that was current in the
byte buffer when they were created; subsequent changes to the byte
order of the byte buffer do not affect the view buffer. If the
underlying byte buffer is direct, then the returned buffer is also
direct; this is important because ByteBuffer is
the only buffer class with an allocateDirect( )
method.
ByteBuffer defines some additional methods, which,
like the get( ) and put( )
methods have analogs in all Buffer subclasses.
duplicate( ) returns a new buffer that shares
the content with this one. The two buffers have independent position,
limit, and mark values, although the duplicate buffer starts off with
the same values as the original buffer. The duplicate buffer is
direct if the original is direct and is read-only if the original is read-only.
The buffers share content, and content changes made to either buffer
are visible through the other. asReadOnlyBuffer( )
is like duplicate( ) except that the returned
buffer is read-only, and all of its put( ) and
related methods throw a ReadOnlyBufferException.
slice( ) is also somewhat like duplicate(
) except the returned buffer represents only the content
between the current position and limit. The returned buffer has a
position of zero, a limit and capacity equal to the number of
remaining elements in this buffer, and an undefined mark.
isDirect( ) is a
simple method that returns true if a buffer is a
direct buffer and false otherwise. If this buffer
has a backing array and is not a read-only buffer (e.g., if it was
created with the allocate( ) or wrap(
) methods) then hasArray( ) returns
TRue, array( ) returns the
backing array, and arrayOffset( ) returns the
offset within that array of the first element of the buffer. If
hasArray( ) returns false, then array(
) and arrayOffset( ) may throw an
UnsupportedOperationException or a
ReadOnlyBufferException.
Finally, ByteBuffer and other
Buffer subclasses override several standard object
methods. The equals( )
methods compares the elements between the position and limit of two
buffers and returns true only if there are the
same number and have the same value. Note that elements before the
position of the buffer are not considered. The hashCode(
) method is implemented to match the equals(
) method: the hashcode is based only upon the elements
between the position and limit of the buffer. This means that the
hashcode changes if either the contents or position of the buffer
changes. This means that instances of ByteBuffer
and other Buffer subclasses are not usually useful
as keys for hashtables or java.util.Map objects.
toString( )
returns a string summary of the buffer, but the precise contents of
the string are unspecified. ByteBuffer and each of
the other Buffer subclasses also implement the
Comparable interface and define a
compareTo( ) method
that performs an element-by-element comparison operation on the
buffer elements between the position and the limit of the buffer.
Figure 13-3. java.nio.ByteBuffer
public abstract class
ByteBuffer extends Buffer
implements Comparable<ByteBuffer> {
// No Constructor
// Public Class Methods
public static ByteBuffer
allocate (int
capacity );
public static ByteBuffer
allocateDirect (int
capacity );
public static ByteBuffer
wrap (byte[ ]
array );
public static ByteBuffer
wrap (byte[ ]
array , int
offset , int
length );
// Public Instance Methods
public final byte[ ]
array ( );
public final int
arrayOffset ( );
public abstract CharBuffer
asCharBuffer ( );
public abstract DoubleBuffer
asDoubleBuffer ( );
public abstract FloatBuffer
asFloatBuffer ( );
public abstract IntBuffer
asIntBuffer ( );
public abstract LongBuffer
asLongBuffer ( );
public abstract ByteBuffer
asReadOnlyBuffer ( );
public abstract ShortBuffer
asShortBuffer ( );
public abstract ByteBuffer
compact ( );
public abstract ByteBuffer
duplicate ( );
public abstract byte
get ( );
public abstract byte
get (int
index );
public ByteBuffer
get (byte[ ]
dst );
public ByteBuffer
get (byte[ ]
dst , int
offset , int
length );
public abstract char
getChar ( );
public abstract char
getChar (int
index );
public abstract double
getDouble ( );
public abstract double
getDouble (int
index );
public abstract float
getFloat ( );
public abstract float
getFloat (int
index );
public abstract int
getInt ( );
public abstract int
getInt (int
index );
public abstract long
getLong ( );
public abstract long
getLong (int
index );
public abstract short
getShort ( );
public abstract short
getShort (int
index );
public final boolean
hasArray ( );
public abstract boolean
isDirect ( );
public final ByteOrder
order ( );
public final ByteBuffer
order (ByteOrder
bo );
public ByteBuffer
put (ByteBuffer
src );
public abstract ByteBuffer
put (byte
b );
public final ByteBuffer
put (byte[ ]
src );
public abstract ByteBuffer
put (int
index , byte
b );
public ByteBuffer
put (byte[ ]
src , int
offset , int
length );
public abstract ByteBuffer
putChar (char
value );
public abstract ByteBuffer
putChar (int
index , char
value );
public abstract ByteBuffer
putDouble (double
value );
public abstract ByteBuffer
putDouble (int
index , double
value );
public abstract ByteBuffer
putFloat (float
value );
public abstract ByteBuffer
putFloat (int
index , float
value );
public abstract ByteBuffer
putInt (int
value );
public abstract ByteBuffer
putInt (int
index , int
value );
public abstract ByteBuffer
putLong (long
value );
public abstract ByteBuffer
putLong (int
index , long
value );
public abstract ByteBuffer
putShort (short
value );
public abstract ByteBuffer
putShort (int
index , short
value );
public abstract ByteBuffer
slice ( );
// Methods Implementing Comparable
5.0 public int
compareTo (ByteBuffer
that );
// Public Methods Overriding Object
public boolean
equals (Object
ob );
public int
hashCode ( );
public String
toString ( );
}
Too many methods to list.