org.xnio.channels

Class Channels

java.lang.Object

org.xnio.channels.Channels

public final class Channels
extends Object

A utility class containing static methods to support channel usage.

Method Summary

Modifier and Type	Method and Description
static <C extends ConnectedChannel,A extends AcceptingChannel<C>> C	acceptBlocking(A channel) Simple utility method to execute a blocking accept on an accepting channel.
static <C extends ConnectedChannel,A extends AcceptingChannel<C>> C	acceptBlocking(A channel, long time, TimeUnit unit) Simple utility method to execute a blocking accept on an accepting channel, with a timeout.
static long	drain(FileChannel channel, long position, long count) Attempt to drain the given number of bytes from the file channel.
static long	drain(ReadableByteChannel channel, long count) Attempt to drain the given number of bytes from the readable byte channel.
static long	drain(StreamSourceChannel channel, long count) Attempt to drain the given number of bytes from the stream source channel.
static void	flushBlocking(SuspendableWriteChannel channel) Simple utility method to execute a blocking flush on a writable channel.
static boolean	getOption(Configurable configurable, Option<Boolean> option, boolean defaultValue) Get an option value from a configurable target.
static int	getOption(Configurable configurable, Option<Integer> option, int defaultValue) Get an option value from a configurable target.
static long	getOption(Configurable configurable, Option<Long> option, long defaultValue) Get an option value from a configurable target.
static <T> T	getOption(Configurable configurable, Option<T> option, T defaultValue) Get an option value from a configurable target.
static <C extends ReadableByteChannel & SuspendableReadChannel> int	readBlocking(C channel, ByteBuffer buffer) Simple utility method to execute a blocking read on a readable byte channel.
static <C extends ScatteringByteChannel & SuspendableReadChannel> long	readBlocking(C channel, ByteBuffer[] buffers, int offs, int len) Simple utility method to execute a blocking read on a scattering byte channel.
static <C extends ScatteringByteChannel & SuspendableReadChannel> long	readBlocking(C channel, ByteBuffer[] buffers, int offs, int len, long time, TimeUnit unit) Simple utility method to execute a blocking read on a scattering byte channel with a timeout.
static <C extends ReadableByteChannel & SuspendableReadChannel> int	readBlocking(C channel, ByteBuffer buffer, long time, TimeUnit unit) Simple utility method to execute a blocking read on a readable byte channel with a timeout.
static <C extends ReadableMessageChannel> int	receiveBlocking(C channel, ByteBuffer buffer) Simple utility method to execute a blocking receive on a readable message channel.
static <C extends ReadableMessageChannel> long	receiveBlocking(C channel, ByteBuffer[] buffers, int offs, int len) Simple utility method to execute a blocking receive on a readable message channel.
static <C extends ReadableMessageChannel> long	receiveBlocking(C channel, ByteBuffer[] buffers, int offs, int len, long time, TimeUnit unit) Simple utility method to execute a blocking receive on a readable message channel with a timeout.
static <C extends ReadableMessageChannel> int	receiveBlocking(C channel, ByteBuffer buffer, long time, TimeUnit unit) Simple utility method to execute a blocking receive on a readable message channel with a timeout.
static void	resumeReadsAsync(SuspendableReadChannel channel) Resume reads asynchronously.
static void	resumeWritesAsync(SuspendableWriteChannel channel) Resume writes asynchronously.
static <C extends WritableMessageChannel> void	sendBlocking(C channel, ByteBuffer buffer) Simple utility method to execute a blocking send on a message channel.
static <C extends WritableMessageChannel> void	sendBlocking(C channel, ByteBuffer[] buffers, int offs, int len) Simple utility method to execute a blocking gathering send on a message channel.
static <C extends WritableMessageChannel> boolean	sendBlocking(C channel, ByteBuffer[] buffers, int offs, int len, long time, TimeUnit unit) Simple utility method to execute a blocking gathering send on a message channel with a timeout.
static <C extends WritableMessageChannel> boolean	sendBlocking(C channel, ByteBuffer buffer, long time, TimeUnit unit) Simple utility method to execute a blocking send on a message channel with a timeout.
static <T extends AcceptingChannel<?>> void	setAcceptListener(T channel, ChannelListener<? super T> listener) Set the accept listener for a channel (type-safe).
static <T extends CloseableChannel> void	setCloseListener(T channel, ChannelListener<? super T> listener) Set the close listener for a channel (type-safe).
static <T extends SuspendableReadChannel> void	setReadListener(T channel, ChannelListener<? super T> listener) Set the read listener for a channel (type-safe).
static <T extends SuspendableWriteChannel> void	setWriteListener(T channel, ChannelListener<? super T> listener) Set the write listener for a channel (type-safe).
static void	shutdownWritesBlocking(SuspendableWriteChannel channel) Simple utility method to execute a blocking write shutdown on a writable channel.
static void	transferBlocking(FileChannel destination, StreamSourceChannel source, long startPosition, long count) Transfer bytes between two channels efficiently, blocking if necessary.
static void	transferBlocking(StreamSinkChannel destination, FileChannel source, long startPosition, long count) Transfer bytes between two channels efficiently, blocking if necessary.
static long	transferBlocking(StreamSinkChannel destination, StreamSourceChannel source, ByteBuffer throughBuffer, long count) Transfer bytes between two channels efficiently, blocking if necessary.
static <T extends Channel> T	unwrap(Class<T> targetType, Channel channel) Unwrap a nested channel type.
static ByteChannel	wrapByteChannel(ByteChannel original) Create a wrapper for a byte channel which does not expose other methods.
static <C extends WritableByteChannel & SuspendableWriteChannel> int	writeBlocking(C channel, ByteBuffer buffer) Simple utility method to execute a blocking write on a byte channel.
static <C extends GatheringByteChannel & SuspendableWriteChannel> long	writeBlocking(C channel, ByteBuffer[] buffers, int offs, int len) Simple utility method to execute a blocking write on a gathering byte channel.
static <C extends GatheringByteChannel & SuspendableWriteChannel> long	writeBlocking(C channel, ByteBuffer[] buffers, int offs, int len, long time, TimeUnit unit) Simple utility method to execute a blocking write on a gathering byte channel with a timeout.
static <C extends WritableByteChannel & SuspendableWriteChannel> int	writeBlocking(C channel, ByteBuffer buffer, long time, TimeUnit unit) Simple utility method to execute a blocking write on a byte channel with a timeout.
static int	writeFinalBasic(StreamSinkChannel channel, ByteBuffer src) Writes out the data in the buffer to the channel.
static long	writeFinalBasic(StreamSinkChannel channel, ByteBuffer[] srcs, int offset, int length) Writes out the data in the buffer to the channel.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

