Java Reference
In-Depth Information
•
int read(ByteBuffer buf))
: Tries to read
buf.remaining()
bytes (equivalent to
limit-pos-
ition
bytes) from the file into the buffer,
buf
, starting at the buffer's current position. The number
of bytes read is returned, or −1 if the channel reaches the end-of-file during the operation. The
buffer position is incremented by the number of bytes read and the buffer's limit is left unchanged.
•
int read(ByteBuffer[] buffers))
: Tries to read bytes into each of the buffers in the
buffers
array in sequence. Bytes are read into each buffer starting at the point defined by that buffer's
position. The number of bytes read into each buffer is defined by the
remaining()
method for
that buffer. The
read()
method returns the total number of bytes read or −1 if the channel reaches
the end-of-file during the operation. Each buffer's position is incremented by the number of bytes
read into it. Each buffer's limit is unchanged.
•
int read(ByteBuffer[] buffers,int offset, int length))
: This operations works in
the same way as the previous method except that bytes are read starting with the buffer
buf-
fers[offset]
, up to and including the buffer
buffers[offset+length-1]
. This method throws
an exception of type
IndexOutOfBoundsException
if
offset
or
offset+length-1
are not valid
index values for the
buffers
array.
As you can see, all three
read()
methods read data into one or more buffers of type
ByteBuffer
. The
file position is incremented by the number of bytes read. Because you can use only
ByteBuffer
objects to
receive the data read from the file, you can only read data as a series of bytes. How you interpret these bytes
afterward, though, is up to you. View buffers provide you with a lot of possibilities.
These methods are distributed among the channel interfaces so the type you use to store the reference to
the channel object can be important. The first
read()
method in the list that reads bytes into a single buf-
fer is declared in the
ReadableByteChannel
interface, which the
SeekableByteChannel
interface extends
along with the
WritableByteChannel
interface. The other two
read()
methods are declared in the
Sc-
atteringByteChannel
interface that the
FileChannel
class implements. The
newByteChannel()
method
returns a reference of type
SeekableByteChannel
, so if you want to use the two latter
read()
methods that
work with arrays of buffers, you must cast the reference that these methods return to type
FileChannel
.
All three methods can throw exceptions of any of the following types:
•
NonReadableChannelException
is thrown if the file is not opened for reading.
•
ClosedChannelException
is thrown if the channel is closed.
•
AsynchronousCloseException
is thrown if the channel is closed by another thread while the read
operation is in progress.
•
ClosedByInterruptException
is thrown if another thread interrupts the current thread while the
read operation is in progress.
•
IOException
is thrown if some other I/O error occurs.
The third
read()
method that enables you to read data into a subset of buffers from an array can also
throw an
IndexOutOfBoundsException
if the index parameters are inconsistent or invalid.
The
FileChannel
object keeps track of the file's current position. This is initially set to zero, which cor-
responds to the first byte available from the file. Each read operation increments the channel's file position
by the number of bytes read, so the next read operation starts at that point, assuming you don't modify the
file position by some other means. When you need to change the file position in the channel — to reread
the file, for example — you just call the
position()
method for the
FileChannel
object, with the index
position of the byte where you want the next read to start as the argument to the method. For example, with
a reference to a
FileChannel
object stored in a variable
inChannel
, you could reset the file position to the
beginning of the file with the following statements: