Package org.xnio.channels

# Class FixedLengthStreamSourceChannel

java.lang.Object
org.xnio.channels.FixedLengthStreamSourceChannel

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`, `Channel`, `InterruptibleChannel`, `ReadableByteChannel`, `ScatteringByteChannel`, `CloseableChannel`, `CloseListenerSettable<FixedLengthStreamSourceChannel>`, `Configurable`, `ProtectedWrappedChannel<StreamSourceChannel>`, `ReadListenerSettable<FixedLengthStreamSourceChannel>`, `StreamSourceChannel`, `SuspendableReadChannel`

public final class FixedLengthStreamSourceChannel extends Object implements StreamSourceChannel, ProtectedWrappedChannel<StreamSourceChannel>, ReadListenerSettable<FixedLengthStreamSourceChannel>, CloseListenerSettable<FixedLengthStreamSourceChannel>
A channel which reads data of a fixed length and calls a finish listener. When the finish listener is called, it should examine the result of `getRemaining()` to see if more bytes were pending when the channel was closed.

Author:
  David M. Lloyd

## Nested Class Summary

## Nested classes/interfaces inherited from interface org.xnio.channels.CloseListenerSettable

`CloseListenerSettable.Setter<C extends Channel>`

## Nested classes/interfaces inherited from interface org.xnio.channels.ReadListenerSettable

`ReadListenerSettable.Setter<C extends Channel>`

## Field Summary

### Fields inherited from interface org.xnio.channels.Configurable

`EMPTY`

## Constructor Summary

Constructors
Constructor
Description
`FixedLengthStreamSourceChannel(StreamSourceChannel delegate, long contentLength, boolean configurable, boolean propagateClose, ChannelListener<? super FixedLengthStreamSourceChannel> finishListener, Object guard)`
Construct a new instance.
`FixedLengthStreamSourceChannel(StreamSourceChannel delegate, long contentLength, boolean configurable, ChannelListener<? super FixedLengthStreamSourceChannel> finishListener, Object guard)`
Construct a new instance.
`FixedLengthStreamSourceChannel(StreamSourceChannel delegate, long contentLength, ChannelListener<? super FixedLengthStreamSourceChannel> finishListener, Object guard)`
Construct a new instance.

## Method Summary

Modifier and Type
Method
Description
`void`
`awaitReadable()`
Block until this channel becomes readable again.
`void`
`awaitReadable(long time, TimeUnit timeUnit)`
Block until this channel becomes readable again, or until the timeout expires.
`void`
`close()`
Close this channel.
`StreamSourceChannel`
`getChannel(Object guard)`
Get the channel which is wrapped by this object, or `null` if the guard is invalid.
`ChannelListener<? super FixedLengthStreamSourceChannel>`
`getCloseListener()`
Get the close listener.
`ChannelListener.Setter<FixedLengthStreamSourceChannel>`
`getCloseSetter()`
Get the setter which can be used to change the close listener for this channel.
`XnioIoThread`
`getIoThread()`
Get the I/O thread associated with this channel.
`<T> T`
`getOption(Option<T> option)`
Get the value of a channel option.
`ChannelListener<? super FixedLengthStreamSourceChannel>`
`getReadListener()`
Get the read listener.
`ChannelListener.Setter<FixedLengthStreamSourceChannel>`
`getReadSetter()`
Get the setter which can be used to change the read listener for this channel.
`XnioExecutor`
`getReadThread()`
Deprecated.
`long`
`getRemaining()`
Get the number of remaining bytes.
`XnioWorker`
`getWorker()`
Get the worker for this channel.
`boolean`
`isOpen()`
`boolean`
`isReadResumed()`
Determine whether reads are resumed.
`int`
`read(ByteBuffer dst)`
`long`
`read(ByteBuffer[] dsts)`
`long`
`read(ByteBuffer[] dsts, int offset, int length)`
`void`
`resumeReads()`
Resume reads on this channel.
`void`
`setCloseListener(ChannelListener<? super FixedLengthStreamSourceChannel> closeListener)`
Set the close listener.
`<T> T`
`setOption(Option<T> option, T value)`
Set an option for this channel.
`void`
`setReadListener(ChannelListener<? super FixedLengthStreamSourceChannel> readListener)`
Set the read listener.
`void`
`shutdownReads()`
Places this readable channel at "end of stream".
`boolean`
`supportsOption(Option<?> option)`
Determine whether an option is supported on this channel.
`void`
`suspendReads()`
Suspend further read notifications on this channel.
`long`
`transferTo(long position, long count, FileChannel target)`
Transfers bytes into the given file from this channel.
`long`
`transferTo(long count, ByteBuffer throughBuffer, StreamSinkChannel target)`
Transfers bytes into the given channel target.
`void`
`wakeupReads()`
`Resume reads` on this channel, and force the read listener to be triggered even if the channel isn't actually readable.

### Methods inherited from class java.lang.Object

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

## Constructor Details

### FixedLengthStreamSourceChannel

public FixedLengthStreamSourceChannel(StreamSourceChannel delegate, long contentLength, ChannelListener<? super FixedLengthStreamSourceChannel> finishListener, Object guard)
Construct a new instance. The given listener is called once all the bytes are read from the stream or the stream is closed. This listener should cause the remaining data to be drained from the underlying stream via the
invalid reference

    #drain()

method if the underlying stream is to be reused.

Calling this constructor will replace the read listener of the underlying channel. The listener should be restored from the `finishListener` object. The underlying stream should not be closed while this wrapper stream is active.

Parameters:
  `delegate` - the stream source channel to read from
  `contentLength` - the amount of content to read
  `finishListener` - the listener to call once the stream is exhausted or closed
  `guard` - the guard object to use

### FixedLengthStreamSourceChannel

public FixedLengthStreamSourceChannel(StreamSourceChannel delegate, long contentLength, boolean configurable, ChannelListener<? super FixedLengthStreamSourceChannel> finishListener, Object guard)
Construct a new instance. The given listener is called once all the bytes are read from the stream or the stream is closed. This listener should cause the remaining data to be drained from the underlying stream via the
invalid reference

    #drain()

method if the underlying stream is to be reused.

Calling this constructor will replace the read listener of the underlying channel. The listener should be restored from the `finishListener` object. The underlying stream should not be closed while this wrapper stream is active.

Parameters:
  `delegate` - the stream source channel to read from
  `contentLength` - the amount of content to read
  `configurable` - `true` to allow options to pass through to the delegate, `false` otherwise
  `finishListener` - the listener to call once the stream is exhausted or closed
  `guard` - the guard object to use

### FixedLengthStreamSourceChannel

public FixedLengthStreamSourceChannel(StreamSourceChannel delegate, long contentLength, boolean configurable, boolean propagateClose, ChannelListener<? super FixedLengthStreamSourceChannel> finishListener, Object guard)
Construct a new instance. The given listener is called once all the bytes are read from the stream or the stream is closed. This listener should cause the remaining data to be drained from the underlying stream via the
invalid reference

    #drain()

method if the underlying stream is to be reused.

Calling this constructor will replace the read listener of the underlying channel. The listener should be restored from the `finishListener` object. The underlying stream should not be closed while this wrapper stream is active.

Parameters:
  `delegate` - the stream source channel to read from
  `contentLength` - the amount of content to read
  `configurable` - `true` to allow options to pass through to the delegate, `false` otherwise
  `propagateClose` - `true` to propagate close/shutdown to the delegate, `false` otherwise
  `finishListener` - the listener to call once the stream is exhausted or closed
  `guard` - the guard object to use

## Method Details

### setReadListener

public void setReadListener(ChannelListener<? super FixedLengthStreamSourceChannel> readListener)
Description copied from interface: `ReadListenerSettable`
Set the read listener.

Specified by:
  `setReadListener` in interface `ReadListenerSettable<FixedLengthStreamSourceChannel>`
Parameters:
  `readListener` - the read listener

### getReadListener

public ChannelListener<? super FixedLengthStreamSourceChannel> getReadListener()
Description copied from interface: `ReadListenerSettable`
Get the read listener.

Specified by:
  `getReadListener` in interface `ReadListenerSettable<FixedLengthStreamSourceChannel>`
Returns:
  the read listener

### setCloseListener

public void setCloseListener(ChannelListener<? super FixedLengthStreamSourceChannel> closeListener)
Description copied from interface: `CloseListenerSettable`
Set the close listener.

Specified by:
  `setCloseListener` in interface `CloseListenerSettable<FixedLengthStreamSourceChannel>`
Parameters:
  `closeListener` - the close listener

### getCloseListener

public ChannelListener<? super FixedLengthStreamSourceChannel> getCloseListener()
Description copied from interface: `CloseListenerSettable`
Get the close listener.

Specified by:
  `getCloseListener` in interface `CloseListenerSettable<FixedLengthStreamSourceChannel>`
Returns:
  the close listener

### getReadSetter

public ChannelListener.Setter<FixedLengthStreamSourceChannel> getReadSetter()
Description copied from interface: `StreamSourceChannel`
Get the setter which can be used to change the read listener for this channel.

Specified by:
  `getReadSetter` in interface `StreamSourceChannel`
Specified by:
  `getReadSetter` in interface `SuspendableReadChannel`
Returns:
  the setter

### getCloseSetter

public ChannelListener.Setter<FixedLengthStreamSourceChannel> getCloseSetter()
Description copied from interface: `StreamSourceChannel`
Get the setter which can be used to change the close listener for this channel. If the channel is already closed, then the listener will not be called.

Specified by:
  `getCloseSetter` in interface `CloseableChannel`
Specified by:
  `getCloseSetter` in interface `StreamSourceChannel`
Specified by:
  `getCloseSetter` in interface `SuspendableReadChannel`
Returns:
  the setter

### transferTo

public long transferTo(long position, long count, FileChannel target) throws IOException
Description copied from interface: `StreamSourceChannel`
Transfers bytes into the given file from this channel. Using this method in preference to `FileChannel.transferFrom(ReadableByteChannel, long, long)` may provide a performance advantage on some platforms.

If the current thread is interrupted when this method is called, it may throw a `InterruptedIOException`; however, if this exception is thrown, the `InterruptedIOException.bytesTransferred` field is guaranteed to be 0.

Specified by:
  `transferTo` in interface `StreamSourceChannel`
Parameters:
  `position` - the position within the file from which the transfer is to begin
  `count` - the number of bytes to be transferred
  `target` - the file to write to
Returns:
  the number of bytes (possibly 0) that were actually transferred
Throws:
  `IOException` - if an I/O error occurs

### transferTo

public long transferTo(long count, ByteBuffer throughBuffer, StreamSinkChannel target) throws IOException
Description copied from interface: `StreamSourceChannel`
Transfers bytes into the given channel target. On some platforms, this may avoid copying bytes between user and kernel space. On other platforms, bytes are passed through the `throughBuffer` parameter's buffer space. On entry, `throughBuffer` will be cleared. On exit, the buffer will be flipped for emptying, and may possibly be empty or may contain data. If this method returns a value less than `count`, then the remaining data in `throughBuffer` may contain data read from this channel which must be written to `target` to complete the operation. Note that using a direct buffer may provide an intermediate performance gain on platforms without zero-copy facilities.

If the current thread is interrupted when this method is called, it may throw a `InterruptedIOException`; however, if this exception is thrown, the `InterruptedIOException.bytesTransferred` field is guaranteed to be 0. Note that the return value is the amount of data that was actually transferred to the `StreamSinkChannel`. The actual amount of data read could be larger than this, and can be calculated by adding the return value and the amount of data left in `throughBuffer`.

Specified by:
  `transferTo` in interface `StreamSourceChannel`
Parameters:
  `count` - the number of bytes to be transferred
  `throughBuffer` - the buffer to copy through.
  `target` - the destination to write to
Returns:
  the number of bytes (possibly 0) that were actually transferred, or -1 if the end of input was reached
Throws:
  `IOException` - if an I/O error occurs

### read

public long read(ByteBuffer[] dsts, int offset, int length) throws IOException

Specified by:
  `read` in interface `ScatteringByteChannel`
Throws:
  `IOException`

### read

public long read(ByteBuffer[] dsts) throws IOException

Specified by:
  `read` in interface `ScatteringByteChannel`
Throws:
  `IOException`

### read

public int read(ByteBuffer dst) throws IOException

Specified by:
  `read` in interface `ReadableByteChannel`
Throws:
  `IOException`

### suspendReads

public void suspendReads()
Description copied from interface: `SuspendableReadChannel`
Suspend further read notifications on this channel.

Specified by:
  `suspendReads` in interface `SuspendableReadChannel`

### resumeReads

public void resumeReads()
Description copied from interface: `SuspendableReadChannel`
Resume reads on this channel. The read listener will be called as soon as there is data available to be read.

Specified by:
  `resumeReads` in interface `SuspendableReadChannel`

### isReadResumed

public boolean isReadResumed()
Description copied from interface: `SuspendableReadChannel`
Determine whether reads are resumed.

Specified by:
  `isReadResumed` in interface `SuspendableReadChannel`
Returns:
  `true` if reads are resumed, `false` if reads are suspended

### wakeupReads

public void wakeupReads()
Description copied from interface: `SuspendableReadChannel`
`Resume reads` on this channel, and force the read listener to be triggered even if the channel isn't actually readable.

Specified by:
  `wakeupReads` in interface `SuspendableReadChannel`

### shutdownReads

public void shutdownReads() throws IOException
Description copied from interface: `SuspendableReadChannel`
Places this readable channel at "end of stream". Further reads will result in EOF. Shutting down all directions of a channel will cause `CloseableChannel.close()` to be called automatically.

Specified by:
  `shutdownReads` in interface `SuspendableReadChannel`
Throws:
  `IOException` - if an I/O error occurs

### awaitReadable

public void awaitReadable() throws IOException
Description copied from interface: `SuspendableReadChannel`
Block until this channel becomes readable again. This method may return spuriously before the channel becomes readable.

Specified by:
  `awaitReadable` in interface `SuspendableReadChannel`
Throws:
  `IOException` - if an I/O error occurs

### awaitReadable

public void awaitReadable(long time, TimeUnit timeUnit) throws IOException
Description copied from interface: `SuspendableReadChannel`
Block until this channel becomes readable again, or until the timeout expires. This method may return spuriously before the channel becomes readable or the timeout expires.

Specified by:
  `awaitReadable` in interface `SuspendableReadChannel`
Parameters:
  `time` - the time to wait
  `timeUnit` - the time unit
Throws:
  `IOException` - if an I/O error occurs

### getReadThread

@Deprecated public XnioExecutor getReadThread()
Deprecated.
Description copied from interface: `SuspendableReadChannel`
Get the read thread for this channel.

Specified by:
  `getReadThread` in interface `SuspendableReadChannel`
Returns:
  the thread, or `null` if none is configured or available

### getIoThread

public XnioIoThread getIoThread()
Description copied from interface: `CloseableChannel`
Get the I/O thread associated with this channel.

Specified by:
  `getIoThread` in interface `CloseableChannel`
Returns:
  the I/O thread associated with this channel

### getWorker

public XnioWorker getWorker()
Description copied from interface: `CloseableChannel`
Get the worker for this channel.

Specified by:
  `getWorker` in interface `CloseableChannel`
Returns:
  the worker

### isOpen

public boolean isOpen()

Specified by:
  `isOpen` in interface `Channel`

### close

public void close() throws IOException
Description copied from interface: `CloseableChannel`
Close this channel. When a channel is closed, its close listener is invoked. Invoking this method more than once has no additional effect.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Channel`
Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in interface `CloseableChannel`
Specified by:
  `close` in interface `InterruptibleChannel`
