| A container for data of a specific primitive type.
This class is provided as part of the JSR 239 NIO Buffer
building block. It is a subset of the java.nio.Buffer
class in Java(TM) Standard Edition version 1.4.2. Differences are
noted in bold italic.
I/O channels, marking and resetting, and read-only
buffers are not supported. The char,
long, and double datatypes are not
supported. The following methods are omitted:
Buffer mark()Buffer reset()boolean isReadOnly()
To mimimize documentation differences from the full NIO package,
the omitted features continue to be mentioned in the
documentation. In each case, a note is added explaining that the
feature is not present.
A buffer is a linear, finite sequence of elements of a
specific primitive type. Aside from its content, the essential
properties of a buffer are its capacity, limit, and position:
A buffer's capacity is the number of elements it contains. The
capacity of a buffer is never negative and never changes.
A buffer's limit is the index of the first element that should
not be read or written. A buffer's limit is never negative and is never
greater than its capacity.
A buffer's position is the index of the next element to be
read or written. A buffer's position is never negative and is never
greater than its limit.
There is one subclass of this class for each non-boolean
primitive type. The char, long,
and double buffer subclasses are not supported in JSR
239.
Transferring data
Each subclass of this class defines two categories of get and
put operations:
Relative operations read or write one or more elements
starting at the current position and then increment the position
by the number of elements transferred. If the requested transfer
exceeds the limit then a relative get operation throws a
BufferUnderflowException
and a relative put operation throws a BufferOverflowException; in either
case, no data is transferred.
Absolute operations take an explicit element index and
do not affect the position. Absolute get and put
operations throw an IndexOutOfBoundsException if the
index argument exceeds the limit.
Data may also, of course, be transferred in to or out of a
buffer by the I/O operations of an appropriate channel, which are
always relative to the current position. Channels are not
supported in JSR 239..
Marking and resetting
Marking and resetting are not supported in JSR
239.
A buffer's mark is the index to which its position will
be reset when the reset
method is invoked. The mark is not always defined, but when it is
defined it is never negative and is never greater than the
position. If the mark is defined then it is discarded when the
position or the limit is adjusted to a value smaller than the mark.
If the mark is not defined then invoking the reset
method causes an InvalidMarkException to
be thrown.
Invariants
The following invariant holds for the mark, position, limit, and
capacity values:
0 <=
mark <=
position <=
limit <=
capacity
A newly-created buffer always has a position of zero and a mark that is
undefined. The initial limit may be zero, or it may be some other value
that depends upon the type of the buffer and the manner in which it is
constructed. The initial content of a buffer is, in general,
undefined.
Clearing, flipping, and rewinding
In addition to methods for accessing the position, limit, and capacity
values and for marking and resetting, this class also defines the following
operations upon buffers:
clear()
makes a buffer ready for a new sequence of channel-read or
relative put operations: It sets the limit to the capacity
and the position to zero. flip()
makes a buffer ready for a new sequence of channel-write or
relative get operations: It sets the limit to the current
position and then sets the position to zero. rewind()
makes a buffer ready for re-reading the data that it already
contains: It leaves the limit unchanged and sets the position to
zero.
Read-only buffers
JSR 239 does not support read-only buffers.
Every buffer is readable, but not every buffer is writable.
The mutation methods of each buffer class are specified as
optional operations that will throw a
ReadOnlyBufferException when invoked upon a read-only
buffer. A read-only buffer does not allow its content to be
changed, but its mark, position, and limit values are mutable.
Whether or not a buffer is read-only may be determined by invoking
its isReadOnly method.
Thread safety
Buffers are not safe for use by multiple concurrent threads.
If a buffer is to be used by more than one thread then access to
the buffer should be controlled by appropriate synchronization.
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; for
example, the sequence of statements
b.flip();
b.position(23);
b.limit(42);
can be replaced by the single, more compact statement
b.flip().position(23).limit(42);
| 