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 ExecutorService. All of those components are configurable by client using the Grizzly Framework.

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 static Logger	logger Default Logger.
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 LinkedTransferQueue<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
protected ExecutorService	threadPool Default Thread Pool (called ExecutorService).If not set, and instance of the DefaultThreadPool will be created.

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 context, SelectorHandler selectorHandler) Configure the Context
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
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.
LinkedTransferQueue	getSelectorHandlers() Return the list SelectorHandler
StateHolder<State>	getStateHolder() Gets this Controller's StateHolder
ExecutorService	getThreadPool() Return the ExecutorService (Thread Pool) used by this Controller.
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.
protected void	notifyException(Throwable e) Notify exception occured
void	notifyReady() Notify controller is ready
void	notifyStarted() Notify controller started
void	notifyStopped() Notify controller stopped
void	pause() Pause this Controller and associated SelectorHandlers
Context	pollContext(SelectionKey key) Get an instance of a Context
NIOContext	pollContext(SelectionKey key, Context.OpType opType) Get an instance of a NIOContext
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 its pool if it is not shared.
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	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	setThreadPool(ExecutorService threadPool) Set the ExecutorService (Thread Pool).
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 LinkedTransferQueue<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

logger

protected static Logger logger

Default Logger.

threadPool

protected ExecutorService threadPool

Default Thread Pool (called ExecutorService).If not set, and instance of the DefaultThreadPool will be created.

stateListeners

protected final 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 NIOContext pollContext(SelectionKey key,
                              Context.OpType opType)

Get an instance of a NIOContext

Parameters:

key - SelectionKey

opType - the current SelectionKey op.

Returns:

Context

configureContext

public void configureContext(Context context,
                             SelectorHandler selectorHandler)

Configure the Context

Parameters:

context -

selectorHandler -

returnContext

public void returnContext(Context ctx)

Return a Context to its pool if it is not shared.

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 LinkedTransferQueue 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

getThreadPool

public ExecutorService getThreadPool()

Return the ExecutorService (Thread Pool) used by this Controller.

setThreadPool

public void setThreadPool(ExecutorService threadPool)

Set the ExecutorService (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

addStateListener

public void addStateListener(ControllerStateListener stateListener)

Add controller state listener

removeStateListener

public void removeStateListener(ControllerStateListener stateListener)

Remove controller state listener

notifyStarted

public void notifyStarted()

Notify controller started

notifyReady

public void notifyReady()

Notify controller is ready

notifyStopped

public void notifyStopped()

Notify controller stopped

notifyException

protected void notifyException(Throwable e)

Notify exception occured

start

public void start()
           throws IOException

Start the Controller. If the thread pool 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 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 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.