ChannelListeners (Red Hat JBoss Enterprise Application Platform 7.2.0.Beta public API)

java.lang.Object
- org.xnio.ChannelListeners

```
public final class ChannelListeners
extends Object
```
Channel listener utility methods.

Author:

David M. Lloyd

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static ChannelExceptionHandler<Channel>`	`closingChannelExceptionHandler()` Get a channel exception handler which closes the channel upon exception.
`static ChannelListener<Channel>`	`closingChannelListener()` Get a channel listener which closes the channel when notified.
`static <T extends Channel> ChannelListener<T>`	`closingChannelListener(ChannelListener<T> delegate, Closeable... resources)` Get a channel listener which closes the given resource when notified.
`static <T extends Channel> ChannelListener<T>`	`closingChannelListener(ChannelListener<T> delegate, Closeable resource)` Get a channel listener which closes the given resource when notified.
`static ChannelListener<Channel>`	`closingChannelListener(Closeable... resources)` Get a channel listener which closes the given resources when notified.
`static ChannelListener<Channel>`	`closingChannelListener(Closeable resource)` Get a channel listener which closes the given resource when notified.
`static <T extends Channel> ChannelListener<T>`	`delegatingChannelListener(ChannelListener<? super T> delegate)` A delegating channel listener which passes an event to another listener of the same or a super type.
`static <C extends Channel,T extends Channel> ChannelListener<C>`	`delegatingChannelListener(T channel, ChannelListener.SimpleSetter<T> setter)` A delegating channel listener which passes an event to the listener stored in the given setter.
`static <T extends StreamSourceChannel> ChannelListener<T>`	`drainListener(long bytes, ChannelListener<? super T> finishListener, ChannelExceptionHandler<? super T> exceptionHandler)` Create a channel listener which automatically drains the given number of bytes from the channel and then calls a listener.
`static <T extends Channel> ChannelListener<T>`	`executorChannelListener(ChannelListener<T> listener, Executor executor)` Get a channel listener which executes a delegate channel listener via an executor.
`static <T extends StreamSourceChannel> ChannelListener<T>`	`fileReceivingChannelListener(FileChannel target, long position, long count, ChannelListener<? super T> delegate, ChannelExceptionHandler<? super T> exceptionHandler)` A file-receiving channel listener.
`static <T extends StreamSinkChannel> ChannelListener<T>`	`fileSendingChannelListener(FileChannel source, long position, long count, ChannelListener<? super T> delegate, ChannelExceptionHandler<? super T> exceptionHandler)` A file-sending channel listener.
`static <T extends SuspendableWriteChannel> ChannelListener<T>`	`flushingChannelListener(ChannelListener<? super T> delegate, ChannelExceptionHandler<? super T> exceptionHandler)` A flushing channel listener.
`static <T extends Channel> Runnable`	`getChannelListenerTask(T channel, ChannelListener.SimpleSetter<T> setter)` Get a task which invokes the given channel listener on the given channel via its setter.
`static <T extends Channel> Runnable`	`getChannelListenerTask(T channel, ChannelListener<? super T> channelListener)` Get a task which invokes the given channel listener on the given channel.
`static <T extends Channel> ChannelListener.Setter<T>`	`getDelegatingSetter(ChannelListener.Setter<? extends Channel> target, T realChannel)` Get a channel listener setter which delegates to the given target setter with a different channel type.
`static <T extends Channel> ChannelListener.Setter<T>`	`getSetter(AtomicReference<ChannelListener<? super T>> atomicReference)` Get a setter based on an atomic reference.
`static <T extends Channel,C> ChannelListener.Setter<T>`	`getSetter(C channel, AtomicReferenceFieldUpdater<C,ChannelListener> updater)` Deprecated. Not recommended as a security manager will enforce unreasonable restrictions on the updater.
`static <I extends StreamSourceChannel,O extends StreamSinkChannel> void`	`initiateTransfer(I source, O sink, Pool<ByteBuffer> pool)` Initiate a low-copy transfer between two stream channels.
`static <I extends StreamSourceChannel,O extends StreamSinkChannel> void`	`initiateTransfer(long count, I source, O sink, ChannelListener<? super I> sourceListener, ChannelListener<? super O> sinkListener, ChannelExceptionHandler<? super I> readExceptionHandler, ChannelExceptionHandler<? super O> writeExceptionHandler, Pool<ByteBuffer> pool)` Initiate a low-copy transfer between two stream channels.
`static <T extends Channel> void`	`invokeChannelExceptionHandler(T channel, ChannelExceptionHandler<? super T> exceptionHandler, IOException exception)` Safely invoke a channel exception handler, logging any errors.
`static <T extends Channel> void`	`invokeChannelListener(Executor executor, T channel, ChannelListener<? super T> channelListener)` Invoke a channel listener on a given channel, logging any errors, using the given executor.
`static <T extends Channel> boolean`	`invokeChannelListener(T channel, ChannelListener<? super T> channelListener)` Invoke a channel listener on a given channel, logging any errors.
`static ChannelListener<Channel>`	`nullChannelListener()` Get a channel listener which does nothing.
`static <T extends Channel> ChannelListener.Setter<T>`	`nullSetter()` Get a channel listener setter which does nothing.
`static <C extends ConnectedChannel> ChannelListener<AcceptingChannel<C>>`	`openListenerAdapter(ChannelListener<? super C> openListener)` Create an open listener adapter which automatically accepts connections and invokes an open listener.
`static <T extends SuspendableReadChannel> ChannelListener<T>`	`readSuspendingChannelListener(ChannelListener<? super T> delegate)` A read-suspending channel listener.
`static <T extends WritableMessageChannel> ChannelListener<T>`	`sendingChannelListener(Pooled<ByteBuffer> pooled, ChannelListener<? super T> delegate, ChannelExceptionHandler<? super T> exceptionHandler)` A sending channel listener.
`static <T extends SuspendableWriteChannel> ChannelListener<T>`	`writeShutdownChannelListener(ChannelListener<? super T> delegate, ChannelExceptionHandler<? super T> exceptionHandler)` A write shutdown channel listener.
`static <T extends SuspendableWriteChannel> ChannelListener<T>`	`writeSuspendingChannelListener(ChannelListener<? super T> delegate)` A write-suspending channel listener.
`static <T extends StreamSinkChannel> ChannelListener<T>`	`writingChannelListener(Pooled<ByteBuffer> pooled, ChannelListener<? super T> delegate, ChannelExceptionHandler<? super T> exceptionHandler)` A writing channel listener.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

invokeChannelListener
```
public static <T extends Channel> boolean invokeChannelListener(T channel,
                                                                ChannelListener<? super T> channelListener)
