com.sun.grizzly.comet
Class CometContext<E>

java.lang.Object
  extended by com.sun.grizzly.comet.CometContext<E>
Direct Known Subclasses:
CometContext

public class CometContext<E>
extends Object

The main object used by CometHandler and Servlet to push information amongs suspended request/response. The CometContext is always available for CometHandler and can be used to notify(java.lang.Object), or share information with other CometHandler. This is the equivalent of server push as the CometContext will invoke all registered CometHandler (addCometHandler(com.sun.grizzly.comet.CometHandler, boolean)) sequentially or using a thread pool when the setBlockingNotification(boolean) is set to false

A CometContext can be considered as a topic where CometHandler register for information. A CometContext can be shared amongs Servlet of the same application, or globally accros all deployed web applications. Normally, a CometContext is created using a topic's name like:


 
 CometEngine ce = CometEngine.getEngine();
 CometContext cc = ce.registerContext("MyTopic");
 cc.setBlockingNotification(false); // Use multiple thread to execute the server push
 
 and then inside a Servlet.service() method, you just need to call:
 
 cc.addCometListener(myNewCometListener());
 cc.notify("I'm pushing data to all registered CometHandler");
 

As soom as addCometHandler(com.sun.grizzly.comet.CometHandler, boolean) is invoked, Grizzly will automatically suspend the request/response (will not commit the response). A response can be resumed by invoking resumeCometHandler(com.sun.grizzly.comet.CometHandler), which will automatically commit the response and remove the associated CometHandler from the CometContext. A CometContext uses a NotificationHandler to invoke, using the calling thread or a Grizzly thread pool, all CometHandler than have been added using the addCometHandler(com.sun.grizzly.comet.CometHandler, boolean). A NotificationHandler can be used to filter or transform the content that will eventually be pushed back to all connected clients. You can also use a NotificationHandler to throttle push like invoking only a subset of the CometHandler, etc. Idle suspended connection can be timed out by configuring the setExpirationDelay(long). The value needs to be in milliseconds. If there is no I/O operations and no invokation of notify(java.lang.Object) during the expiration delay, Grizzly will resume all suspended connection. An application will have a chance to send back data using the connection as Grizzly will invoke the CometHandler.onInterrupt(com.sun.grizzly.comet.CometEvent) before resuming the connection. Note that setting the expiration delay to -1 disable the above mechanism, e.g. idle connection will never get resumed by Grizzly.

Attributes can be added/removed the same way HttpServletSession is doing. It is not recommended to use attributes if this CometContext is not shared amongst multiple context path (uses HttpServletSession instead).

Author:
Jeanfrancois Arcand, Gustav Trede

Field Summary
protected static String ALREADY_REMOVED
           
protected  boolean blockingNotification
          true if the caller of notify(java.lang.Object) should block when notifying other CometHandler.
protected  int continuationType
          The CometContext continuationType.
protected  CometEvent eventInterrupt
           
protected  CometEvent eventTerminate
           
protected  ConcurrentHashMap<CometHandler,CometTask> handlers
          The list of registered CometHandler
protected static String INVALID_COMET_HANDLER
          Generic error message
protected static Logger logger
          Main logger
protected  NotificationHandler notificationHandler
          The default NotificationHandler.
protected  String topic
          The context path associated with this instance.
 
Constructor Summary
CometContext(String contextTopic, int type)
          Create a new instance
 
Method Summary
protected  void addActiveHandler(CometTask cometTask)
          adds a CometTask to the active set
 void addAttribute(Object key, Object value)
          Add an attibute.
 int addCometHandler(CometHandler handler)
          Add a CometHandler which will starts the process of suspending the underlying response.
 int addCometHandler(CometHandler handler, boolean alreadySuspended)
          Add a CometHandler.
 Object getAttribute(Object key)
          Retrieve an attribute.
 CometHandler getCometHandler(int hashCode)
          Deprecated. 
 Set<CometHandler> getCometHandlers()
          Return the current list of active CometHandler
 String getContextPath()
          Deprecated. - use getTopic.
 long getExpirationDelay()
          Return the long delay, in millisecond, before a request is resumed.
 NotificationHandler getNotificationHandler()
          Return the associated NotificationHandler
 String getTopic()
          Get the topic representing this instance with this instance.
protected  ConcurrentHashMap<CometHandler,CometTask> handlers()
          Return the internal list of active CometHandler
protected  void initialize(CometHandler handler)
          Initialize the newly added CometHandler.