Throws:
  `IOException` - if the close failed

### supportsOption

public boolean supportsOption(Option<?> option)
Description copied from interface: `Configurable`
Determine whether an option is supported on this channel.

Specified by:
  `supportsOption` in interface `Configurable`
Parameters:
  `option` - the option
Returns:
  `true` if it is supported

### getOption

public <T> T getOption(Option<T> option) throws IOException
Description copied from interface: `Configurable`
Get the value of a channel option.

Specified by:
  `getOption` in interface `Configurable`
Type Parameters:
  `T` - the type of the option value
Parameters:
  `option` - the option to get
Returns:
  the value of the option, or `null` if it is not set
Throws:
  `IOException` - if an I/O error occurred when reading the option

### setOption

public <T> T setOption(Option<T> option, T value) throws IllegalArgumentException, IOException
Description copied from interface: `Configurable`
Set an option for this channel. Unsupported options are ignored.

Specified by:
  `setOption` in interface `Configurable`
Type Parameters:
  `T` - the type of the option value
Parameters:
  `option` - the option to set
  `value` - the value of the option to set
Returns:
  the previous option value, if any
Throws:
  `IllegalArgumentException` - if the value is not acceptable for this option
  `IOException` - if an I/O error occurred when modifying the option

### getChannel

public StreamSourceChannel getChannel(Object guard)
Description copied from interface: `ProtectedWrappedChannel`
Get the channel which is wrapped by this object, or `null` if the guard is invalid.

Specified by:
  `getChannel` in interface `ProtectedWrappedChannel<StreamSourceChannel>`
Parameters:
  `guard` - the guard object
Returns:
  the wrapped channel

### getRemaining

public long getRemaining()
Get the number of remaining bytes.

Returns:
  the number of remaining bytes