```
Invoke a channel listener on a given channel, logging any errors.

Type Parameters:

T - the channel type

Parameters:

channel - the channel

channelListener - the channel listener

Returns:

true if the listener completed successfully, or false if it failed

invokeChannelListener

public static <T extends Channel> void invokeChannelListener(Executor executor,
                                                             T channel,
                                                             ChannelListener<? super T> channelListener)

Invoke a channel listener on a given channel, logging any errors, using the given executor.

Type Parameters:: T - the channel type
Parameters:: executor - the executor; channel - the channel; channelListener - the channel listener

invokeChannelExceptionHandler

public static <T extends Channel> void invokeChannelExceptionHandler(T channel,
                                                                     ChannelExceptionHandler<? super T> exceptionHandler,
                                                                     IOException exception)

Safely invoke a channel exception handler, logging any errors.

Type Parameters:: T - the exception type
Parameters:: channel - the channel; exceptionHandler - the exception handler; exception - the exception to pass in

getChannelListenerTask

public static <T extends Channel> Runnable getChannelListenerTask(T channel,
                                                                  ChannelListener<? super T> channelListener)

Get a task which invokes the given channel listener on the given channel.

Type Parameters:: T - the channel type
Parameters:: channel - the channel; channelListener - the channel listener
Returns:: the runnable task

getChannelListenerTask

public static <T extends Channel> Runnable getChannelListenerTask(T channel,
                                                                  ChannelListener.SimpleSetter<T> setter)

Get a task which invokes the given channel listener on the given channel via its setter.

Type Parameters:: T - the channel type
Parameters:: channel - the channel; setter - the setter for the channel listener
Returns:: the runnable task

closingChannelListener
```
public static ChannelListener<Channel> closingChannelListener()
```
Get a channel listener which closes the channel when notified.

Returns:

the channel listener

closingChannelListener
```
public static ChannelListener<Channel> closingChannelListener(Closeable resource)
```
Get a channel listener which closes the given resource when notified.

Parameters:

resource - the resource to close

Returns:

the channel listener

closingChannelListener
```
public static ChannelListener<Channel> closingChannelListener(Closeable... resources)
```
Get a channel listener which closes the given resources when notified.

Parameters:

resources - the resources to close

Returns:

the channel listener

closingChannelListener

public static <T extends Channel> ChannelListener<T> closingChannelListener(ChannelListener<T> delegate,
                                                                            Closeable resource)

Get a channel listener which closes the given resource when notified.

Parameters:: delegate - the listener to call next; resource - the resource to close
Returns:: the channel listener

closingChannelListener

public static <T extends Channel> ChannelListener<T> closingChannelListener(ChannelListener<T> delegate,
                                                                            Closeable... resources)

Get a channel listener which closes the given resource when notified.

Parameters:: delegate - the listener to call next; resources - the resource to close
Returns:: the channel listener

nullChannelListener
```
public static ChannelListener<Channel> nullChannelListener()
```
Get a channel listener which does nothing.

Returns:

the null channel listener

closingChannelExceptionHandler
```
public static ChannelExceptionHandler<Channel> closingChannelExceptionHandler()
```
Get a channel exception handler which closes the channel upon exception.

Returns:

the channel exception handler

openListenerAdapter
```
public static <C extends ConnectedChannel> ChannelListener<AcceptingChannel<C>> openListenerAdapter(ChannelListener<? super C> openListener)
```
Create an open listener adapter which automatically accepts connections and invokes an open listener.

Type Parameters:

C - the connected channel type

Parameters:

openListener - the channel open listener

Returns:

a channel accept listener

getSetter
```
@Deprecated
public static <T extends Channel,C> ChannelListener.Setter<T> getSetter(C channel,
                                                                                    AtomicReferenceFieldUpdater<C,ChannelListener> updater)