flushBlocking

public static void flushBlocking(SuspendableWriteChannel channel)
                          throws IOException

Simple utility method to execute a blocking flush on a writable channel. The method blocks until there are no remaining bytes in the send queue.

Parameters:

channel - the writable channel

Throws:

IOException - if an I/O exception occurs

Since:

2.0

shutdownWritesBlocking

public static void shutdownWritesBlocking(SuspendableWriteChannel channel)
                                   throws IOException

Simple utility method to execute a blocking write shutdown on a writable channel. The method blocks until the channel's output side is fully shut down.

Parameters:

channel - the writable channel

Throws:

IOException - if an I/O exception occurs

Since:

2.0

writeBlocking

public static <C extends WritableByteChannel & SuspendableWriteChannel> int writeBlocking(C channel,
                                                                                          ByteBuffer buffer)
                                                                                   throws IOException

Simple utility method to execute a blocking write on a byte channel. The method blocks until the bytes in the buffer have been fully written. To ensure that the data is sent, the flushBlocking(SuspendableWriteChannel) method should be called after all writes are complete.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to write on

buffer - the data to write

Returns:

the number of bytes written

Throws:

IOException - if an I/O exception occurs

Since:

1.2

writeBlocking

public static <C extends WritableByteChannel & SuspendableWriteChannel> int writeBlocking(C channel,
                                                                                          ByteBuffer buffer,
                                                                                          long time,
                                                                                          TimeUnit unit)
                                                                                   throws IOException

