APIdia Launch Partner
Top Description Inners Constructors Methods
java.nio.channels

public final Class Channels

extends Object
Class Inheritance
Imports
java.io.FileInputStream, .FileOutputStream, .InputStream, .OutputStream, .Reader, .Writer, .IOException, java.nio.ByteBuffer, java.nio.charset.Charset, .CharsetDecoder, .CharsetEncoder, .UnsupportedCharsetException, java.nio.channels.spi.AbstractInterruptibleChannel, java.util.Objects, java.util.concurrent.ExecutionException, sun.nio.cs.StreamDecoder, .StreamEncoder
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.

Authors
Mark Reinhold, Mike McCloskey, JSR-51 Expert Group
Since
1.4

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
Channels.ReadableByteChannelImpl

private static class
Channels.WritableByteChannelImpl

Constructor Summary

AccessConstructor and Description
private
Channels()

Method Summary

Modifier and TypeMethod and Description
public static ReadableByteChannel

Returns:

A new readable byte channel
newChannel(InputStream
The stream from which bytes are to be read
in)

Constructs a channel that reads bytes from the given stream.

public static WritableByteChannel

Returns:

A new writable byte channel
newChannel(OutputStream
The stream to which bytes are to be written
out)

Constructs a channel that writes bytes to the given stream.

public static InputStream

Returns:

A new input stream
newInputStream(ReadableByteChannel
The channel from which bytes will be read
ch)

Constructs a stream that reads bytes from the given channel.

public static InputStream

Returns:

A new input stream
newInputStream(AsynchronousByteChannel
The channel from which bytes will be read
ch)

Constructs a stream that reads bytes from the given channel.

public static OutputStream

Returns:

A new output stream
newOutputStream(WritableByteChannel
The channel to which bytes will be written
ch)

Constructs a stream that writes bytes to the given channel.

public static OutputStream

Returns:

A new output stream
newOutputStream(AsynchronousByteChannel
The channel to which bytes will be written
ch)

Constructs a stream that writes bytes to the given channel.

public static Reader

Returns:

A new reader
newReader(ReadableByteChannel
The channel from which bytes will be read
ch, CharsetDecoder
The charset decoder to be used
dec, int
The minimum capacity of the internal byte buffer, or -1 if an implementation-dependent default capacity is to be used
minBufferCap)

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

public static Reader

Returns:

A new reader
newReader(ReadableByteChannel
The channel from which bytes will be read
ch, String
The name of the charset to be used
csName)

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

public static Reader

Returns:

A new reader
newReader(ReadableByteChannel
The channel from which bytes will be read
ch, Charset
The charset to be used
charset)

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

public static Writer

Returns:

A new writer
newWriter(WritableByteChannel
The channel to which bytes will be written
ch, CharsetEncoder
The charset encoder to be used
enc, int
The minimum capacity of the internal byte buffer, or -1 if an implementation-dependent default capacity is to be used. The value of minBufferCap may be ignored
minBufferCap)

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

public static Writer

Returns:

A new writer
newWriter(WritableByteChannel
The channel to which bytes will be written
ch, String
The name of the charset to be used
csName)

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

public static Writer

Returns:

A new writer
newWriter(WritableByteChannel
The channel to which bytes will be written
ch, Charset
The charset to be used
charset)

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Channelsback to summary
private Channels()

Method Detail

newChannelback to summary
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. Reading from the resulting channel will read from the input stream and thus block until input is available or end of file is reached. Closing the channel will in turn cause the stream to be closed.

Parameters
in:InputStream

The stream from which bytes are to be read

Returns:ReadableByteChannel

A new readable byte channel

newChannelback to summary
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:OutputStream

The stream to which bytes are to be written

Returns:WritableByteChannel

A new writable byte channel

newInputStreamback to summary
public static InputStream newInputStream(ReadableByteChannel ch)

Constructs a stream that reads bytes from the given channel.

The read and transferTo methods of the resulting stream will throw an IllegalBlockingModeException if invoked while the underlying channel is in non-blocking mode. The transferTo method will also throw an IllegalBlockingModeException if invoked to transfer bytes to an output stream that writes to an underlying channel 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:ReadableByteChannel

The channel from which bytes will be read

Returns:InputStream

A new input stream

newInputStreamback to summary
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:AsynchronousByteChannel

The channel from which bytes will be read

Returns:InputStream

A new input stream

Since
1.7
newOutputStreamback to summary
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:WritableByteChannel

The channel to which bytes will be written

Returns:OutputStream

A new output stream

newOutputStreamback to summary
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:AsynchronousByteChannel

The channel to which bytes will be written

Returns:OutputStream

A new output stream

Since
1.7
newReaderback to summary
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:ReadableByteChannel

The channel from which bytes will be read

