## com.sun.grizzly
Class Controller

    java.lang.Object
      com.sun.grizzly.Controller

All Implemented Interfaces:
  ConnectorHandlerPool, Lifecycle, AttributeHolder, Copyable, SupportStateHolder<State>, Runnable

Direct Known Subclasses:
  ReadController

    public class Controller

extends Object
implements Runnable, Lifecycle, Copyable, ConnectorHandlerPool, AttributeHolder, SupportStateHolder<State>

Main entry point when using the Grizzly Framework. A Controller is composed of Handlers, ProtocolChain and Pipeline. All of those components are configurable by client using the Grizzly Framework.

A Pipeline is a wrapper around a Thread pool.

A ProtocolChain implement the "Chain of Responsibility" pattern (for more info, take a look at the classic "Gang of Four" design patterns book). Towards that end, the Chain API models a computation as a series of "protocol filter" that can be combined into a "protocol chain".

An Handler is a interface that can be implemented by implemented by client of the Grizzly Framework to used to help handling NIO operations. The Grizzly Framework define three Handlers:

     (1) SelectorHandler: A SelectorHandler handles all java.nio.channels.Selector
                         operations. One or more instance of a Selector are
                         handled by SelectorHandler. The logic for processing of
                         SelectionKey interest (OP_ACCEPT,OP_READ, etc.) is usually
                         defined using an instance of SelectorHandler.
     (2) SelectionKeyHandler: A SelectionKeyHandler is used to handle the life
                              life cycle of a SelectionKey. Operations like canceling,
                              registering or closing are handled by SelectionKeyHandler.
     (3) ProtocolChainInstanceHandler: An ProtocolChainInstanceHandler is where one or several ProtocolChain
                          are created and cached. An ProtocolChainInstanceHandler decide if
                          a stateless or statefull ProtocolChain needs to be created.

By default, the Grizzly Framework bundles implementation for TCP and UPD transport. The TCPSelectorHandler is instanciated by default. As an example, supporting the HTTP protocol should only consist of adding the appropriate ProtocolFilter like:

           Controller sel = new Controller();
           sel.setProtocolChainInstanceHandler(new DefaultProtocolChainInstanceHandler(){
               public ProtocolChain poll() {
                   ProtocolChain protocolChain = protocolChains.poll();
                   if (protocolChain == null){
                       protocolChain = new DefaultProtocolChain();
                       protocolChain.addFilter(new ReadFilter());
                       protocolChain.addFilter(new HTTPParserFilter());
                   }
                   return protocolChain;
               }
           });

In the example above, a pool of ProtocolChain will be created, and all instance of ProtocolChain will have their instance of ProtocolFilter. Hence the above implementation can be called statefull. A stateless implementation would instead consist of sharing the ProtocolFilter among ProtocolChain:

           final Controller sel = new Controller();
           final ReadFilter readFilter = new ReadFilter();
           final LogFilter logFilter = new LogFilter();

           sel.setProtocolChainInstanceHandler(new DefaultProtocolChainInstanceHandler(){
               public ProtocolChain poll() {
                   ProtocolChain protocolChain = protocolChains.poll();
                   if (protocolChain == null){
                       protocolChain = new DefaultProtocolChain();
                       protocolChain.addFilter(readFilter);
                       protocolChain.addFilter(logFilter);
                   }
                   return protocolChain;
               }
           });

Author:
  Jeanfrancois Arcand

Nested Class Summary
`static class` `Controller.Protocol`

Field Summary
`protected Map<String,Object>` `attributes` Attributes, associated with the `Controller` instance
`protected ConnectorHandlerPool` `connectorHandlerPool` The ConnectorHandlerPool, which is responsible for creating/caching ConnectorHandler instances.
`protected ProtocolChainInstanceHandler` `instanceHandler` The ProtocolChainInstanceHandler used by this instance.
`protected ComplexSelectorHandler` `multiReadThreadSelectorHandler` The SelectorHandler, which will manage connection accept, if readThreadsCount > 0 and spread connection processing between different read threads
`protected ReadController[]` `readThreadControllers` The array of `Controller`s to be used for reading
`protected int` `readThreadsCount` The number of read threads
`protected AtomicInteger` `readySelectorHandlerCounter` Internal countdown counter of `SelectorHandler`s, which are ready to process
`protected SelectionKeyHandler` `selectionKeyHandler` The SelectionKey Handler used by this instance.
`protected ConcurrentLinkedQueue<SelectorHandler>` `selectorHandlers` The set of `SelectorHandler`s used by this instance.
`protected StateHolder<State>` `stateHolder` Current `Controller` state
`protected Collection<ControllerStateListener>` `stateListeners` Collection of `Controller` state listeners, which will are notified on `Controller` state change.
`protected AtomicInteger` `stoppedSelectorHandlerCounter` Internal countdown counter of `SelectorHandler`s, which stopped

