FileDocCategorySizeDatePackage
Buffer.javaAPI DocphoneME MR2 API (J2ME)13559Wed May 02 18:00:46 BST 2007java.nio

Buffer

public abstract class Buffer extends Object

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);

Fields Summary
int
capacity
int
limit
int
position
Constructors Summary
Buffer()

Methods Summary
public final intcapacity()
Returns this buffer's capacity.
return
The capacity of this buffer.
	return capacity;
    
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. JSR 239 does
not support marking and resetting.


 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




 JSR 239 does not support channels.


 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.
        this.position = 0;
        this.limit = this.capacity;
        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. JSR 239 does
not support marking and resetting.


 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.


 JSR 239 does not support channels.
return
This buffer.
        this.limit = this.position;
        this.position = 0;
        return this;
    
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 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. JSR 239 does not support marking and
resetting.
param
newLimit the new limit value.
return
this buffer.
throws
IllegalArgumentException if newLimit is
negative or larger than this buffer's capacity.
        if (newLimit < 0 || newLimit > capacity) {
            throw new IllegalArgumentException();
        }
        if (position > newLimit) {
            position = newLimit;
        }
	this.limit = newLimit;
	return this;
    
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. JSR 239 does
not support marking and resetting.
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 < 0 || newPosition > limit) {
            throw new IllegalArgumentException();
        }
	this.position = newPosition;
	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.Bufferrewind()
Rewinds this buffer. The position is set to zero and the mark
is discarded. JSR 239 does
not support marking and resetting.


 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




 JSR 239 does not support channels.
        this.position = 0;
        return this;