dec:CharsetDecoder

The charset decoder to be used

minBufferCap:int

The minimum capacity of the internal byte buffer, or -1 if an implementation-dependent default capacity is to be used

Returns:Reader

A new reader

newReaderback to summary
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) 
Channels.newReader(ch, csname)
behaves in exactly the same way as the expression
Channels.newReader(ch, Charset.forName(csName)) 
Channels.newReader(ch, Charset.forName(csName))
Parameters
ch:ReadableByteChannel

The channel from which bytes will be read

csName:String

The name of the charset to be used

Returns:Reader

A new reader

Exceptions
UnsupportedCharsetException:
If no support for the named charset is available in this instance of the Java virtual machine
newReaderback to summary
public static Reader newReader(ReadableByteChannel ch, Charset charset)

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

An invocation of this method of the form

Channels.newReader(ch, charset) 
Channels.newReader(ch, charset)
behaves in exactly the same way as the expression
Channels.newReader(ch, charset.newDecoder(), -1) 
Channels.newReader(ch, charset.newDecoder(), -1)

The reader's default action for malformed-input and unmappable-character errors is to report them. When more control over the error handling is required, the constructor that takes a java.nio.charset.CharsetDecoder should be used.

Parameters
ch:ReadableByteChannel

The channel from which bytes will be read

charset:Charset

The charset to be used

Returns:Reader

A new reader

Since
10
newWriterback to summary
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.

Implementation Note

The value of minBufferCap is ignored.

Parameters
ch:WritableByteChannel

The channel to which bytes will be written

enc:CharsetEncoder

The charset encoder to be used

minBufferCap:int

The minimum capacity of the internal byte buffer, or -1 if an implementation-dependent default capacity is to be used. The value of minBufferCap may be ignored

Returns:Writer

A new writer

newWriterback to summary
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) 
Channels.newWriter(ch, csname)
behaves in exactly the same way as the expression
Channels.newWriter(ch, Charset.forName(csName)) 
Channels.newWriter(ch, Charset.forName(csName))
Parameters
ch:WritableByteChannel

The channel to which bytes will be written

csName:String

The name of the charset to be used

Returns:Writer

A new writer

Exceptions
UnsupportedCharsetException:
If no support for the named charset is available in this instance of the Java virtual machine
newWriterback to summary
public static Writer newWriter(WritableByteChannel ch, Charset charset)

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

An invocation of this method of the form

Channels.newWriter(ch, charset) 
Channels.newWriter(ch, charset)
behaves in exactly the same way as the expression
Channels.newWriter(ch, charset.newEncoder(), -1) 
Channels.newWriter(ch, charset.newEncoder(), -1)

The writer's default action for malformed-input and unmappable-character errors is to report them. When more control over the error handling is required, the constructor that takes a java.nio.charset.CharsetEncoder should be used.

Parameters
ch:WritableByteChannel

The channel to which bytes will be written

charset:Charset

The charset to be used

Returns:Writer

A new writer

Since
10
java.nio.channels back to summary

private Class Channels.ReadableByteChannelImpl

extends AbstractInterruptibleChannel
implements ReadableByteChannel
Class Inheritance
All Implemented Interfaces
java.nio.channels.ReadableByteChannel, java.nio.channels.Channel, java.io.Closeable, java.lang.AutoCloseable

Field Summary

Modifier and TypeField and Description
private byte[]
buf

private final InputStream
in

private final Object
readLock

private static final int
TRANSFER_SIZE

Constructor Summary

AccessConstructor and Description
pack-priv
ReadableByteChannelImpl(InputStream in)

Method Summary

Modifier and TypeMethod and Description
protected void
implCloseChannel()

Implements abstract java.nio.channels.spi.AbstractInterruptibleChannel.implCloseChannel.

Closes this channel.

public int
read(ByteBuffer dst)

Implements java.nio.channels.ReadableByteChannel.read.

Reads a sequence of bytes from this channel into the given buffer.

Inherited from java.nio.channels.spi.AbstractInterruptibleChannel:
begincloseendisOpen

Field Detail

bufback to summary
private byte[] buf
inback to summary
private final InputStream in
readLockback to summary
private final Object readLock
TRANSFER_SIZEback to summary
private static final int TRANSFER_SIZE

Constructor Detail

ReadableByteChannelImplback to summary
pack-priv ReadableByteChannelImpl(InputStream in)

Method Detail

implCloseChannelback to summary
protected void implCloseChannel() throws IOException

Implements abstract java.nio.channels.spi.AbstractInterruptibleChannel.implCloseChannel.

Doc from java.nio.channels.spi.AbstractInterruptibleChannel.implCloseChannel.

Closes this channel.

This method is invoked by the close method in order to perform the actual work of closing the channel. This method is only invoked if the channel has not yet been closed, and it is never invoked more than once.