Constructor Summary
`Controller()` Controller constructor

Method Summary
`ConnectorHandler` `acquireConnectorHandler(Controller.Protocol protocol)` Return an instance of a `ConnectorHandler` based on the Protocol requested.
`void` `addSelectorHandler(SelectorHandler selectorHandler)` Add a `SelectorHandler`
`void` `addStateListener(ControllerStateListener stateListener)` Add controller state listener
`void` `cancelKey(SelectionKey key)` Deprecated.
`void` `configureContext(Context ctx, SelectorHandler selectorHandler)`
`void` `copyTo(Copyable copy)` Copy this Controller state to another instance of a Controller.
`protected void` `doSelect(SelectorHandler selectorHandler)` This method handle the processing of all Selector's interest op (OP_ACCEPT,OP_READ,OP_WRITE,OP_CONNECT) by delegating to its Handler.
`Object` `getAttribute(String key)` Return an object based on a key.
`Map<String,Object>` `getAttributes()` Return a `Map` of attribute name/value pairs.
`ConnectorHandlerPool` `getConnectorHandlerPool()` Return the `ConnectorHandlerPool` used.
`static Controller` `getHandlerController(Handler handler)` Return the Controller which is handling the `Handler`
`Pipeline` `getPipeline()` Return the `Pipeline` (Thread Pool) used by this Controller.
`ProtocolChainInstanceHandler` `getProtocolChainInstanceHandler()` Return the `ProtocolChainInstanceHandler`
`int` `getReadThreadsCount()` Return the number of Reader threads count.
`SelectionKeyHandler` `getSelectionKeyHandler()` Deprecated. Return the `SelectionKeyHandler` Method is deprecated. Use SelectorHandler.getSelectionKeyHandler() instead
`SelectorHandler` `getSelectorHandler(Controller.Protocol protocol)` Return the `SelectorHandler` associated with the protocol.
`SelectorHandler` `getSelectorHandler(Selector selector)` Return the `SelectorHandler` associated with the `Selector`.
`ConcurrentLinkedQueue` `getSelectorHandlers()` Return the list `SelectorHandler`
`StateHolder<State>` `getStateHolder()` Gets this `Controller`'s `StateHolder`
`boolean` `isHandleReadWriteConcurrently()` `true` if OP_ERAD and OP_WRITE can be handled concurrently.
`boolean` `isStarted()` Is this Controller started?
`static Logger` `logger()` Return the current `Logger` used by this Controller.
`void` `pause()` Pause this `Controller` and associated `SelectorHandler`s
`Context` `pollContext(SelectionKey key)` Get an instance of a `Context`
`Context` `pollContext(SelectionKey key, Context.OpType opType)` Get an instance of a `Context`
`void` `registerKey(SelectionKey key)` Register a SelectionKey.
`void` `registerKey(SelectionKey key, int ops)` Register a SelectionKey on the first SelectorHandler that was added using the addSelectorHandler().
`void` `registerKey(SelectionKey key, int ops, Controller.Protocol protocol)` Register a SelectionKey.
`void` `releaseConnectorHandler(ConnectorHandler connectorHandler)` Return a `ConnectorHandler` to the pool of ConnectorHandler.
`Object` `removeAttribute(String key)` Remove a key/value object.
`void` `removeSelectorHandler(SelectorHandler selectorHandler)` Shuts down `SelectorHandler` and removes it from this `Controller` list
`void` `removeStateListener(ControllerStateListener stateListener)` Remove controller state listener
`void` `resume()` Resume this `Controller` and associated `SelectorHandler`s
`void` `returnContext(Context ctx)` Return a Context to the pool
`void` `run()` Execute this Controller.
`void` `setAttribute(String key, Object value)` Set a key/value object.
`void` `setAttributes(Map<String,Object> attributes)` Set a `Map` of attribute name/value pairs.
`void` `setConnectorHandlerPool(ConnectorHandlerPool connectorHandlerPool)` Set the `ConnectorHandlerPool` used.
`void` `setHandleReadWriteConcurrently(boolean handleReadWriteConcurrently)` `true` if OP_ERAD and OP_WRITE can be handled concurrently.
`static void` `setLogger(Logger l)` Set the Logger single instance to use.
`void` `setPipeline(Pipeline<Callable> pipeline)` Set the `Pipeline` (Thread Pool).
`void` `setProtocolChainInstanceHandler(ProtocolChainInstanceHandler instanceHandler)` Set the `ProtocolChainInstanceHandler` to use for creating instance of `ProtocolChain`.
`void` `setReadThreadsCount(int readThreadsCount)` Set the number of Reader threads count.
`void` `setSelectionKeyHandler(SelectionKeyHandler selectionKeyHandler)` Deprecated. Set the `SelectionKeyHandler` to use for managing the life cycle of SelectionKey. Method is deprecated. Use SelectorHandler.setSelectionKeyHandler() instead
`void` `setSelectorHandler(SelectorHandler selectorHandler)` Set the first `SelectorHandler`
`void` `start()` Start the Controller.
`void` `stop()` Stop the Controller by canceling all the registered keys.
`void` `stop(boolean isAsync)` Stop the Controller by canceling all the registered keys.
`protected void` `waitUntilSeletorHandlersStop()` Method waits until all initialized `SelectorHandler`s will not get stopped

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