```
Deprecated. Not recommended as a security manager will enforce unreasonable restrictions on the updater.

Get a setter based on an atomic reference field updater. Used by channel implementations to avoid having to define an anonymous class for each listener field.

Type Parameters:

T - the channel type

C - the holding class

Parameters:

channel - the channel

updater - the updater

Returns:

the setter

getSetter
```
public static <T extends Channel> ChannelListener.Setter<T> getSetter(AtomicReference<ChannelListener<? super T>> atomicReference)
```
Get a setter based on an atomic reference. Used by channel implementations to avoid having to define an anonymous class for each listener field.

Type Parameters:

T - the channel type

Parameters:

atomicReference - the atomic reference

Returns:

the setter

getDelegatingSetter
```
public static <T extends Channel> ChannelListener.Setter<T> getDelegatingSetter(ChannelListener.Setter<? extends Channel> target,
                                                                                T realChannel)
```
Get a channel listener setter which delegates to the given target setter with a different channel type.

Type Parameters:

T - the real channel type

Parameters:

target - the target setter

realChannel - the channel to send in to the listener

Returns:

the delegating setter

nullSetter
```
public static <T extends Channel> ChannelListener.Setter<T> nullSetter()
```
Get a channel listener setter which does nothing.

Type Parameters:

T - the channel type

Returns:

a setter which does nothing

executorChannelListener
```
public static <T extends Channel> ChannelListener<T> executorChannelListener(ChannelListener<T> listener,
                                                                             Executor executor)
```
Get a channel listener which executes a delegate channel listener via an executor. If an exception occurs submitting the task, the associated channel is closed.

Type Parameters:

T - the channel type

Parameters:

listener - the listener to invoke

executor - the executor with which to invoke the listener

Returns:

a delegating channel listener

flushingChannelListener
```
public static <T extends SuspendableWriteChannel> ChannelListener<T> flushingChannelListener(ChannelListener<? super T> delegate,
                                                                                             ChannelExceptionHandler<? super T> exceptionHandler)
