java.nio
Class Buffer

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by java.nio.Buffer
Direct Known Subclasses:
ByteBuffer sample code for java.nio.ByteBuffer definition code for java.nio.ByteBuffer , CharBuffer sample code for java.nio.CharBuffer definition code for java.nio.CharBuffer , DoubleBuffer sample code for java.nio.DoubleBuffer definition code for java.nio.DoubleBuffer , FloatBuffer sample code for java.nio.FloatBuffer definition code for java.nio.FloatBuffer , IntBuffer sample code for java.nio.IntBuffer definition code for java.nio.IntBuffer , LongBuffer sample code for java.nio.LongBuffer definition code for java.nio.LongBuffer , ShortBuffer sample code for java.nio.ShortBuffer definition code for java.nio.ShortBuffer

public abstract class Buffer
extends Object sample code for java.lang.Object definition code for java.lang.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 BufferUnderflowException sample code for java.nio.BufferUnderflowException definition code for java.nio.BufferUnderflowException and a relative put operation throws a BufferOverflowException sample code for java.nio.BufferOverflowException definition code for java.nio.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 sample code for java.lang.IndexOutOfBoundsException definition code for java.lang.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 reset sample code for java.nio.Buffer.reset() definition code for java.nio.Buffer.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 sample code for java.nio.Buffer.reset() definition code for java.nio.Buffer.reset() method causes an InvalidMarkException sample code for java.nio.InvalidMarkException definition code for java.nio.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:

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 sample code for java.nio.ReadOnlyBufferException definition code for java.nio.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 sample code for java.nio.Buffer.isReadOnly() definition code for java.nio.Buffer.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);

Since:
1.4

Method Summary
 int capacity sample code for java.nio.Buffer.capacity() definition code for java.nio.Buffer.capacity() ()
          Returns this buffer's capacity.
 Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer clear sample code for java.nio.Buffer.clear() definition code for java.nio.Buffer.clear() ()
          Clears this buffer.
 Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer flip sample code for java.nio.Buffer.flip() definition code for java.nio.Buffer.flip() ()
          Flips this buffer.
 boolean hasRemaining sample code for java.nio.Buffer.hasRemaining() definition code for java.nio.Buffer.hasRemaining() ()
          Tells whether there are any elements between the current position and the limit.
abstract  boolean isReadOnly sample code for java.nio.Buffer.isReadOnly() definition code for java.nio.Buffer.isReadOnly() ()
          Tells whether or not this buffer is read-only.
 int limit sample code for java.nio.Buffer.limit() definition code for java.nio.Buffer.limit() ()
          Returns this buffer's limit.
 Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer limit sample code for java.nio.Buffer.limit(int) definition code for java.nio.Buffer.limit(int) (int newLimit)
          Sets this buffer's limit.
 Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer mark sample code for java.nio.Buffer.mark() definition code for java.nio.Buffer.mark() ()
          Sets this buffer's mark at its position.
 int position sample code for java.nio.Buffer.position() definition code for java.nio.Buffer.position() ()
          Returns this buffer's position.
 Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer position sample code for java.nio.Buffer.position(int) definition code for java.nio.Buffer.position(int) (int newPosition)
          Sets this buffer's position.
 int remaining sample code for java.nio.Buffer.remaining() definition code for java.nio.Buffer.remaining() ()
          Returns the number of elements between the current position and the limit.
 Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer reset sample code for java.nio.Buffer.reset() definition code for java.nio.Buffer.reset() ()
          Resets this buffer's position to the previously-marked position.
 Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer rewind sample code for java.nio.Buffer.rewind() definition code for java.nio.Buffer.rewind() ()
          Rewinds this buffer.
 
