Writing Files - Beginning Java - page 459

METHOD DESCRIPTION

— you are trying to transfer a buffer to itself,; in other words — , an exception of type IllegalAr-
gumentException is thrown.

Each of these methods returns a reference to the buffer for which it was called. If the buffer is read-only,
any of these methods throws an exception of type ReadOnlyBufferException . You see how a buffer can
be read-only when I discuss using view buffers in more detail. Each buffer object that stores elements of a
given primitive type — CharBuffer , DoubleBuffer , or whatever — has put() methods analogous to those
for ByteBuffer , but with arguments of a type appropriate to the type of element in the buffer.
The ByteBuffer class has some extra methods that enable you to transfer binary data of other primitive
types to the buffer. For example, you can transfer a value of type double to a buffer of type ByteBuffer
with either of the methods in Table 10-8 .

TABLE 10-8 : ByteBuffer Methods that Transfer double Values
METHOD

DESCRIPTION

Transfers the double value specified by the argument to the buffer at the current position and in-
crements the position by 8. If there are fewer than 8 bytes remaining in the buffer, an exception of
type BufferOverflowException is thrown.

putDouble(double
value)

Transfers the double value specified by the second argument to the buffer starting at the index po-
sition specified by the first argument. The buffer's position is unchanged. If there are fewer than 8
bytes remaining in the buffer, an exception of type BufferOverflowException is thrown. If in-
dex is negative or the buffer's limit is less than or equal to index + 7, the method throws an excep-
tion of type IndexOutOfBoundsException .

putDouble(int
index, double
value)

Note that these provide for transferring only single values. If you want to transfer an array of values you
must use a loop. Similar pairs of methods to the preceding are defined in the ByteBuffer class to transfer
values of other primitive types. These are the methods putChar() , putShort() , putInt() , putLong() , and
putFloat() , each of which transfers a value of the corresponding type. Like the other put() methods you
have seen, these all return a reference to the buffer for which they are called. This is to enable you to chain
the calls for these methods together in a single statement if you want. For example:
String text = "Value of e = ";
ByteBuffer buf = ByteBuffer.allocate(text.length()+ sizeof(Math.E));
buf.put(text.getBytes()).putDouble(Math.E);
buf.rewind(); // Reset the current position to zero

Here, you write the string to the buffer by converting it to bytes by calling its getBytes() method and
passing the result to the put() method for the buffer. The put() method returns a reference to the buffer,
buf , so you use that to call the putDouble() method to write the 8 bytes for the double value, Math.E , to
the buffer. Of course, putDouble() also returns a reference to buf , so you can chain further calls together in
the same statement if you wish. Here the buffer capacity has been allocated so that it exactly accommodates
the data to be loaded, so the capacity is 21 bytes. Each time you call the put() method for a buffer, the po-
sition is moved to the next available position in the buffer. To write the data to the buffer, the position must
be set to where the contents to be written start. Calling the rewind() method for a buffer resets the position
to zero.
The putDouble() method writes the 8-byte binary double value to the buffer, so you are not going to be
able to read this very easily by inspecting the file. If you want to write the value of Math.E as characters,
you could use the following code: