ByteBuffer
, CharBuffer
, DoubleBuffer
, FloatBuffer
, IntBuffer
, LongBuffer
, ShortBuffer
public abstract class Buffer extends Object
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.
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 aBufferOverflowException
; 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.
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.
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. Each element of a newly-allocated buffer is initialized to zero.
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.
slice()
creates a subsequence of a buffer: It leaves the
limit and the position unchanged.
duplicate()
creates a shallow copy of a buffer: It leaves
the limit and the position unchanged.
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.
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.
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
can be replaced by the single, more compact statementb.flip(); b.position(23); b.limit(42);
b.flip().position(23).limit(42);
Modifier and Type | Method | Description |
---|---|---|
abstract Object |
array() |
Returns the array that backs this
buffer (optional operation).
|
abstract int |
arrayOffset() |
Returns the offset within this buffer's backing array of the first
element of the buffer (optional operation).
|
int |
capacity() |
Returns this buffer's capacity.
|
Buffer |
clear() |
Clears this buffer.
|
abstract Buffer |
duplicate() |
Creates a new buffer that shares this buffer's content.
|
Buffer |
flip() |
Flips this buffer.
|
abstract boolean |
hasArray() |
Tells whether or not this buffer is backed by an accessible
array.
|
boolean |
hasRemaining() |
Tells whether there are any elements between the current position and
the limit.
|
abstract boolean |
isDirect() |
Tells whether or not this buffer is
direct.
|
abstract boolean |
isReadOnly() |
Tells whether or not this buffer is read-only.
|
int |
limit() |
Returns this buffer's limit.
|
Buffer |
limit(int newLimit) |
Sets this buffer's limit.
|
Buffer |
mark() |
Sets this buffer's mark at its position.
|
int |
position() |
Returns this buffer's position.
|
Buffer |
position(int newPosition) |
Sets this buffer's position.
|
int |
remaining() |
Returns the number of elements between the current position and the
limit.
|
Buffer |
reset() |
Resets this buffer's position to the previously-marked position.
|
Buffer |
rewind() |
Rewinds this buffer.
|
abstract Buffer |
slice() |
Creates a new buffer whose content is a shared subsequence of
this buffer's content.
|
public final int capacity()
public final int position()
public Buffer position(int newPosition)
newPosition
- The new position value; must be non-negative
and no larger than the current limitIllegalArgumentException
- If the preconditions on newPosition
do not holdpublic final int limit()
public Buffer limit(int newLimit)
newLimit
- The new limit value; must be non-negative
and no larger than this buffer's capacityIllegalArgumentException
- If the preconditions on newLimit
do not holdpublic Buffer mark()
public Buffer reset()
Invoking this method neither changes nor discards the mark's value.
InvalidMarkException
- If the mark has not been setpublic Buffer clear()
Invoke this method before using a sequence of channel-read or put operations to fill this buffer. For example:
buf.clear(); // Prepare buffer for reading in.read(buf); // Read data
This method does not actually erase the data in the buffer, but it is named as if it did because it will most often be used in situations in which that might as well be the case.
public Buffer flip()
After a sequence of channel-read or put operations, invoke this method to prepare for a sequence of channel-write or relative get operations. For example:
buf.put(magic); // Prepend header in.read(buf); // Read data into rest of buffer buf.flip(); // Flip buffer out.write(buf); // Write header + data to channel
This method is often used in conjunction with the compact
method when transferring data from
one place to another.
public Buffer rewind()
Invoke this method before a sequence of channel-write or get operations, assuming that the limit has already been set appropriately. For example:
out.write(buf); // Write remaining data buf.rewind(); // Rewind buffer buf.get(array); // Copy data into array
public final int remaining()
public final boolean hasRemaining()
true
if, and only if, there is at least one element
remaining in this bufferpublic abstract boolean isReadOnly()
true
if, and only if, this buffer is read-onlypublic abstract boolean hasArray()
If this method returns true
then the array
and arrayOffset
methods may safely be invoked.
true
if, and only if, this buffer
is backed by an array and is not read-onlypublic abstract Object array()
This method is intended to allow array-backed buffers to be passed to native code more efficiently. Concrete subclasses provide more strongly-typed return values for this method.
Modifications to this buffer's content will cause the returned array's content to be modified, and vice versa.
Invoke the hasArray
method before invoking this
method in order to ensure that this buffer has an accessible backing
array.
ReadOnlyBufferException
- If this buffer is backed by an array but is read-onlyUnsupportedOperationException
- If this buffer is not backed by an accessible arraypublic abstract int arrayOffset()
If this buffer is backed by an array then buffer position p
corresponds to array index p + arrayOffset()
.
Invoke the hasArray
method before invoking this
method in order to ensure that this buffer has an accessible backing
array.
ReadOnlyBufferException
- If this buffer is backed by an array but is read-onlyUnsupportedOperationException
- If this buffer is not backed by an accessible arraypublic abstract boolean isDirect()
true
if, and only if, this buffer is directpublic abstract Buffer slice()
The content of the new buffer will start at this buffer's current position. Changes to this buffer's content will be visible in the new buffer, and vice versa; the two buffers' position, limit, and mark values will be independent.
The new buffer's position will be zero, its capacity and its limit will be the number of elements remaining in this buffer, its mark will be undefined. The new buffer will be direct if, and only if, this buffer is direct, and it will be read-only if, and only if, this buffer is read-only.
public abstract Buffer duplicate()
The content of the new buffer will be that of this buffer. Changes to this buffer's content will be visible in the new buffer, and vice versa; the two buffers' position, limit, and mark values will be independent.
The new buffer's capacity, limit, position and mark values will be identical to those of this buffer. The new buffer will be direct if, and only if, this buffer is direct, and it will be read-only if, and only if, this buffer is read-only.
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-internal+0-adhoc.mlchung.jdk9-jdeps