Module 

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 Details

    • 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
    • flushBlocking

      public static boolean flushBlocking(SuspendableWriteChannel channel, long time, TimeUnit unit) 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 or the timeout is reached.
      Parameters:
      channel - the writable channel
      time - the amount of time to wait
      unit - the unit of time to wait
      Returns:
      true if the channel was successfully flushed, false if the timeout was reached
      Throws:
      IOException - if an I/O exception occurs
      Since:
      3.8
    • 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
    • shutdownWritesBlocking

      public static boolean shutdownWritesBlocking(SuspendableWriteChannel channel, long time, TimeUnit unit) 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 or the timeout is reached.
      Parameters:
      channel - the writable channel
      time - the amount of time to wait
      unit - the unit of time to wait
      Returns:
      true if the channel was successfully flushed, false if the timeout was reached
      Throws:
      IOException - if an I/O exception occurs
      Since:
      3.8
    • 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:
    • 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