protected  void invokeCometHandler(CometEvent event, CometHandler cometHandler)
          Invoke a CometHandler using the CometEvent
 boolean isActive(CometHandler handler)
          Return true if this CometHandler is still active, e.g.
 boolean isBlockingNotification()
          Return true if the invoker of notify(java.lang.Object) should block when notifying Comet Handlers.
 void notify(Object attachment)
          Notify all CometHandler.
 void notify(Object attachment, CometHandler cometHandler)
          Notify a single CometHandler#onEvent(CometEvent.
 void notify(Object attachment, int eventType)
          Notify all CometHandler.
 void notify(Object attachment, int eventType, CometHandler cometHandler)
          Notify a single CometHandler.
 void notify(Object attachment, int eventType, int cometHandlerID)
          Deprecated. - use notify(attachment,eventType,CometHandler;
 void recycle()
          Recycle this object.
 boolean registerAsyncRead(CometHandler handler)
          Register for asynchronous read event (CometEvent#READ}.
 boolean registerAsyncWrite(CometHandler handler)
          Register for asynchronous write event (CometEvent#WRITE} .As soon as Grizzly detects there is some OS buffer available for write operations, your CometHandler.onEvent(CometEvent) will be invoked.
 Object removeAttribute(Object key)
          Remove an attribute.
 boolean removeCometHandler(CometHandler handler)
          Remove a CometHandler.
 boolean removeCometHandler(CometHandler handler, boolean resume)
          Remove a CometHandler.
 boolean removeCometHandler(int hashCode)
          Deprecated. 
protected  void resetSuspendIdleTimeout()
          Reset the current timestamp on a suspended connection.
 boolean resumeCometHandler(CometHandler handler)
          Resume the Comet request and remove it from the active CometHandler list.
 void setBlockingNotification(boolean blockingNotification)
          Set to true if the invoker of notify(java.lang.Object) should block when notifying Comet Handlers.
 void setExpirationDelay(long expirationDelay)
          Set the long delay before a request is resumed.
 void setNotificationHandler(NotificationHandler notificationHandler)
          Set the current NotificationHandler
 String toString()
          Helper.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

INVALID_COMET_HANDLER

protected static final String INVALID_COMET_HANDLER
Generic error message

See Also:
Constant Field Values

ALREADY_REMOVED

protected static final String ALREADY_REMOVED
See Also:
Constant Field Values

logger

protected static final Logger logger
Main logger


topic

protected String topic
The context path associated with this instance.


continuationType

protected int continuationType
The CometContext continuationType. See CometEngine


blockingNotification

protected boolean blockingNotification
true if the caller of notify(java.lang.Object) should block when notifying other CometHandler.


notificationHandler

protected NotificationHandler notificationHandler
The default NotificationHandler.


handlers

protected final ConcurrentHashMap<CometHandler,CometTask> handlers
The list of registered CometHandler


eventInterrupt

protected final CometEvent eventInterrupt

eventTerminate

protected final CometEvent eventTerminate
Constructor Detail

CometContext

public CometContext(String contextTopic,
                    int type)
Create a new instance

Parameters:
contextTopic - the context path
type - when the Comet processing will happen (see CometEngine).
Method Detail

getContextPath

public String getContextPath()
Deprecated. - use getTopic.

Get the context path associated with this instance.

Returns:
topic the context path associated with this instance

getTopic

public String getTopic()
Get the topic representing this instance with this instance. This is the value to uses when invoking CometEngine.getCometContext(java.lang.String)

Returns:
topic the topic associated with this instance

addAttribute

public void addAttribute(Object key,
                         Object value)
Add an attibute.

Parameters:
key - the key
value - the value

getAttribute

public Object getAttribute(Object key)
Retrieve an attribute.

Parameters:
key - the key
Returns:
Object the value.

removeAttribute

public Object removeAttribute(Object key)
Remove an attribute.

Parameters:
key - the key
Returns:
Object the value

addCometHandler

public int addCometHandler(CometHandler handler,
                           boolean alreadySuspended)
Add a CometHandler. The underlying HttpServletResponse will not get commited until resumeCometHandler(CometHandler) is invoked, unless the setExpirationDelay(long) expires. If set to alreadySuspended is set to true, no I/O operations are allowed inside the CometHandler as the underlying HttpServletResponse has not been suspended. Adding such CometHandler is usefull only when no I/O operations on the HttpServletResponse are required. Examples include calling a remote EJB when a push operations happens, storing data inside a database, etc.

Parameters:
handler - a new CometHandler
alreadySuspended - Add the Comethandler but don't suspend the HttpServletResponse. If set to true, no I/O operations are allowed inside the CometHandler as the underlying HttpServletResponse has not been suspended, unless the CometHandler is shared amongs more than one CometContext
Returns:
The CometHandler#hashCode value.

addCometHandler

public int addCometHandler(CometHandler handler)
Add a CometHandler which will starts the process of suspending the underlying response. The underlying HttpServletResponse will not get committed until resumeCometHandler(CometHandler) is invoked, unless the setExpirationDelay(long) expires.

Parameters:
handler - a new CometHandler

getCometHandler

@Deprecated
public CometHandler getCometHandler(int hashCode)
Deprecated. 

Retrieve a CometHandler using its based on its CometHandler#hashCode;


recycle

public void recycle()
Recycle this object.


addActiveHandler

protected void addActiveHandler(CometTask cometTask)
adds a CometTask to the active set

Parameters:
cometTask - CometTask

invokeCometHandler

protected void invokeCometHandler(CometEvent event,
                                  CometHandler cometHandler)
                           throws IOException
Invoke a CometHandler using the CometEvent

Parameters:
event - - CometEvent
cometHandler - - CometHandler
Throws:
IOException

removeCometHandler

public boolean removeCometHandler(CometHandler handler)
Remove a CometHandler. If the continuation (connection) associated with this CometHandler no longer have CometHandler associated to it, it will be resumed by Grizzly by calling resumeCometHandler(CometHandler)

Returns:
true if the operation succeeded.

removeCometHandler

public boolean removeCometHandler(CometHandler handler,
                                  boolean resume)
Remove a CometHandler. If the continuation (connection) associated with this CometHandler no longer have CometHandler associated to it, it will be resumed.

Parameters:
handler - The CometHandler to remove.
resume - True is the connection can be resumed if no CometHandler are associated with the underlying SelectionKey.
Returns:
true if the operation succeeded.

removeCometHandler

@Deprecated
public boolean removeCometHandler(int hashCode)
Deprecated. 

Remove a CometHandler based on its hashcode. Return true if the operation was sucessfull. O(n) performance.

Parameters:
hashCode - The hashcode of the CometHandler to remove.
Returns:
true if the operation succeeded.

resumeCometHandler

public boolean resumeCometHandler(CometHandler handler)
Resume the Comet request and remove it from the active CometHandler list. Once resumed, a CometHandler must never manipulate the HttpServletRequest or HttpServletResponse as those object will be recycled and may be re-used to serve another request. If you cache them for later reuse by another thread there is a possibility to introduce corrupted responses next time a request is made.

Parameters:
handler - The CometHandler to resume.
Returns:
true if the operation succeeded.

isActive

public boolean isActive(CometHandler handler)
Return true if this CometHandler is still active, e.g. there is still a suspended connection associated with it.

Returns:
true

handlers

protected ConcurrentHashMap<CometHandler,CometTask> handlers()
Return the internal list of active CometHandler

Returns:
Return the internal list of active CometHandler

notify

public void notify(Object attachment)
            throws IOException
Notify all CometHandler. All CometHandler.onEvent(com.sun.grizzly.comet.CometEvent) will be invoked with a CometEvent of type NOTIFY.

Parameters:
attachment - An object shared amongst CometHandler.
Throws:
IOException

notify

public void notify(Object attachment,
                   int eventType,
                   int cometHandlerID)
            throws IOException
Deprecated. - use notify(attachment,eventType,CometHandler;

Notify a single CometHandler. The CometEvent.getType() will determine which CometHandler method will be invoked:

 CometEvent.INTERRUPT -> CometHandler.onInterrupt(com.sun.grizzly.comet.CometEvent)
 CometEvent.NOTIFY -> CometHandler.onEvent(com.sun.grizzly.comet.CometEvent)
 CometEvent.INITIALIZE -> CometHandler.onInitialize(com.sun.grizzly.comet.CometEvent)
 CometEvent.TERMINATE -> CometHandler.onTerminate(com.sun.grizzly.comet.CometEvent)
 CometEvent.READ -> CometHandler.onEvent(com.sun.grizzly.comet.CometEvent)
 

Parameters:
attachment - An object shared amongst CometHandler.
eventType - The type of notification.
cometHandlerID - Notify a single CometHandler.
Throws:
IOException

notify

public void notify(Object attachment,
                   CometHandler cometHandler)
            throws IOException
Notify a single CometHandler#onEvent(CometEvent.

Parameters:
attachment - An object shared amongst CometHandler.
{@link - CometHandler} to notify.
Throws:
IOException

notify

public void notify(Object attachment,
                   int eventType,
                   CometHandler cometHandler)
            throws IOException
Notify a single CometHandler. The CometEvent.getType() will determine which CometHandler method will be invoked:

 CometEvent.INTERRUPT -> CometHandler.onInterrupt(com.sun.grizzly.comet.CometEvent)
 CometEvent.NOTIFY -> CometHandler.onEvent(com.sun.grizzly.comet.CometEvent)
 CometEvent.INITIALIZE -> CometHandler.onInitialize(com.sun.grizzly.comet.CometEvent)
 CometEvent.TERMINATE -> CometHandler.onTerminate(com.sun.grizzly.comet.CometEvent)
 CometEvent.READ -> CometHandler.onEvent(com.sun.grizzly.comet.CometEvent)
 

Parameters:
attachment - An object shared amongst CometHandler.
eventType - The type of notification.
{@link - CometHandler} to notify.
Throws:
IOException

notify

public void notify(Object attachment,
                   int eventType)
            throws IOException
Notify all CometHandler. The CometEvent.getType() will determine which CometHandler method will be invoked:

 CometEvent.INTERRUPT -> CometHandler.onInterrupt(com.sun.grizzly.comet.CometEvent)
 CometEvent.NOTIFY -> CometHandler.onEvent(com.sun.grizzly.comet.CometEvent)
 CometEvent.INITIALIZE -> CometHandler.onInitialize(com.sun.grizzly.comet.CometEvent)
 CometEvent.TERMINATE -> CometHandler.onTerminate(com.sun.grizzly.comet.CometEvent)
 CometEvent.READ -> CometHandler.onEvent(com.sun.grizzly.comet.CometEvent)
 

Parameters:
attachment - An object shared amongst CometHandler.
eventType - The type of notification.
Throws:
IOException

initialize

protected void initialize(CometHandler handler)
                   throws IOException
Initialize the newly added CometHandler.

Throws:
IOException

resetSuspendIdleTimeout

protected void resetSuspendIdleTimeout()
Reset the current timestamp on a suspended connection.


registerAsyncRead

public boolean registerAsyncRead(CometHandler handler)
Register for asynchronous read event (CometEvent#READ}. As soon as Grizzly detects there is some bytes available for read, your CometHandler.onEvent(CometEvent) will be invoked. CometEvent.attachment() will return an instance of CometReader that can be used to asynchronously read the available bytes. If your client supports http pipelining, invoking this method might result in a state where your CometHandler is invoked with a CometReader that will read the next http request. In that case, it is strongly recommended to not use that method unless your CometHandler can handle the http request.

Parameters:
handler - The CometHandler that will be invoked.

registerAsyncWrite

public boolean registerAsyncWrite(CometHandler handler)
Register for asynchronous write event (CometEvent#WRITE} .As soon as Grizzly detects there is some OS buffer available for write operations, your CometHandler.onEvent(CometEvent) will be invoked. CometEvent.attachment() will return an instance of CometWriter that can be used to asynchronously write the available bytes.

Parameters:
handler - The CometHandler that will be invoked.

toString

public String toString()
Helper.

Overrides:
toString in class Object

getExpirationDelay

public long getExpirationDelay()
Return the long delay, in millisecond, before a request is resumed.

Returns:
long the long delay, in millisecond, before a request is resumed.

setExpirationDelay

public void setExpirationDelay(long expirationDelay)
Set the long delay before a request is resumed.

Parameters:
expirationDelay - the long delay before a request is resumed. Value is in milliseconds.

getCometHandlers

public Set<CometHandler> getCometHandlers()
Return the current list of active CometHandler

Returns:
the current list of active CometHandler

isBlockingNotification

public boolean isBlockingNotification()
Return true if the invoker of notify(java.lang.Object) should block when notifying Comet Handlers.


setBlockingNotification

public void setBlockingNotification(boolean blockingNotification)
Set to true if the invoker of notify(java.lang.Object) should block when notifying Comet Handlers.


setNotificationHandler

public void setNotificationHandler(NotificationHandler notificationHandler)
Set the current NotificationHandler

Parameters:
notificationHandler -

getNotificationHandler

public NotificationHandler getNotificationHandler()
Return the associated NotificationHandler

Returns:


Copyright © 2012 Oracle Corporation. All Rights Reserved.