Field Detail

### instanceHandler

    protected ProtocolChainInstanceHandler instanceHandler

  The ProtocolChainInstanceHandler used by this instance. If not set, and instance of the DefaultInstanceHandler will be created.

### selectionKeyHandler

    protected SelectionKeyHandler selectionKeyHandler

  The SelectionKey Handler used by this instance. If not set, and instance of the DefaultSelectionKeyHandler will be created.

### multiReadThreadSelectorHandler

    protected ComplexSelectorHandler multiReadThreadSelectorHandler

  The SelectorHandler, which will manage connection accept, if readThreadsCount > 0 and spread connection processing between different read threads

### connectorHandlerPool

    protected ConnectorHandlerPool connectorHandlerPool

  The ConnectorHandlerPool, which is responsible for creating/caching ConnectorHandler instances.

### selectorHandlers

    protected ConcurrentLinkedQueue<SelectorHandler> selectorHandlers

  The set of `SelectorHandler`s used by this instance. If not set, the instance of the TCPSelectorHandler will be added by default.

### stateHolder

    protected StateHolder<State> stateHolder

  Current `Controller` state

### readThreadsCount

    protected int readThreadsCount

  The number of read threads

### readThreadControllers

    protected ReadController[] readThreadControllers

  The array of `Controller`s to be used for reading

### stateListeners

    protected Collection<ControllerStateListener> stateListeners

  Collection of `Controller` state listeners, which will are notified on `Controller` state change.

### readySelectorHandlerCounter

    protected AtomicInteger readySelectorHandlerCounter

  Internal countdown counter of `SelectorHandler`s, which are ready to process

### stoppedSelectorHandlerCounter

    protected AtomicInteger stoppedSelectorHandlerCounter

  Internal countdown counter of `SelectorHandler`s, which stopped

### attributes

    protected Map<String,Object> attributes

  Attributes, associated with the `Controller` instance

Constructor Detail

### Controller

    public Controller()

  Controller constructor

Method Detail

### doSelect

    protected void doSelect(SelectorHandler selectorHandler)

  This method handle the processing of all Selector's interest op (OP_ACCEPT,OP_READ,OP_WRITE,OP_CONNECT) by delegating to its Handler. By default, all java.nio.channels.Selector operations are implemented using SelectorHandler. All SelectionKey operations are implemented by SelectionKeyHandler. Finally, ProtocolChain creation/re-use are implemented by InstanceHandler.

  Parameters:
    `selectorHandler` - - the `SelectorHandler`

### registerKey

    public void registerKey(SelectionKey key)

  Register a SelectionKey.

  Parameters:
    `key` - `SelectionKey` to register

### registerKey

    public void registerKey(SelectionKey key,
                            int ops)

  Register a SelectionKey on the first SelectorHandler that was added using the addSelectorHandler().

  Parameters:
    `key` - `SelectionKey` to register
    `ops` - - the interest op to register

### registerKey

    public void registerKey(SelectionKey key,
                            int ops,
                            Controller.Protocol protocol)

  Register a SelectionKey.

  Parameters:
    `key` - `SelectionKey` to register
    `ops` - - the interest op to register
    `protocol` - specified protocol SelectorHandler key should be registered on

### cancelKey

    public void cancelKey(SelectionKey key)

  Deprecated.

  Cancel a SelectionKey

  Parameters:
    `key` - `SelectionKey` to cancel

### pollContext

    public Context pollContext(SelectionKey key)

  Get an instance of a `Context`

  Parameters:
    `key` - `SelectionKey`
  Returns:
    `Context`

