Java in a Nutshell, 5th Edition

Name

ReadableByteChannel

Synopsis

This subinterface of Channel defines a single key read( ) method which reads bytes from the channel and stores them in the specified ByteBuffer, updating the buffer position as it does so. read( ) attempts to read as many bytes as will fit in the specified buffer, (see Buffer.remaining( )) but may read fewer than this. If the channel is a nonblocking channel, for example, the read( ) will return immediately, even if there are no bytes available to be read. read( ) returns the number of bytes actually read (which may be zero in the nonblocking case), or returns -1 if there are no more bytes to be read in the channel (if, for example, the end of a file has been reached, or the other end of a socket has been closed.)

read( ) is declared to throw an IOException. More specifically, it may throw a ClosedChannelException if the channel is closed. If the channel is closed asynchronously, or if a blocked thread is interrupted, the read( ) method may terminate with an AsynchronousCloseException or a ClosedByInterruptException. read( ) may also throw an unchecked NonReadableChannelException if it is called on a channel that was not opened or configured to allow reading.

ReadableByteChannel implementations are required to be thread-safe: only one thread may perform a read operation on a channel at a time. If a read operation is in progress, then any call to read( ) will block until the in-progress operation completes. Some channel implementations may allow read ...