Simple utility method to execute a blocking write on a byte channel with a timeout. The method blocks until either the bytes in the buffer have been fully written, or the timeout expires, whichever comes first.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to write on

buffer - the data to write

time - the amount of time to wait

unit - the unit of time to wait

Returns:

the number of bytes written

Throws:

IOException - if an I/O exception occurs

Since:

1.2

writeBlocking

public static <C extends GatheringByteChannel & SuspendableWriteChannel> long writeBlocking(C channel,
                                                                                            ByteBuffer[] buffers,
                                                                                            int offs,
                                                                                            int len)
                                                                                     throws IOException

Simple utility method to execute a blocking write on a gathering byte channel. The method blocks until the bytes in the buffer have been fully written.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to write on

buffers - the data to write

offs - the index of the first buffer to write

len - the number of buffers to write

Returns:

the number of bytes written

Throws:

IOException - if an I/O exception occurs

Since:

1.2

writeBlocking

public static <C extends GatheringByteChannel & SuspendableWriteChannel> long writeBlocking(C channel,
                                                                                            ByteBuffer[] buffers,
                                                                                            int offs,
                                                                                            int len,
                                                                                            long time,
                                                                                            TimeUnit unit)
                                                                                     throws IOException

Simple utility method to execute a blocking write on a gathering byte channel with a timeout. The method blocks until all the bytes are written, or until the timeout occurs.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to write on

buffers - the data to write

offs - the index of the first buffer to write

len - the number of buffers to write

time - the amount of time to wait

unit - the unit of time to wait

Returns:

the number of bytes written

Throws:

IOException - if an I/O exception occurs

Since:

1.2

sendBlocking

public static <C extends WritableMessageChannel> void sendBlocking(C channel,
                                                                   ByteBuffer buffer)
                                                            throws IOException

Simple utility method to execute a blocking send on a message channel. The method blocks until the message is written.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to write on

buffer - the data to write

Throws:

IOException - if an I/O exception occurs

Since:

1.2

sendBlocking

public static <C extends WritableMessageChannel> boolean sendBlocking(C channel,
                                                                      ByteBuffer buffer,
                                                                      long time,
                                                                      TimeUnit unit)
                                                               throws IOException

Simple utility method to execute a blocking send on a message channel with a timeout. The method blocks until the channel is writable, and then the message is written.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to write on

buffer - the data to write

time - the amount of time to wait

unit - the unit of time to wait

Returns:

the write result

Throws:

IOException - if an I/O exception occurs

Since:

1.2

sendBlocking

public static <C extends WritableMessageChannel> void sendBlocking(C channel,
                                                                   ByteBuffer[] buffers,
                                                                   int offs,
                                                                   int len)
                                                            throws IOException

Simple utility method to execute a blocking gathering send on a message channel. The method blocks until the message is written.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to write on

buffers - the data to write

offs - the index of the first buffer to write

len - the number of buffers to write

Throws:

IOException - if an I/O exception occurs

Since:

1.2

sendBlocking

public static <C extends WritableMessageChannel> boolean sendBlocking(C channel,
                                                                      ByteBuffer[] buffers,
                                                                      int offs,
                                                                      int len,
                                                                      long time,
                                                                      TimeUnit unit)
                                                               throws IOException

Simple utility method to execute a blocking gathering send on a message channel with a timeout. The method blocks until either the message is written or the timeout expires.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to write on

buffers - the data to write

offs - the index of the first buffer to write

len - the number of buffers to write

time - the amount of time to wait

unit - the unit of time to wait

Returns:

true if the message was written before the timeout

Throws:

IOException - if an I/O exception occurs

Since:

1.2

readBlocking

public static <C extends ReadableByteChannel & SuspendableReadChannel> int readBlocking(C channel,
                                                                                        ByteBuffer buffer)
                                                                                 throws IOException

Simple utility method to execute a blocking read on a readable byte channel. This method blocks until the channel is readable, and then the message is read.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to read from

