org.itsnat.core

Interface CometNotifier

All Superinterfaces:

ItsNatUserData

public interface CometNotifier
extends ItsNatUserData

Is used to implement the COMET or server push technique to notify the client to be updated usually when the document is changed.

The ItsNat COMET approach is based on AJAX or SCRIPT, the client is ever waiting for an asynchronous event to return. When new code must be sent to the client this event returns and updates the client and automatically a new asynchronous request is sent to the server waiting to new asynchronous server changes (technique sometimes called as "long polling").

Use COMET if you have to monitor by web a never ending server process.

Current implementation does not need a special server but it locks a thread per client (and a HTTP connection per client). This thread is stalled most of the time, the scalability issue is more related to the maximun number of threads the system can manage.

Author:

Jose Maria Arranz Santamaria

See Also:

ClientDocument.createCometNotifier()

Method Summary

Methods

Modifier and Type	Method and Description
void	addEventListener(EventListener listener) Adds an event listener to this Comet notifier.
ClientDocument	getClientDocument() Returns the parent client document this object belongs to.
long	getEventTimeout() Returns the default timeout in client of COMET AJAX/SCRIPT events.
long	getExpirationDelay() Returns the maximum expiration delay.
ItsNatDocument	getItsNatDocument() Returns the asociated document.
boolean	isStopped() Informs whether this notifier is stopped.
void	notifyClient() Notifies the client thread to send pending document modifications.
void	removeEventListener(EventListener listener) Removes the specified event listener from this Comet notifier.
void	setExpirationDelay(long expirationDelay) Sets the maximum expiration delay.
void	stop() Stops and disposes this notifier.

Methods inherited from interface org.itsnat.core.ItsNatUserData

containsUserValueName, getUserValue, getUserValueNames, removeUserValue, setUserValue

Method Detail

getClientDocument

ClientDocument getClientDocument()

Returns the parent client document this object belongs to.

Returns:

the parent client document.

getItsNatDocument

ItsNatDocument getItsNatDocument()

Returns the asociated document.

Returns:

the document object this Comet notifier is bound to.

notifyClient

void notifyClient()

Notifies the client thread to send pending document modifications.

This method may be called by a non-servlet based thread, and no synchronization of the ItsNatDocument is necessary.

The client thread is woke up to send document modifications to the client and a new web request is sent to the document again to wait a new notification.

stop

void stop()

Stops and disposes this notifier. The stalled client thread is woke up to send any pending modification and no new request is sent.

A stopped Comet notifier is invalid and cannot be reused.

isStopped

boolean isStopped()

Informs whether this notifier is stopped. A Comet notifier is stopped if it was explicitly stopped calling stop() or the associated document was destroyed.

Returns:

true if this notifier is stopped.

getExpirationDelay

long getExpirationDelay()

Returns the maximum expiration delay. This is the maximum time a stalled client thread will wait to receive a notification, if this limit is reached this notifier is automatically stopped.

This limit is defined to avoid an unlimited wait because the notifier process has ended and the notifier was not explicitly stopped.

Returns:

the maximum expiration delay in milliseconds. By default is 1 hour.

See Also:

setExpirationDelay(long)

setExpirationDelay

void setExpirationDelay(long expirationDelay)

Sets the maximum expiration delay.

Parameters:

expirationDelay - the maximum expiration delay in milliseconds.

See Also:

getExpirationDelay()

getEventTimeout

long getEventTimeout()

Returns the default timeout in client of COMET AJAX/SCRIPT events.

This is the maximum time a stalled COMET request will wait to receive a notification, if this limit is reached the last request is aborted stopping the COMET process. If a timeout is defined this value should be greater than getExpirationDelay().

COMET events are ever asynchronous.

Returns:

the timeout of COMET events in milliseconds.

addEventListener

void addEventListener(EventListener listener)

Adds an event listener to this Comet notifier. This listener is called when the client is going to be notified.

This method is not synchronized and must be called from a web request thread (in this context this method is thread safe because the ItsNat document is automatically synchronized).

Event listeners are dispatched using a web request thread, therefore the ItsNat document object is already synchronized and Java code can be the same as a normal event processing.

The event object used when dispatching the listener is a not a "real" DOM client event and most of methods have no meaning.

Parameters:

listener - the listener to add.

See Also:

removeEventListener(EventListener)

removeEventListener

void removeEventListener(EventListener listener)

Removes the specified event listener from this Comet notifier.

This method is not synchronized and must be called from a web request thread (in this context this method is thread safe because the ItsNat document is automatically synchronized).

Parameters:

listener - the listener to remove.

See Also:

addEventListener(EventListener)