public abstract class Buffer extends Object
java.nio.Buffer
class in Java SE.
Differences are noted in bold italic.
Marking and resetting, and read-only
buffers are not supported. The char
,
long
, and double
data types are not
supported. The following methods are omitted:
Buffer mark()
Buffer reset()
boolean isReadOnly()
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.
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.
The following invariant holds for the position, limit, and capacity values:
0 <= position <= limit <= capacity
A newly-created buffer always has a position of zero. 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, this class also defines the following operations upon buffers:
clear()
makes a buffer ready for a new sequence of
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
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.
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 and Description |
---|---|
int |
capacity()
Returns this buffer's capacity.
|
Buffer |
clear()
Clears this buffer.
|
Buffer |
flip()
Flips this buffer.
|
boolean |
hasRemaining()
Tells whether there are any elements between the current position and
the limit.
|
int |
limit()
Returns this buffer's limit.
|
Buffer |
limit(int newLimit)
Sets this buffer's limit.
|
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 |
rewind()
Rewinds this buffer.
|
public final int capacity()
public final Buffer clear()
Invoke this method before using a sequence of 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 final Buffer flip()
After a sequence of put operations, invoke this method to prepare for a sequence of 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
public final boolean hasRemaining()
public final int limit()
public final 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 final int position()
public final 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 remaining()
public final Buffer rewind()
Invoke this method before a sequence of 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
Copyright (c) 2014, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.