buffer - the buffer into which bytes are to be transferred

Returns:

the number of bytes read

Throws:

IOException - if an I/O exception occurs

Since:

1.2

readBlocking

public static <C extends ReadableByteChannel & SuspendableReadChannel> int readBlocking(C channel,
                                                                                        ByteBuffer buffer,
                                                                                        long time,
                                                                                        TimeUnit unit)
                                                                                 throws IOException

Simple utility method to execute a blocking read on a readable byte channel with a timeout. This method blocks until the channel is readable, and then the message is read.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to read from

buffer - the buffer into which bytes are to be transferred

time - the amount of time to wait

unit - the unit of time to wait

Returns:

the number of bytes read

Throws:

IOException - if an I/O exception occurs

Since:

1.2

readBlocking

public static <C extends ScatteringByteChannel & SuspendableReadChannel> long readBlocking(C channel,
                                                                                           ByteBuffer[] buffers,
                                                                                           int offs,
                                                                                           int len)
                                                                                    throws IOException

Simple utility method to execute a blocking read on a scattering byte channel. This method blocks until the channel is readable, and then the message is read.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to read from

buffers - the buffers into which bytes are to be transferred

offs - the first buffer to use

len - the number of buffers to use

Returns:

the number of bytes read

Throws:

IOException - if an I/O exception occurs

Since:

1.2

readBlocking

public static <C extends ScatteringByteChannel & SuspendableReadChannel> long readBlocking(C channel,
                                                                                           ByteBuffer[] buffers,
                                                                                           int offs,
                                                                                           int len,
                                                                                           long time,
                                                                                           TimeUnit unit)
                                                                                    throws IOException

Simple utility method to execute a blocking read on a scattering byte channel with a timeout. This method blocks until the channel is readable, and then the message is read.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to read from

buffers - the buffers into which bytes are to be transferred

offs - the first buffer to use

len - the number of buffers to use

time - the amount of time to wait

unit - the unit of time to wait

Returns:

the number of bytes read

Throws:

IOException - if an I/O exception occurs

Since:

1.2

receiveBlocking

public static <C extends ReadableMessageChannel> int receiveBlocking(C channel,
                                                                     ByteBuffer buffer)
                                                              throws IOException

Simple utility method to execute a blocking receive on a readable message channel. This method blocks until the channel is readable, and then the message is received.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to read from

buffer - the buffer into which bytes are to be transferred

Returns:

the number of bytes read

Throws:

IOException - if an I/O exception occurs

Since:

1.2

receiveBlocking

public static <C extends ReadableMessageChannel> int receiveBlocking(C channel,
                                                                     ByteBuffer buffer,
                                                                     long time,
                                                                     TimeUnit unit)
                                                              throws IOException

Simple utility method to execute a blocking receive on a readable message channel with a timeout. This method blocks until the channel is readable, and then the message is received.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to read from

buffer - the buffer into which bytes are to be transferred

time - the amount of time to wait

unit - the unit of time to wait

Returns:

the number of bytes read

Throws:

IOException - if an I/O exception occurs

Since:

1.2

receiveBlocking

public static <C extends ReadableMessageChannel> long receiveBlocking(C channel,
                                                                      ByteBuffer[] buffers,
                                                                      int offs,
                                                                      int len)
                                                               throws IOException

Simple utility method to execute a blocking receive on a readable message channel. This method blocks until the channel is readable, and then the message is received.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to read from

buffers - the buffers into which bytes are to be transferred

offs - the first buffer to use

len - the number of buffers to use

Returns:

the number of bytes read

Throws:

IOException - if an I/O exception occurs

Since:

1.2

receiveBlocking

public static <C extends ReadableMessageChannel> long receiveBlocking(C channel,
                                                                      ByteBuffer[] buffers,
                                                                      int offs,
                                                                      int len,
                                                                      long time,
                                                                      TimeUnit unit)
                                                               throws IOException

Simple utility method to execute a blocking receive on a readable message channel with a timeout. This method blocks until the channel is readable, and then the message is received.

Type Parameters:

C - the channel type

Parameters:

