NIOMultiplexor.java

package org.limewire.nio.channel;


/**
 * Defines the interface of a class that can handle delegating 
 * <code>ChannelReadObserver</code> or <code>ChannelWriter</code> events to 
 * other <code>ChannelReadObservers</code> or <code>ChannelWriters</code>.
 */
public interface NIOMultiplexor {
    
    /**
     * Sets the new <code>ReadObserver</code>. A <code>ChannelReadObserver</code> 
     * is required so that the multiplexor can set the appropriate source channel
     * for reading. The source channel is set on the deepest 
     * <code>ChannelReader</code> in the chain. For example, given the chain:
     * <pre>
     *      ChannelReadObserver a = new ProtocolReader();
     *      ChannelReader b = new DeObfuscator();
     *      ChannelReader c = new DataInflater();
     *      a.setReadChannel(b);
     *      b.setReadChannel(c);
     *      setReadObserver(a);
     *      
     * the deepest ChannelReader is 'c', so the muliplexor would call
     *
     *      c.setReadChannel(ultimateSource);
     *
     * The deepest ChannelReader is found with code equivalent to:
     *
     *      ChannelReader deepest = initial;
     *      while(deepest.getReadChannel() instanceof ChannelReader)
     *          deepest = (ChannelReader)deepest.getReadChannel();
     *  </pre>
     */
    public void setReadObserver(ChannelReadObserver reader);
    
    /**
     * Sets the new <code>ChannelWriter</code>. A <code>ChannelWriter</code> is 
     * necessary (instead of a <code>WriteObserver</code>) because the actual 
     * <code>WriteObserver</code> that listens for write events from the 
     * ultimate source will be installed at the deepest
     * <code>InterestWriteChannel</code> in the chain. For example, given the chain:
     * <pre>
     *      ChannelWriter a = new ProtocolWriter();
     *      ChannelWriter b = new Obfuscator();
     *      ChannelWriter c = new DataDeflater();
     *      a.setWriteChannel(b);
     *      b.setWriteChannel(c);
     *      setWriteObserver(a);
     *      
     * the deepest ChannelWriter is 'c', so the multiplexor would call
     *      c.setWriteChannel(networkSink);
     * where networkSink is the network channel from where data is actually read.
     * 
     * The deepest ChannelWriter is found with code equivalent to:
     * 
     *      ChannelWriter deepest = initial;
     *      while(deepest.getWriteChannel() instanceof ChannelWriter)
     *          deepest = (ChannelWriter)deepest.getWriteChannel();
     *
     * </pre>
     * When write events are generated, <code>ultimateSource.handleWrite</code> 
     * will forward the event to the last channel that was interested in it ('c'),
     * which will cause 'c' to either write data immediately or forward the event
     * to 'b', etc.
     */
    public void setWriteObserver(ChannelWriter writer);
}