Class Buffer
- java.lang.Object
-
- javacardx.framework.nio.Buffer
-
- Direct Known Subclasses:
ByteBuffer
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.
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<=
capacityA 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.
Clearing, flipping, and rewinding
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. -
slice()
creates a subsequence of a buffer: It leaves the limit and the position unchanged.
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);
b.flip().position(23).limit(42);
- Since:
- 3.1
-
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods 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.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.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.abstract Buffer
slice()
Creates a new buffer whose content is a shared subsequence of this buffer's content.
-
-
-
Method Detail
-
capacity
public final int capacity()
Returns this buffer's capacity.- Returns:
- The capacity of this buffer.
-
position
public final int position()
Returns this buffer's position.- Returns:
- The position of this buffer.
-
position
public final Buffer position(int newPosition)
Sets this buffer's position.- Parameters:
newPosition
- The new position value; must be nonnegative and no larger than the current limit.- Returns:
- This buffer.
- Throws:
SystemException
- with reason code SystemException.ILLEGAL_VALUE if thenewPosition
is negative or larger than the current limit.
-
limit
public final int limit()
Returns this buffer's limit.- Returns:
- The limit of this buffer.
-
limit
public final 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.- Parameters:
newLimit
- the new limit value.- Returns:
- this buffer.
- Throws:
SystemException
- with reason code SystemException.ILLEGAL_VALUE ifnewLimit
is negative or larger than this buffer's capacity.
-
clear
public final Buffer clear()
Clears this buffer. The position is set to zero and the limit is set to the capacity.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.
- Returns:
- This buffer.
-
flip
public final Buffer flip()
Flips this buffer. The limit is set to the current position and then the position is set to zero.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
This method is often used in conjunction with the compact method when transferring data from one place to another.
- Returns:
- This buffer.
-
rewind
public final Buffer rewind()
Rewinds this buffer. The position is set to zero.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
- Returns:
- this 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
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
public abstract boolean isReadOnly()
Tells whether or not this buffer is read-only.- Returns:
true
if, and only if, this buffer is read-only
-
hasArray
public abstract boolean hasArray()
Tells whether or not this buffer is backed by an accessible array.If this method returns
true
then thearrayOffset
methods may safely be invoked.- Returns:
true
if, and only if, this buffer is backed by an array and is not read-only
-
array
public abstract Object array()
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
hasArray
method before invoking this method in order to ensure that this buffer has an accessible backing array.- Returns:
- The array that backs this buffer
- Throws:
ReadOnlyBufferException
- If this buffer is backed by an array but is read-onlySystemException
- with reason code SystemException.ILLEGAL_USE if this buffer is not backed by an accessible array
-
arrayOffset
public abstract int arrayOffset()
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
hasArray
method before invoking this method in order to ensure that this buffer has an accessible backing array.- Returns:
- 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-onlySystemException
- with reason code SystemException.ILLEGAL_USE if this buffer is not backed by an accessible array
-
isDirect
public abstract boolean isDirect()
Tells whether or not this buffer is direct.- Returns:
true
if, and only if, this buffer is direct
-
slice
public abstract Buffer slice()
Creates a new buffer whose content is a shared subsequence of this buffer's content.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 and limit 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. 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.
- Returns:
- The new buffer
-
-