### pollContext

    public Context pollContext(SelectionKey key,
                               Context.OpType opType)

  Get an instance of a `Context`

  Parameters:
    `key` - `SelectionKey`
    `opType` - the current SelectionKey op.
  Returns:
    `Context`

### configureContext

    public void configureContext(Context ctx,
                                 SelectorHandler selectorHandler)

### returnContext

    public void returnContext(Context ctx)

  Return a Context to the pool

  Parameters:
    `ctx` - - the `Context`

### logger

    public static Logger logger()

  Return the current `Logger` used by this Controller.

### setLogger

    public static void setLogger(Logger l)

  Set the Logger single instance to use.

### setProtocolChainInstanceHandler

    public void setProtocolChainInstanceHandler(ProtocolChainInstanceHandler instanceHandler)

  Set the `ProtocolChainInstanceHandler` to use for creating instance of `ProtocolChain`.

### getProtocolChainInstanceHandler

    public ProtocolChainInstanceHandler getProtocolChainInstanceHandler()

  Return the `ProtocolChainInstanceHandler`

### setSelectionKeyHandler

    public void setSelectionKeyHandler(SelectionKeyHandler selectionKeyHandler)

  Deprecated. Set the `SelectionKeyHandler` to use for managing the life cycle of SelectionKey. Method is deprecated. Use SelectorHandler.setSelectionKeyHandler() instead

### getSelectionKeyHandler

    public SelectionKeyHandler getSelectionKeyHandler()

  Deprecated. Return the `SelectionKeyHandler` Method is deprecated. Use SelectorHandler.getSelectionKeyHandler() instead

### addSelectorHandler

    public void addSelectorHandler(SelectorHandler selectorHandler)

  Add a `SelectorHandler`

  Parameters:
    `selectorHandler` - - the `SelectorHandler`

### setSelectorHandler

    public void setSelectorHandler(SelectorHandler selectorHandler)

  Set the first `SelectorHandler`

  Parameters:
    `selectorHandler` - - the `SelectorHandler`

### getSelectorHandler

    public SelectorHandler getSelectorHandler(Controller.Protocol protocol)

  Return the `SelectorHandler` associated with the protocol.

  Parameters:
    `protocol` - - the `Controller.Protocol`
  Returns:
    `SelectorHandler`

### getSelectorHandler

    public SelectorHandler getSelectorHandler(Selector selector)

  Return the `SelectorHandler` associated with the `Selector`.

  Parameters:
    `selector` - - the `Selector`
  Returns:
    `SelectorHandler`

### getSelectorHandlers

    public ConcurrentLinkedQueue getSelectorHandlers()

  Return the list `SelectorHandler`

  Returns:
    `ConcurrentLinkedQueue`

### removeSelectorHandler

    public void removeSelectorHandler(SelectorHandler selectorHandler)

  Shuts down `SelectorHandler` and removes it from this `Controller` list

  Parameters:
    `{@link` - SelectorHandler} to remove

### getPipeline

    public Pipeline getPipeline()

  Return the `Pipeline` (Thread Pool) used by this Controller.

### setPipeline

    public void setPipeline(Pipeline<Callable> pipeline)

  Set the `Pipeline` (Thread Pool).

### getReadThreadsCount

    public int getReadThreadsCount()

  Return the number of Reader threads count.

### setReadThreadsCount

    public void setReadThreadsCount(int readThreadsCount)

  Set the number of Reader threads count.

### getConnectorHandlerPool

    public ConnectorHandlerPool getConnectorHandlerPool()

  Return the `ConnectorHandlerPool` used.

### setConnectorHandlerPool

    public void setConnectorHandlerPool(ConnectorHandlerPool connectorHandlerPool)

  Set the `ConnectorHandlerPool` used.

### run

    public void run()

  Execute this Controller.

  Specified by:
    `run` in interface `Runnable`

### copyTo

    public void copyTo(Copyable copy)

  Copy this Controller state to another instance of a Controller.

  Specified by:
    `copyTo` in interface `Copyable`
  Parameters:
    `copy` - represents target object, where current object's content will be copied

### addStateListener

    public void addStateListener(ControllerStateListener stateListener)

  Add controller state listener

### removeStateListener

    public void removeStateListener(ControllerStateListener stateListener)

  Remove controller state listener

### start

    public void start()
               throws IOException

  Start the Controller. If the Pipeline and/or Handler has not been defined, the default will be used.

  Specified by:
    `start` in interface `Lifecycle`
  Throws:
    `IOException`

### stop

    public void stop()
              throws IOException

  Stop the Controller by canceling all the registered keys.

  Specified by:
    `stop` in interface `Lifecycle`
  Throws:
    `IOException`

