org.glassfish.grizzly.comet

Class CometContext<E>

java.lang.Object

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<E>)) 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<E>) 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<E>). 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

Fields

Modifier and Type	Field and Description
protected static String	ALREADY_REMOVED
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 static ThreadLocal<Request>	REQUEST_LOCAL
protected String	topic The context path associated with this instance.

Constructor Summary

Constructors

Constructor and Description
CometContext(CometEngine engine, String contextTopic) Create a new instance

Method Summary

Modifier and Type	Method and Description
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

REQUEST_LOCAL

protected static final ThreadLocal<Request> REQUEST_LOCAL

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.