Java Reference
In-Depth Information
Transferring Data Into a Buffer
The
ByteBuffer
class and all the view buffer classes have two
put()
methods for transferring a
single element of the buffer's type to the buffer. One is a relative
put()
method that transfers an
element to a given index position in the buffer and the other is an absolute put method that places the
element at an index position that you specify as an argument. They also have three relative put methods
for bulk transfer of elements of the given type. Let's consider the
put()
methods for a
ByteBuffer
object as an example.
Method
Description
put(byte
b)
Transfers the byte specified by the argument to the buffer at
the current position, and increments the position by 1. An
exception of type
BufferOverflowException
will be
thrown if the buffer's position is not less than its limit.
put(int
index,
byte
b)
Transfers the byte specified by the second argument to the
buffer at the index position specified by the first argument.
The buffer position is unchanged. An exception of type
IndexOutOfBoundsException
will be thrown if the index
value is negative or greater than or equal to the buffer's limit.
put(byte[]array)
Transfers all the elements of array to this buffer starting at the
current position. The position will be incremented by the
length of the array. An exception of type
BufferOverflowException
will be thrown if there is
insufficient space in the buffer to accommodate the contents
of array.
put(byte[]array,
int
offset,
int
length)
Transfers elements
array[offset]
to
array[offset+length-1]
inclusive to the buffer. If there
is insufficient space for them an exception of type
BufferOverflowException
will be thrown.
put(ByteBuffer
src)
Transfers the bytes remaining in
src
to the buffer. This will
be
src.remaining()
elements from the buffer
src
from
its position index to
limit-1
. If there is insufficient space to
accommodate these then an exception of type
BufferOverflowException
will be thrown. If
src
is
identical to the current buffer - you are trying to transfer a
buffer to itself in other words - an exception of type
IllegalArgumentException
will be thrown.
Each of these methods returns a reference to the buffer for which they were called. If the buffer is read-only,
any of these methods will throw an exception of type
ReadOnlyBufferException
. We will see how a
buffer can be read-only when we discuss
Using View Buffers
in more detail. Each
Buffer
class that stores
elements of a given basic type -
CharBuffer
,
DoubleBuffer
, or whatever - will have
put()
methods
analogous to these, but with arguments of a type appropriate to the type of element in the buffer.