### stop

    public void stop(boolean isAsync)
              throws IOException

  Stop the Controller by canceling all the registered keys.

  Parameters:
    `isAsync,` - true if controller should be stopped asynchrounously and control returned immediately. If false - control will be returned after Controller will be completely stoped.
  Throws:
    `IOException`

### pause

    public void pause()
               throws IOException

  Pause this `Controller` and associated `SelectorHandler`s

  Specified by:
    `pause` in interface `Lifecycle`
  Throws:
    `IOException`

### resume

    public void resume()
                throws IOException

  Resume this `Controller` and associated `SelectorHandler`s

  Specified by:
    `resume` in interface `Lifecycle`
  Throws:
    `IOException`

### getStateHolder

    public StateHolder<State> getStateHolder()

  Gets this `Controller`'s `StateHolder`

  Specified by:
    `getStateHolder` in interface `SupportStateHolder<State>`
  Returns:
    `StateHolder`

### isStarted

    public boolean isStarted()

  Is this Controller started?

  Returns:
    `boolean` true / false

### acquireConnectorHandler

    public ConnectorHandler acquireConnectorHandler(Controller.Protocol protocol)

  Return an instance of a `ConnectorHandler` based on the Protocol requested.

  Specified by:
    `acquireConnectorHandler` in interface `ConnectorHandlerPool`
  Parameters:
    `protocol` - a `Controller.Protocol`
  Returns:
    `ConnectorHandler`

### releaseConnectorHandler

    public void releaseConnectorHandler(ConnectorHandler connectorHandler)

  Return a `ConnectorHandler` to the pool of ConnectorHandler. Any reference to the returned must not be re-used as that instance can always be acquired again, causing unexpected results.

  Specified by:
    `releaseConnectorHandler` in interface `ConnectorHandlerPool`
  Parameters:
    `connectorHandler` - - a `ConnectorHandler`

### isHandleReadWriteConcurrently

    public boolean isHandleReadWriteConcurrently()

  `true` if OP_ERAD and OP_WRITE can be handled concurrently. If `false`, the Controller will first invoke the OP_READ handler and then invoke the OP_WRITE during the next Selector.select() invocation.

### setHandleReadWriteConcurrently

    public void setHandleReadWriteConcurrently(boolean handleReadWriteConcurrently)

  `true` if OP_ERAD and OP_WRITE can be handled concurrently. If `false`, the Controller will first invoke the OP_READ handler and then invoke the OP_WRITE during the next Selector.select() invocation.

### waitUntilSeletorHandlersStop

    protected void waitUntilSeletorHandlersStop()

  Method waits until all initialized `SelectorHandler`s will not get stopped

### removeAttribute

    public Object removeAttribute(String key)

  Remove a key/value object. Method is not thread safe

  Specified by:
    `removeAttribute` in interface `AttributeHolder`
  Parameters:
    `key` - - name of an attribute
  Returns:
    attribute which has been removed

### setAttribute

    public void setAttribute(String key,
                             Object value)

  Set a key/value object. Method is not thread safe

  Specified by:
    `setAttribute` in interface `AttributeHolder`
  Parameters:
    `key` - - name of an attribute
    `value` - - value of named attribute

### getAttribute

    public Object getAttribute(String key)

  Return an object based on a key. Method is not thread safe

  Specified by:
    `getAttribute` in interface `AttributeHolder`
  Parameters:
    `key` - - name of an attribute
  Returns:
    - attribute value for the `key`, null if `key` does not exist in `attributes`

### setAttributes

    public void setAttributes(Map<String,Object> attributes)

  Set a `Map` of attribute name/value pairs. Old `AttributeHolder` values will not be available. Later changes of this `Map` will lead to changes to the current `AttributeHolder`.

  Specified by:
    `setAttributes` in interface `AttributeHolder`
  Parameters:
    `attributes` - - map of name/value pairs

### getAttributes

    public Map<String,Object> getAttributes()

  Return a `Map` of attribute name/value pairs. Updates, performed on the returned `Map` will be reflected in this `AttributeHolder`

  Specified by:
    `getAttributes` in interface `AttributeHolder`
  Returns:
    - `Map` of attribute name/value pairs

### getHandlerController

    public static Controller getHandlerController(Handler handler)

  Return the Controller which is handling the `Handler`

  Parameters:
    `handler` - The handler (like `SelectorHandler`)
  Returns:
    The Controller associated with the Handler, or null if not associated.

Copyright © 2008 SUN Microsystems. All Rights Reserved.