FileDocCategorySizeDatePackage
Buffer.javaAPI DocJava SE 6 API16726Tue Jun 10 00:25:42 BST 2008java.nio

Buffer

public abstract class Buffer extends Object
A container for data of a specific primitive type.

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.

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 {@link BufferUnderflowException} and a relative put operation throws a {@link 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 {@link 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.

Marking and resetting

A buffer's mark is the index to which its position will be reset when the {@link #reset 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 {@link #reset reset} method causes an {@link 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:

  • {@link #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.

  • {@link #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.

  • {@link #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

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 {@link 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 {@link #isReadOnly 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);
author
Mark Reinhold
author
JSR-51 Expert Group
version
1.38, 05/12/20
since
1.4

Fields Summary
private int
mark
private int
position
private int
limit
private int
capacity
long
address
Constructors Summary
Buffer(int mark, int pos, int lim, int cap)


    // Creates a new buffer with the given mark, position, limit, and capacity,
    // after checking invariants.
    //
            	// package-private
	if (cap < 0)
	    throw new IllegalArgumentException();
	this.capacity = cap;
	limit(lim);
	position(pos);
	if (mark >= 0) {
	    if (mark > pos)
		throw new IllegalArgumentException();
	    this.mark = mark;
	}
Methods Summary
public abstract java.lang.Objectarray()
Returns the array that backs this buffer  (optional operation).

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 {@link #hasArray hasArray} method before invoking this method in order to ensure that this buffer has an accessible backing array.

return
The array that backs this buffer
throws
ReadOnlyBufferException If this buffer is backed by an array but is read-only
throws
UnsupportedOperationException If this buffer is not backed by an accessible array
since
1.6

public abstract intarrayOffset()
Returns the offset within this buffer's backing array of the first
element of the buffer  (optional operation).


 If this buffer is backed by an array then buffer position p
corresponds to array index p + arrayOffset().


 Invoke the {@link #hasArray hasArray} method before invoking this
method in order to ensure that this buffer has an accessible backing
array. 
return
The offset within this buffer's array
of the first element of the buffer
throws
ReadOnlyBufferException
If this buffer is backed by an array but is read-only
throws
UnsupportedOperationException
If this buffer is not backed by an accessible array
since
1.6
public final intcapacity()
Returns this buffer's capacity. 
return
The capacity of this buffer
	return capacity;
    
static voidcheckBounds(int off, int len, int size)
 // package-private
        if ((off | len | (off + len) | (size - (off + len))) < 0)
	    throw new IndexOutOfBoundsException();
    
final intcheckIndex(int i)
Checks the given index against the limit, throwing an {@link
IndexOutOfBoundsException} if it is not smaller than the limit
or is smaller than zero.
			// package-private
	if ((i < 0) || (i >= limit))
	    throw new IndexOutOfBoundsException();
	return i;
    
final intcheckIndex(int i, int nb)
		// package-private
	if ((i < 0) || (nb > limit - i))
	    throw new IndexOutOfBoundsException();
	return i;
    
public final java.nio.Bufferclear()
Clears this buffer. The position is set to zero, the limit is set to
the capacity, and the mark is discarded.


 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. 
return
This buffer
	position = 0;
	limit = capacity;
	mark = -1;
	return this;
    
public final java.nio.Bufferflip()
Flips this buffer. The limit is set to the current position and then
the position is set to zero. If the mark is defined then it is
discarded.


 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 {@link
java.nio.ByteBuffer#compact compact} method when transferring data from
one place to another. 
return
This buffer
	limit = position;
	position = 0;
	mark = -1;
	return this;
    
public abstract booleanhasArray()
Tells whether or not this buffer is backed by an accessible
array.


 If this method returns true then the {@link #array() array}
and {@link #arrayOffset() arrayOffset} methods may safely be invoked.

return
true if, and only if, this buffer
is backed by an array and is not read-only
since
1.6
public final booleanhasRemaining()
Tells whether there are any elements between the current position and
the limit. 
return
true if, and only if, there is at least one element
remaining in this buffer
	return position < limit;
    
public abstract booleanisDirect()
Tells whether or not this buffer is
direct. 
return
true if, and only if, this buffer is direct
since
1.6
public abstract booleanisReadOnly()
Tells whether or not this buffer is read-only. 
return
true if, and only if, this buffer is read-only
public final intlimit()
Returns this buffer's limit. 
return
The limit of this buffer
	return limit;
    
public final java.nio.Bufferlimit(int newLimit)
Sets this buffer's limit. If the position is larger than the new limit
then it is set to the new limit. If the mark is defined and larger than
the new limit then it is discarded. 
param
newLimit
The new limit value; must be non-negative
and no larger than this buffer's capacity
return
This buffer
throws
IllegalArgumentException
If the preconditions on newLimit do not hold
	if ((newLimit > capacity) || (newLimit < 0))
	    throw new IllegalArgumentException();
	limit = newLimit;
	if (position > limit) position = limit;
	if (mark > limit) mark = -1;
	return this;
    
public final java.nio.Buffermark()
Sets this buffer's mark at its position. 
return
This buffer
	mark = position;
	return this;
    
final intmarkValue()
				// package-private
	return mark;
    
final intnextGetIndex()
Checks the current position against the limit, throwing a {@link
BufferUnderflowException} if it is not smaller than the limit, and then
increments the position. 
return
The current position value, before it is incremented
				// package-private
	if (position >= limit)
	    throw new BufferUnderflowException();
	return position++;
    
final intnextGetIndex(int nb)
			// package-private
        if (limit - position < nb)
	    throw new BufferUnderflowException();
	int p = position;
	position += nb;
	return p;
    
final intnextPutIndex()
Checks the current position against the limit, throwing a {@link
BufferOverflowException} if it is not smaller than the limit, and then
increments the position. 
return
The current position value, before it is incremented
				// package-private
	if (position >= limit)
	    throw new BufferOverflowException();
	return position++;
    
final intnextPutIndex(int nb)
			// package-private
        if (limit - position < nb)
	    throw new BufferOverflowException();
	int p = position;
	position += nb;
	return p;
    
public final intposition()
Returns this buffer's position. 
return
The position of this buffer
	return position;
    
public final java.nio.Bufferposition(int newPosition)
Sets this buffer's position. If the mark is defined and larger than the
new position then it is discarded. 
param
newPosition
The new position value; must be non-negative
and no larger than the current limit
return
This buffer
throws
IllegalArgumentException
If the preconditions on newPosition do not hold
	if ((newPosition > limit) || (newPosition < 0))
	    throw new IllegalArgumentException();
	position = newPosition;
	if (mark > position) mark = -1;
	return this;
    
public final intremaining()
Returns the number of elements between the current position and the
limit. 
return
The number of elements remaining in this buffer
	return limit - position;
    
public final java.nio.Bufferreset()
Resets this buffer's position to the previously-marked position.


 Invoking this method neither changes nor discards the mark's
value. 
return
This buffer
throws
InvalidMarkException
If the mark has not been set
        int m = mark;
	if (m < 0)
	    throw new InvalidMarkException();
	position = m;
	return this;
    
public final java.nio.Bufferrewind()
Rewinds this buffer. The position is set to zero and the mark is
discarded.


 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
return
This buffer
	position = 0;
	mark = -1;
	return this;