java.nio.channels
Interface Channel

All Known Subinterfaces:

ByteChannel, GatheringByteChannel, ReadableByteChannel, ScatteringByteChannel, WritableByteChannel

All Known Implementing Classes:

AbstractChannel, DatagramChannel, FileChannel, Pipe.SinkChannel, Pipe.SourceChannel, SelectableChannel, SocketChannel

public interface Channel

A nexus for I/O operations.

A channel represents an open connection to an entity such as a hardware device, a file, a network socket, or a program component that is capable of performing one or more distinct I/O operations, for example reading or writing.

A channel is either open or closed. A channel is open upon creation, and once closed it remains closed. Once a channel is closed, any attempt to invoke an I/O operation upon it will cause a ClosedChannelException to be thrown. Whether or not a channel is open may be tested by invoking its isOpen method.

Channels are asynchronously closeable: If a thread is blocked in an I/O operation on a channel then another thread may invoke the channel's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

Channels are also interruptible: If a thread is blocked in an I/O operation on a channel then another thread may invoke the blocked thread's interrupt method. This will cause the channel to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a channel then the channel will be closed and the thread will immediately receive a ClosedByInterruptException; its interrupt status will remain set.

Channels are, in general, intended to be safe for multithreaded access as described in the specifications of the interfaces and classes that extend and implement this interface.

Design note: Interrupts

That channels are asynchronously closeable and interruptible arises from the practical need to be able to break threads out of blocking I/O operations.

The java.io package specifies an InterruptedIOException for this purpose, the idea being that invoking a thread's interrupt method will cause the thread to break out of a blocking I/O operation and receive this exception. Unfortunately this approach has turned out to be impossible to implement both efficiently and reliably on most popular operating systems, and in fact it is well known not to work uniformly across different implementations of the Java platform.

A technique that does work, however, is to close the file descriptor or handle that is the subject of the operation in which the target thread is blocked. Despite the fact that this closes the corresponding stream or channel, this behavior is often acceptable because the most common reason for interrupting a thread is to ask it to shut down. It is also difficult in practice to write systems that deal gracefully at a high level with partly-completed I/O operations; it is often simply easier to discard a stream or channel that's in an unknown state and recover in some other way, e.g., by opening a new connection. Hence this technique has come to be known as a portable workaround for the lack of true interruptible I/O in the java.io package.

The approach taken here, then, is to codify the close-on-interrupt technique in the java.nio package. The closing-on-interrupt of a channel is treated as a special case of asynchronously closing a channel. Each condition is given a distinct exception because application code may want to treat the interrupting case specially.

Since:

1.4

Method Summary

void	close() Closes this channel.
boolean	isOpen() Tells whether or not this channel is open.

Method Detail

isOpen

public boolean isOpen()

Tells whether or not this channel is open.

Returns:

true if, and only if, this channel is open

close

public void close()
           throws IOException

Closes this channel.

Any thread currently blocked in an I/O operation upon this channel will receive an AsynchronousCloseException.

After a channel is closed, any further attempt to invoke I/O operations upon it will cause a ClosedChannelException to be thrown.

If this channel is already closed then invoking this method has no effect.

This method may be invoked at any time. If some other thread has already invoked it, however, then another invocation will block until the first invocation is complete, after which it will return without effect.

Throws:

IOException - If an I/O error occurs