```
A flushing channel listener. Flushes the channel and then calls the delegate listener. Calls the exception handler if an exception occurs. The delegate listener should ensure that the channel write listener is appropriately set.
The returned listener is stateless and may be reused on any number of channels concurrently or sequentially.

Type Parameters:

T - the channel type

Parameters:

delegate - the delegate listener

exceptionHandler - the exception handler

Returns:

the flushing channel listener

writeShutdownChannelListener
```
public static <T extends SuspendableWriteChannel> ChannelListener<T> writeShutdownChannelListener(ChannelListener<? super T> delegate,
                                                                                                  ChannelExceptionHandler<? super T> exceptionHandler)
```
A write shutdown channel listener. Shuts down and flushes the channel and calls the delegate listener. Calls the exception handler if an exception occurs. When the delegate listener is called, the channel's write side will be shut down and flushed. The delegate listener should ensure that the channel write listener is appropriately set.

Type Parameters:

T - the channel type

Parameters:

delegate - the delegate listener

exceptionHandler - the exception handler

Returns:

the channel listener

writingChannelListener

public static <T extends StreamSinkChannel> ChannelListener<T> writingChannelListener(Pooled<ByteBuffer> pooled,
                                                                                      ChannelListener<? super T> delegate,
                                                                                      ChannelExceptionHandler<? super T> exceptionHandler)

A writing channel listener. Writes the buffer to the channel and then calls the delegate listener. Calls the exception handler if an exception occurs. The delegate listener should ensure that the channel write listener is appropriately set.

The returned listener is stateful and will not execute properly if reused.

Type Parameters:: T - the channel type
Parameters:: pooled - the buffer to write; delegate - the delegate listener; exceptionHandler - the exception handler
Returns:: the writing channel listener

sendingChannelListener

public static <T extends WritableMessageChannel> ChannelListener<T> sendingChannelListener(Pooled<ByteBuffer> pooled,
                                                                                           ChannelListener<? super T> delegate,
                                                                                           ChannelExceptionHandler<? super T> exceptionHandler)

A sending channel listener. Writes the buffer to the channel and then calls the delegate listener. Calls the exception handler if an exception occurs. The delegate listener should ensure that the channel write listener is appropriately set.

The returned listener is stateful and will not execute properly if reused.

Type Parameters:: T - the channel type
Parameters:: pooled - the buffer to send; delegate - the delegate listener; exceptionHandler - the exception handler
Returns:: the sending channel listener

fileSendingChannelListener

public static <T extends StreamSinkChannel> ChannelListener<T> fileSendingChannelListener(FileChannel source,
                                                                                          long position,
                                                                                          long count,
                                                                                          ChannelListener<? super T> delegate,
                                                                                          ChannelExceptionHandler<? super T> exceptionHandler)

A file-sending channel listener. Writes the file to the channel and then calls the delegate listener. Calls the exception handler if an exception occurs. The delegate listener should ensure that the channel write listener is appropriately set.

The returned listener is stateful and will not execute properly if reused.

Type Parameters:: T - the channel type
Parameters:: source - the file to read from; position - the position in the source file to read from; count - the number of bytes to read; delegate - the listener to call when the file is sent; exceptionHandler - the exception handler to call if a problem occurs
Returns:: the channel listener

fileReceivingChannelListener

public static <T extends StreamSourceChannel> ChannelListener<T> fileReceivingChannelListener(FileChannel target,
                                                                                              long position,
                                                                                              long count,
                                                                                              ChannelListener<? super T> delegate,
                                                                                              ChannelExceptionHandler<? super T> exceptionHandler)

A file-receiving channel listener. Writes the file from the channel and then calls the delegate listener. Calls the exception handler if an exception occurs. The delegate listener should ensure that the channel read listener is appropriately set.

The returned listener is stateful and will not execute properly if reused.

Type Parameters:: T - the channel type
Parameters:: target - the file to write to; position - the position in the target file to write to; count - the number of bytes to write; delegate - the listener to call when the file is sent; exceptionHandler - the exception handler to call if a problem occurs
Returns:: the channel listener

delegatingChannelListener
```
public static <T extends Channel> ChannelListener<T> delegatingChannelListener(ChannelListener<? super T> delegate)
```
A delegating channel listener which passes an event to another listener of the same or a super type.

Type Parameters:

T - the channel type

Parameters:

delegate - the delegate channel listener

Returns:

the listener

delegatingChannelListener

public static <C extends Channel,T extends Channel> ChannelListener<C> delegatingChannelListener(T channel,
                                                                                                 ChannelListener.SimpleSetter<T> setter)

A delegating channel listener which passes an event to the listener stored in the given setter.

Type Parameters:: C - the listener channel type; T - the passed in channel type
Parameters:: channel - the channel to pass in; setter - the channel listener setter
Returns:: the listener

writeSuspendingChannelListener
```
public static <T extends SuspendableWriteChannel> ChannelListener<T> writeSuspendingChannelListener(ChannelListener<? super T> delegate)
```
A write-suspending channel listener. The returned listener will suspend writes when called. Useful for chaining writing listeners to a flush listener to this listener. The delegate listener should ensure that the channel write listener is appropriately set.

Parameters:

delegate - the delegate channel listener

Returns:

the suspending channel listener

readSuspendingChannelListener
```
public static <T extends SuspendableReadChannel> ChannelListener<T> readSuspendingChannelListener(ChannelListener<? super T> delegate)
```
A read-suspending channel listener. The returned listener will suspend read when called. The delegate listener should ensure that the channel read listener is appropriately set.

Parameters:

delegate - the delegate channel listener

Returns:

the suspending channel listener

initiateTransfer

public static <I extends StreamSourceChannel,O extends StreamSinkChannel> void initiateTransfer(I source,
                                                                                                O sink,
                                                                                                Pool<ByteBuffer> pool)

Initiate a low-copy transfer between two stream channels. The pool should be a direct buffer pool for best performance. The channels will be closed when the transfer completes or if there is an error.

Type Parameters:: I - the source stream type; O - the sink stream type
Parameters:: source - the source channel; sink - the target channel; pool - the pool from which the transfer buffer should be allocated

initiateTransfer

public static <I extends StreamSourceChannel,O extends StreamSinkChannel> void initiateTransfer(long count,
                                                                                                I source,
                                                                                                O sink,
                                                                                                ChannelListener<? super I> sourceListener,
                                                                                                ChannelListener<? super O> sinkListener,
                                                                                                ChannelExceptionHandler<? super I> readExceptionHandler,
                                                                                                ChannelExceptionHandler<? super O> writeExceptionHandler,
                                                                                                Pool<ByteBuffer> pool)

Initiate a low-copy transfer between two stream channels. The pool should be a direct buffer pool for best performance.

Parameters:: count - the number of bytes to transfer, or Long.MAX_VALUE to transfer all remaining bytes; source - the source channel; sink - the target channel; sourceListener - the source listener to set and call when the transfer is complete, or null to clear the listener at that time; sinkListener - the target listener to set and call when the transfer is complete, or null to clear the listener at that time; readExceptionHandler - the read exception handler to call if an error occurs during a read operation; writeExceptionHandler - the write exception handler to call if an error occurs during a write operation; pool - the pool from which the transfer buffer should be allocated

drainListener

public static <T extends StreamSourceChannel> ChannelListener<T> drainListener(long bytes,
                                                                               ChannelListener<? super T> finishListener,
                                                                               ChannelExceptionHandler<? super T> exceptionHandler)

Create a channel listener which automatically drains the given number of bytes from the channel and then calls a listener.

Type Parameters:: T - the channel type
Parameters:: bytes - the number of bytes to drain, or Long.MAX_VALUE to drain the channel completely; finishListener - the listener to call when the drain is complete; exceptionHandler - the handler to call if the drain fails
Returns:: the channel listener

Class ChannelListeners

Method Summary

Methods inherited from class java.lang.Object

Method Detail

invokeChannelListener

invokeChannelListener

invokeChannelExceptionHandler

getChannelListenerTask

getChannelListenerTask

closingChannelListener

closingChannelListener

closingChannelListener

closingChannelListener

closingChannelListener

nullChannelListener

closingChannelExceptionHandler

openListenerAdapter

getSetter

getSetter

getDelegatingSetter

nullSetter

executorChannelListener

flushingChannelListener

writeShutdownChannelListener

writingChannelListener

sendingChannelListener

fileSendingChannelListener

fileReceivingChannelListener

delegatingChannelListener

delegatingChannelListener

writeSuspendingChannelListener

readSuspendingChannelListener

initiateTransfer

initiateTransfer

drainListener