channel - the channel to read from

buffers - the buffers into which bytes are to be transferred

offs - the first buffer to use

len - the number of buffers to use

time - the amount of time to wait

unit - the unit of time to wait

Returns:

the number of bytes read

Throws:

IOException - if an I/O exception occurs

Since:

1.2

acceptBlocking

public static <C extends ConnectedChannel,A extends AcceptingChannel<C>> C acceptBlocking(A channel)
                                                                                   throws IOException

Simple utility method to execute a blocking accept on an accepting channel. This method blocks until an accept is possible, and then returns the accepted connection.

Type Parameters:

C - the connection channel type

A - the accepting channel type

Parameters:

channel - the accepting channel

Returns:

the accepted channel

Throws:

IOException - if an I/O error occurs

Since:

3.0

acceptBlocking

public static <C extends ConnectedChannel,A extends AcceptingChannel<C>> C acceptBlocking(A channel,
                                                                                          long time,
                                                                                          TimeUnit unit)
                                                                                   throws IOException

Simple utility method to execute a blocking accept on an accepting channel, with a timeout. This method blocks until an accept is possible, and then returns the accepted connection.

Type Parameters:

C - the connection channel type

A - the accepting channel type

Parameters:

channel - the accepting channel

time - the amount of time to wait

unit - the unit of time to wait

Returns:

the accepted channel, or null if the timeout occurred before a connection was accepted

Throws:

IOException - if an I/O error occurs

Since:

3.0

transferBlocking

public static void transferBlocking(StreamSinkChannel destination,
                                    FileChannel source,
                                    long startPosition,
                                    long count)
                             throws IOException

Transfer bytes between two channels efficiently, blocking if necessary.

Parameters:

destination - the destination channel

source - the source file channel

startPosition - the start position in the source file

count - the number of bytes to transfer

Throws:

IOException - if an I/O error occurs

transferBlocking

public static void transferBlocking(FileChannel destination,
                                    StreamSourceChannel source,
                                    long startPosition,
                                    long count)
                             throws IOException

Transfer bytes between two channels efficiently, blocking if necessary.

Parameters:

destination - the destination file channel

source - the source channel

startPosition - the start position in the destination file

count - the number of bytes to transfer

Throws:

IOException - if an I/O error occurs

transferBlocking

public static long transferBlocking(StreamSinkChannel destination,
                                    StreamSourceChannel source,
                                    ByteBuffer throughBuffer,
                                    long count)
                             throws IOException

Transfer bytes between two channels efficiently, blocking if necessary.

Parameters:

destination - the destination channel

source - the source channel

throughBuffer - the buffer to transfer through,

count - the number of bytes to transfer

Returns:

the number of bytes actually transferred (will be fewer than count if EOF was reached)

Throws:

IOException - if the transfer fails

setCloseListener

public static <T extends CloseableChannel> void setCloseListener(T channel,
                                                                 ChannelListener<? super T> listener)

Set the close listener for a channel (type-safe).

Type Parameters:

T - the channel type

Parameters:

channel - the channel

listener - the listener to set

setAcceptListener

public static <T extends AcceptingChannel<?>> void setAcceptListener(T channel,
                                                                     ChannelListener<? super T> listener)

Set the accept listener for a channel (type-safe).

Type Parameters:

T - the channel type

Parameters:

channel - the channel

listener - the listener to set

setReadListener

public static <T extends SuspendableReadChannel> void setReadListener(T channel,
                                                                      ChannelListener<? super T> listener)

Set the read listener for a channel (type-safe).

Type Parameters:

T - the channel type

Parameters:

channel - the channel

listener - the listener to set

setWriteListener

public static <T extends SuspendableWriteChannel> void setWriteListener(T channel,
                                                                        ChannelListener<? super T> listener)

Set the write listener for a channel (type-safe).

Type Parameters:

T - the channel type

Parameters:

channel - the channel

listener - the listener to set

wrapByteChannel

public static ByteChannel wrapByteChannel(ByteChannel original)

Create a wrapper for a byte channel which does not expose other methods.

Parameters:

original - the original

Returns:

the wrapped channel

getOption

public static <T> T getOption(Configurable configurable,
                              Option<T> option,
                              T defaultValue)

Get an option value from a configurable target. If the method throws an exception then the default value is returned.

Type Parameters:

T - the option value type

Parameters:

configurable - the configurable target

option - the option

defaultValue - the default value

Returns:

the value

getOption

public static boolean getOption(Configurable configurable,
                                Option<Boolean> option,
                                boolean defaultValue)

Get an option value from a configurable target. If the method throws an exception then the default value is returned.

Parameters:

configurable - the configurable target

option - the option

defaultValue - the default value

Returns:

the value

getOption

public static int getOption(Configurable configurable,
                            Option<Integer> option,
                            int defaultValue)

Get an option value from a configurable target. If the method throws an exception then the default value is returned.

Parameters:

configurable - the configurable target

option - the option

defaultValue - the default value

Returns:

the value

getOption

public static long getOption(Configurable configurable,
                             Option<Long> option,
                             long defaultValue)

Get an option value from a configurable target. If the method throws an exception then the default value is returned.

Parameters:

configurable - the configurable target

option - the option

defaultValue - the default value

Returns:

the value

unwrap

public static <T extends Channel> T unwrap(Class<T> targetType,
                                           Channel channel)

Unwrap a nested channel type. If the channel does not wrap the target type, null is returned.

Type Parameters:

T - the type to unwrap

Parameters:

targetType - the class to unwrap

channel - the channel

Returns:

the unwrapped type, or null if the given type is not wrapped

See Also:

WrappedChannel

drain

public static long drain(StreamSourceChannel channel,
                         long count)
                  throws IOException

Attempt to drain the given number of bytes from the stream source channel.

Parameters:

channel - the channel to drain

count - the number of bytes

Returns:

the number of bytes drained, 0 if reading the channel would block, or -1 if the EOF was reached

Throws:

IOException - if an error occurs

drain

public static long drain(ReadableByteChannel channel,
                         long count)
                  throws IOException

Attempt to drain the given number of bytes from the readable byte channel.

Parameters:

channel - the channel to drain

count - the number of bytes

Returns:

the number of bytes drained, 0 if reading the channel would block, or -1 if the EOF was reached

Throws:

IOException - if an error occurs

drain

public static long drain(FileChannel channel,
                         long position,
                         long count)
                  throws IOException

Attempt to drain the given number of bytes from the file channel. This does nothing more than force a read of bytes in the file.

Parameters:

channel - the channel to drain

position - the position to drain from

count - the number of bytes

Returns:

the number of bytes drained, 0 if reading the channel would block, or -1 if the EOF was reached

Throws:

IOException - if an error occurs

resumeReadsAsync

public static void resumeReadsAsync(SuspendableReadChannel channel)

Resume reads asynchronously. Queues a task on the channel's I/O thread to resume. Note that if a channel has multiple threads associated with it, the results may not be desirable.

Parameters:

channel - the channel to resume

resumeWritesAsync

public static void resumeWritesAsync(SuspendableWriteChannel channel)

Resume writes asynchronously. Queues a task on the channel's I/O thread to resume. Note that if a channel has multiple threads associated with it, the results may not be desirable.

Parameters:

channel - the channel to resume

writeFinalBasic

public static int writeFinalBasic(StreamSinkChannel channel,
                                  ByteBuffer src)
                           throws IOException

Writes out the data in the buffer to the channel. If all the data is written out then the channel will have its writes shutdown.

Parameters:

channel - The channel

src - The buffer

Returns:

The number of bytes written

Throws:

IOException

writeFinalBasic

public static long writeFinalBasic(StreamSinkChannel channel,
                                   ByteBuffer[] srcs,
                                   int offset,
                                   int length)
                            throws IOException

Writes out the data in the buffer to the channel. If all the data is written out then the channel will have its writes shutdown.

Parameters:

channel - The channel

srcs - The buffers

offset - The offset into the srcs array

length - The number buffers to write

Returns:

The number of bytes written

Throws:

IOException