org.glassfish.grizzly.comet
Class CometContext<E>

java.lang.Object
  extended by org.glassfish.grizzly.comet.CometContext<E>

public class CometContext<E>
extends Object

The main object used by CometHandler and Servlet to push information amongst suspended request/response. The CometContext is always available for CometHandler and can be used to notify(E), or share information with other CometHandler. This is the equivalent of server push as the CometContext will invoke all registered CometHandler (addCometHandler(org.glassfish.grizzly.comet.CometHandler)) sequentially.

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


 

CometEngine ce = CometEngine.getEngine(); CometContext cc = ce.registerContext("MyTopic");

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 soon as addCometHandler(org.glassfish.grizzly.comet.CometHandler) is invoked, Grizzly will automatically suspend the request/response (will not commit the response). A response can be resumed by invoking resumeCometHandler(org.glassfish.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(org.glassfish.grizzly.comet.CometHandler). 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 invocation of notify(E) 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(org.glassfish.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).


Field Summary
protected static String ALREADY_REMOVED
           
protected static ThreadLocal<Connection> connection
           
protected  CometEvent<CometContext> eventInterrupt
           
protected  CometEvent<CometContext> eventTerminate
           
protected static String INVALID_COMET_HANDLER
          Generic error message
protected static Logger logger
           
protected  NotificationHandler notificationHandler
          The default NotificationHandler.
protected  String topic
          The context path associated with this instance.
 
Constructor Summary
CometContext(CometEngine engine, String contextTopic)
          Create a new instance
 
Method Summary
 void addAttribute(Object key, Object value)
          Add an attribute.
 int addCometHandler(CometHandler<E> handler)
          Add a CometHandler.
 Object getAttribute(Object key)
          Retrieve an attribute.
 List<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  void initialize(CometHandler handler)
          Initialize the newly added CometHandler.
 boolean interrupt(CometHandler handler, boolean finishExecution)
          Interrupt a CometHandler by invoking CometHandler.onInterrupt(org.glassfish.grizzly.comet.CometEvent)
protected  void interrupt0(CometHandler handler, boolean finishExecution)
          Interrupt logic in its own method, so it can be executed either async or sync.
cometHandler.onInterrupt is performed async due to its functionality is unknown, hence not safe to run in the performance critical selector thread.
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 isDetectClosedConnections()
          Returns true if connection terminate detection is on.
 void notify(E attachment)
          Notify all CometHandler.
 void notify(E attachment, CometEvent.Type eventType)
          Notify all CometHandler.
 void notify(E attachment, CometEvent.Type eventType, CometHandler cometHandler)
          Notify a single CometHandler.
 void notify(E attachment, CometHandler cometHandler)
          Notify a single CometHandler.onEvent(CometEvent).
 void recycle()
          Recycle this object.
 Object removeAttribute(Object key)
          Remove an attribute.
 boolean removeCometHandler(CometHandler handler)
          Remove a CometHandler.
 boolean removeCometHandler(CometHandler handler, boolean resume)
          Remove a CometHandler.
 boolean resumeCometHandler(CometHandler handler)
          Resume the Comet request and remove it from the active CometHandler list.
 void setDetectClosedConnections(boolean isDetectClosedConnections)
          Enable/disable the mechanism, which detects closed connections and notifies user's handlers via CometHandler.onInterrupt(org.glassfish.grizzly.comet.CometEvent) method.
 void setExpirationDelay(long expirationDelay)
          Set the long delay before a request is resumed.
 void setNotificationHandler(NotificationHandler notificationHandler)
          Set the current NotificationHandler
 String toString()
           
 
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

connection

protected static final ThreadLocal<Connection> connection

topic

protected String topic
The context path associated with this instance.


notificationHandler

protected NotificationHandler notificationHandler
The default NotificationHandler.


eventInterrupt

protected final CometEvent<CometContext> eventInterrupt

eventTerminate

protected final CometEvent<CometContext> eventTerminate
Constructor Detail

CometContext

public CometContext(CometEngine engine,
                    String contextTopic)
Create a new instance

Parameters:
contextTopic - the context path
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 attribute.

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<E> handler)
Add a CometHandler. The underlying HttpServletResponse will not get committed 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 useful 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
Returns:
The hash code of the handler.

recycle

public void recycle()
Recycle this object.


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.

resumeCometHandler

public boolean resumeCometHandler(CometHandler handler)
                           throws IOException
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.
Throws:
IOException

interrupt

public boolean interrupt(CometHandler handler,
                         boolean finishExecution)
                  throws IOException
Interrupt a CometHandler by invoking CometHandler.onInterrupt(org.glassfish.grizzly.comet.CometEvent)

Parameters:
handler - The CometHandler encapsulating the suspended connection.
finishExecution - Finish the current execution.
Throws:
IOException

interrupt0

protected void interrupt0(CometHandler handler,
                          boolean finishExecution)
                   throws IOException
Interrupt logic in its own method, so it can be executed either async or sync.
cometHandler.onInterrupt is performed async due to its functionality is unknown, hence not safe to run in the performance critical selector thread.

Parameters:
handler - The CometHandler encapsulating the suspended connection.
finishExecution - Finish the current execution.
Throws:
IOException

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

notify

public void notify(E attachment)
            throws IOException
Notify all CometHandler. All CometHandler.onEvent(org.glassfish.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(E attachment,
                   CometHandler cometHandler)
            throws IOException
Notify a single CometHandler.onEvent(CometEvent).

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

notify

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

 CometEvent.INTERRUPT -> CometHandler.onInterrupt(CometEvent)
 CometEvent.Type.NOTIFY -> CometHandler.onEvent(CometEvent)
 CometEvent.INITIALIZE -> CometHandler.onInitialize(CometEvent)
 CometEvent.TERMINATE -> CometHandler.onTerminate(CometEvent)
 CometEvent.READ -> CometHandler.onEvent(CometEvent)
 

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

notify

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

 CometEvent.Type.INTERRUPT -> CometHandler.onInterrupt(org.glassfish.grizzly.comet.CometEvent)
 CometEvent.Type.NOTIFY -> CometHandler.onEvent(org.glassfish.grizzly.comet.CometEvent)
 CometEvent.Type.INITIALIZE -> CometHandler.onInitialize(org.glassfish.grizzly.comet.CometEvent)
 CometEvent.Type.TERMINATE -> CometHandler.onTerminate(org.glassfish.grizzly.comet.CometEvent)
 CometEvent.Type.READ -> CometHandler.onEvent(org.glassfish.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

toString

public String toString()
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 List<CometHandler> getCometHandlers()
Return the current list of active CometHandler

Returns:
the current list of active CometHandler

setNotificationHandler

public void setNotificationHandler(NotificationHandler notificationHandler)
Set the current NotificationHandler


getNotificationHandler

public NotificationHandler getNotificationHandler()
Return the associated NotificationHandler


setDetectClosedConnections

public void setDetectClosedConnections(boolean isDetectClosedConnections)
Enable/disable the mechanism, which detects closed connections and notifies user's handlers via CometHandler.onInterrupt(org.glassfish.grizzly.comet.CometEvent) method. If this feature is on - HTTP pipelining can not be used.

Parameters:
isDetectClosedConnections -

isDetectClosedConnections

public boolean isDetectClosedConnections()
Returns true if connection terminate detection is on. If this feature is on - HTTP pipelining can not be used. The feature is enabled by default.



Copyright © 2013 Oracle Corporation. All Rights Reserved.