Methods inherited from class java.lang.Object sample code for java.lang.Object definition code for java.lang.Object
clone sample code for java.lang.Object.clone() definition code for java.lang.Object.clone() , equals sample code for java.lang.Object.equals(java.lang.Object) definition code for java.lang.Object.equals(java.lang.Object) , finalize sample code for java.lang.Object.finalize() definition code for java.lang.Object.finalize() , getClass sample code for java.lang.Object.getClass() definition code for java.lang.Object.getClass() , hashCode sample code for java.lang.Object.hashCode() definition code for java.lang.Object.hashCode() , notify sample code for java.lang.Object.notify() definition code for java.lang.Object.notify() , notifyAll sample code for java.lang.Object.notifyAll() definition code for java.lang.Object.notifyAll() , toString sample code for java.lang.Object.toString() definition code for java.lang.Object.toString() , wait sample code for java.lang.Object.wait() definition code for java.lang.Object.wait() , wait sample code for java.lang.Object.wait(long) definition code for java.lang.Object.wait(long) , wait sample code for java.lang.Object.wait(long, int) definition code for java.lang.Object.wait(long, int)
 

Method Detail

capacity sample code for java.nio.Buffer.capacity() definition code for java.nio.Buffer.capacity()

public final int capacity()
Returns this buffer's capacity.

Returns:
The capacity of this buffer

position sample code for java.nio.Buffer.position() definition code for java.nio.Buffer.position()

public final int position()
Returns this buffer's position.

Returns:
The position of this buffer

position sample code for java.nio.Buffer.position(int) definition code for java.nio.Buffer.position(int)

public final Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer  position(int newPosition)
Sets this buffer's position. If the mark is defined and larger than the new position then it is discarded.

Parameters:
newPosition - The new position value; must be non-negative and no larger than the current limit
Returns:
This buffer
Throws:
IllegalArgumentException sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - If the preconditions on newPosition do not hold

limit sample code for java.nio.Buffer.limit() definition code for java.nio.Buffer.limit()

public final int limit()
Returns this buffer's limit.

Returns:
The limit of this buffer

limit sample code for java.nio.Buffer.limit(int) definition code for java.nio.Buffer.limit(int)

public final Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer  limit(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.

Parameters:
newLimit - The new limit value; must be non-negative and no larger than this buffer's capacity
Returns:
This buffer
Throws:
IllegalArgumentException sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - If the preconditions on newLimit do not hold

mark sample code for java.nio.Buffer.mark() definition code for java.nio.Buffer.mark()

public final Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer  mark()
Sets this buffer's mark at its position.

Returns:
This buffer

reset sample code for java.nio.Buffer.reset() definition code for java.nio.Buffer.reset()

public final Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer  reset()
Resets this buffer's position to the previously-marked position.

Invoking this method neither changes nor discards the mark's value.

Returns:
This buffer
Throws:
InvalidMarkException sample code for java.nio.InvalidMarkException definition code for java.nio.InvalidMarkException - If the mark has not been set

clear sample code for java.nio.Buffer.clear() definition code for java.nio.Buffer.clear()

public final Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer  clear()
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.

Returns:
This buffer

flip sample code for java.nio.Buffer.flip() definition code for java.nio.Buffer.flip()

public final Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer  flip()
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 compact sample code for java.nio.ByteBuffer.compact() definition code for java.nio.ByteBuffer.compact() method when transferring data from one place to another.

Returns:
This buffer

rewind sample code for java.nio.Buffer.rewind() definition code for java.nio.Buffer.rewind()

public final Buffer sample code for java.nio.Buffer definition code for java.nio.Buffer  rewind()
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

Returns:
This buffer

remaining sample code for java.nio.Buffer.remaining() definition code for java.nio.Buffer.remaining()

public final int remaining()
Returns the number of elements between the current position and the limit.

Returns:
The number of elements remaining in this buffer

hasRemaining sample code for java.nio.Buffer.hasRemaining() definition code for java.nio.Buffer.hasRemaining()

public final boolean hasRemaining()
Tells whether there are any elements between the current position and the limit.

Returns:
true if, and only if, there is at least one element remaining in this buffer

isReadOnly sample code for java.nio.Buffer.isReadOnly() definition code for java.nio.Buffer.isReadOnly()

public abstract boolean isReadOnly()
Tells whether or not this buffer is read-only.

Returns:
true if, and only if, this buffer is read-only