An implementation of this method must arrange for any other thread that is blocked in an I/O operation upon this channel to return immediately, either by throwing an exception or by returning normally.

Annotations
@Override
Exceptions
IOException:
If an I/O error occurs while closing the channel
readback to summary
public int read(ByteBuffer dst) throws IOException

Implements java.nio.channels.ReadableByteChannel.read.

Doc from java.nio.channels.ReadableByteChannel.read.

Reads a sequence of bytes from this channel into the given buffer.

An attempt is made to read up to r bytes from the channel, where r is the number of bytes remaining in the buffer, that is, dst.remaining(), at the moment this method is invoked.

Suppose that a byte sequence of length n is read, where 0 <= n <= r. This byte sequence will be transferred into the buffer so that the first byte in the sequence is at index p and the last byte is at index p + n - 1, where p is the buffer's position at the moment this method is invoked. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

A read operation might not fill the buffer, and in fact it might not read any bytes at all. Whether or not it does so depends upon the nature and state of the channel. A socket channel in non-blocking mode, for example, cannot read any more bytes than are immediately available from the socket's input buffer; similarly, a file channel cannot read any more bytes than remain in the file. It is guaranteed, however, that if a channel is in blocking mode and there is at least one byte remaining in the buffer then this method will block until at least one byte is read.

This method may be invoked at any time. If another thread has already initiated a read operation upon this channel, however, then an invocation of this method will block until the first operation is complete.

Annotations
@Override
Exceptions
IOException:
If some other I/O error occurs
java.nio.channels back to summary

private Class Channels.WritableByteChannelImpl

extends AbstractInterruptibleChannel
implements WritableByteChannel
Class Inheritance
All Implemented Interfaces
java.nio.channels.WritableByteChannel, java.nio.channels.Channel, java.io.Closeable, java.lang.AutoCloseable

Field Summary

Modifier and TypeField and Description
private byte[]
buf

private final OutputStream
out

private static final int
TRANSFER_SIZE

private final Object
writeLock

Constructor Summary

AccessConstructor and Description
pack-priv
WritableByteChannelImpl(OutputStream out)

Method Summary

Modifier and TypeMethod and Description
protected void
implCloseChannel()

Implements abstract java.nio.channels.spi.AbstractInterruptibleChannel.implCloseChannel.

Closes this channel.

public int
write(ByteBuffer src)

Implements java.nio.channels.WritableByteChannel.write.

Writes a sequence of bytes to this channel from the given buffer.

Inherited from java.nio.channels.spi.AbstractInterruptibleChannel:
begincloseendisOpen

Field Detail

bufback to summary
private byte[] buf
outback to summary
private final OutputStream out
TRANSFER_SIZEback to summary
private static final int TRANSFER_SIZE
writeLockback to summary
private final Object writeLock

Constructor Detail

WritableByteChannelImplback to summary
pack-priv WritableByteChannelImpl(OutputStream out)

Method Detail

implCloseChannelback to summary
protected void implCloseChannel() throws IOException

Implements abstract java.nio.channels.spi.AbstractInterruptibleChannel.implCloseChannel.

Doc from java.nio.channels.spi.AbstractInterruptibleChannel.implCloseChannel.

Closes this channel.

This method is invoked by the close method in order to perform the actual work of closing the channel. This method is only invoked if the channel has not yet been closed, and it is never invoked more than once.

An implementation of this method must arrange for any other thread that is blocked in an I/O operation upon this channel to return immediately, either by throwing an exception or by returning normally.

Annotations
@Override
Exceptions
IOException:
If an I/O error occurs while closing the channel
writeback to summary
public int write(ByteBuffer src) throws IOException

Implements java.nio.channels.WritableByteChannel.write.

Doc from java.nio.channels.WritableByteChannel.write.

Writes a sequence of bytes to this channel from the given buffer.

An attempt is made to write up to r bytes to the channel, where r is the number of bytes remaining in the buffer, that is, src.remaining(), at the moment this method is invoked.

Suppose that a byte sequence of length n is written, where 0 <= n <= r. This byte sequence will be transferred from the buffer starting at index p, where p is the buffer's position at the moment this method is invoked; the index of the last byte written will be p + n - 1. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

For many types of channels, a write operation will return only after writing all of the r requested bytes. Some types of channels, depending upon their state, may write only some of the bytes or possibly none at all. A socket channel in non-blocking mode, for example, cannot write any more bytes than are free in the socket's output buffer. The write method may need to be invoked more than once to ensure that all remaining bytes are written.

This method may be invoked at any time. If another thread has already initiated a write operation upon this channel, however, then an invocation of this method will block until the first operation is complete.

Annotations
@Override
Exceptions
IOException:
If some other I/O error occurs