Channels

AI-generated Key Takeaways

• The Channels class provides utility methods to connect Java's stream classes (InputStream, OutputStream, Reader, Writer) with channel classes (ReadableByteChannel, WritableByteChannel, AsynchronousByteChannel).

• These methods enable the construction of channels from streams and vice-versa, allowing data to flow between them.

• Channels created or used by these methods will generally not be buffered and closing the constructed stream or reader/writer will close the underlying channel.

• When constructing readers and writers, charset encoders and decoders can be specified or inferred from charset names to handle character encoding.

• If a channel is in non-blocking mode and a blocking operation is attempted on a stream created from it, an IllegalBlockingModeException will be thrown.

public final class Channels extends Object

Utility methods for channels and streams.

This class defines static methods that support the interoperation of the stream classes of the java.io package with the channel classes of this package.

Public Method Summary

static ReadableByteChannel	newChannel(InputStream in) Constructs a channel that reads bytes from the given stream.
static WritableByteChannel	newChannel(OutputStream out) Constructs a channel that writes bytes to the given stream.
static InputStream	newInputStream(ReadableByteChannel ch) Constructs a stream that reads bytes from the given channel.
static InputStream	newInputStream(AsynchronousByteChannel ch) Constructs a stream that reads bytes from the given channel.
static OutputStream	newOutputStream(AsynchronousByteChannel ch) Constructs a stream that writes bytes to the given channel.
static OutputStream	newOutputStream(WritableByteChannel ch) Constructs a stream that writes bytes to the given channel.
static Reader	newReader(ReadableByteChannel ch, CharsetDecoder dec, int minBufferCap) Constructs a reader that decodes bytes from the given channel using the given decoder.
static Reader	newReader(ReadableByteChannel ch, String csName) Constructs a reader that decodes bytes from the given channel according to the named charset.
static Writer	newWriter(WritableByteChannel ch, CharsetEncoder enc, int minBufferCap) Constructs a writer that encodes characters using the given encoder and writes the resulting bytes to the given channel.
static Writer	newWriter(WritableByteChannel ch, String csName) Constructs a writer that encodes characters according to the named charset and writes the resulting bytes to the given channel.

Inherited Method Summary

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

Public Methods

public static ReadableByteChannel newChannel (InputStream in)

Constructs a channel that reads bytes from the given stream.

The resulting channel will not be buffered; it will simply redirect its I/O operations to the given stream. Closing the channel will in turn cause the stream to be closed.

Parameters

in	The stream from which bytes are to be read

Returns

• A new readable byte channel

public static WritableByteChannel newChannel (OutputStream out)

Constructs a channel that writes bytes to the given stream.

The resulting channel will not be buffered; it will simply redirect its I/O operations to the given stream. Closing the channel will in turn cause the stream to be closed.

Parameters

out	The stream to which bytes are to be written

Returns

• A new writable byte channel

public static InputStream newInputStream (ReadableByteChannel ch)

Constructs a stream that reads bytes from the given channel.

The read methods of the resulting stream will throw an IllegalBlockingModeException if invoked while the underlying channel is in non-blocking mode. The stream will not be buffered, and it will not support the mark or reset methods. The stream will be safe for access by multiple concurrent threads. Closing the stream will in turn cause the channel to be closed.

Parameters

ch	The channel from which bytes will be read

Returns

• A new input stream

public static InputStream newInputStream (AsynchronousByteChannel ch)

Constructs a stream that reads bytes from the given channel.

The stream will not be buffered, and it will not support the mark or reset methods. The stream will be safe for access by multiple concurrent threads. Closing the stream will in turn cause the channel to be closed.

Parameters

ch	The channel from which bytes will be read

Returns

• A new input stream

public static OutputStream newOutputStream (AsynchronousByteChannel ch)

Constructs a stream that writes bytes to the given channel.

The stream will not be buffered. The stream will be safe for access by multiple concurrent threads. Closing the stream will in turn cause the channel to be closed.

Parameters

ch	The channel to which bytes will be written

Returns

• A new output stream

public static OutputStream newOutputStream (WritableByteChannel ch)

Constructs a stream that writes bytes to the given channel.

The write methods of the resulting stream will throw an IllegalBlockingModeException if invoked while the underlying channel is in non-blocking mode. The stream will not be buffered. The stream will be safe for access by multiple concurrent threads. Closing the stream will in turn cause the channel to be closed.

Parameters

ch	The channel to which bytes will be written

Returns

• A new output stream

public static Reader newReader (ReadableByteChannel ch, CharsetDecoder dec, int minBufferCap)

Constructs a reader that decodes bytes from the given channel using the given decoder.

The resulting stream will contain an internal input buffer of at least minBufferCap bytes. The stream's read methods will, as needed, fill the buffer by reading bytes from the underlying channel; if the channel is in non-blocking mode when bytes are to be read then an IllegalBlockingModeException will be thrown. The resulting stream will not otherwise be buffered, and it will not support the mark or reset methods. Closing the stream will in turn cause the channel to be closed.

Parameters

ch	The channel from which bytes will be read
dec	The charset decoder to be used
minBufferCap	The minimum capacity of the internal byte buffer, or -1 if an implementation-dependent default capacity is to be used

Returns

• A new reader

public static Reader newReader (ReadableByteChannel ch, String csName)

Constructs a reader that decodes bytes from the given channel according to the named charset.

An invocation of this method of the form

 Channels.newReader(ch, csname)

behaves in exactly the same way as the expression

 Channels.newReader(ch,
                    Charset.forName(csName)
                        .newDecoder(),
                    -1);

Parameters

ch	The channel from which bytes will be read
csName	The name of the charset to be used

Returns

• A new reader

Throws

UnsupportedCharsetException	If no support for the named charset is available in this instance of the Java virtual machine

public static Writer newWriter (WritableByteChannel ch, CharsetEncoder enc, int minBufferCap)

Constructs a writer that encodes characters using the given encoder and writes the resulting bytes to the given channel.

The resulting stream will contain an internal output buffer of at least minBufferCap bytes. The stream's write methods will, as needed, flush the buffer by writing bytes to the underlying channel; if the channel is in non-blocking mode when bytes are to be written then an IllegalBlockingModeException will be thrown. The resulting stream will not otherwise be buffered. Closing the stream will in turn cause the channel to be closed.

Parameters

ch	The channel to which bytes will be written
enc	The charset encoder to be used
minBufferCap	The minimum capacity of the internal byte buffer, or -1 if an implementation-dependent default capacity is to be used

Returns

• A new writer

public static Writer newWriter (WritableByteChannel ch, String csName)

Constructs a writer that encodes characters according to the named charset and writes the resulting bytes to the given channel.

An invocation of this method of the form

 Channels.newWriter(ch, csname)

behaves in exactly the same way as the expression

 Channels.newWriter(ch,
                    Charset.forName(csName)
                        .newEncoder(),
                    -1);

Parameters

ch	The channel to which bytes will be written
csName	The name of the charset to be used

Returns

• A new writer

Throws

UnsupportedCharsetException	If no support for the named charset is available in this instance of the Java virtual machine