com.sun.grizzly
Class Controller

java.lang.Object
  extended by 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 Controllers to be used for reading
protected  int readThreadsCount
          The number of read threads
protected  AtomicInteger readySelectorHandlerCounter
          Internal countdown counter of SelectorHandlers, which are ready to process
protected  SelectionKeyHandler selectionKeyHandler
          The SelectionKey Handler used by this instance.
protected  ConcurrentLinkedQueue<SelectorHandler> selectorHandlers
          The set of SelectorHandlers 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 SelectorHandlers, 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 SelectorHandlers
 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 SelectorHandlers
 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 SelectorHandlers 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 SelectorHandlers 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 Controllers 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 SelectorHandlers, which are ready to process


stoppedSelectorHandlerCounter

protected AtomicInteger stoppedSelectorHandlerCounter
Internal countdown counter of SelectorHandlers, 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 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:
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 SelectorHandlers

Specified by:
pause in interface Lifecycle
Throws:
IOException

resume

public void resume()
            throws IOException
Resume this Controller and associated SelectorHandlers

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 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 SelectorHandlers 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.