001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013:
014: package org.itsnat.core;
015:
016: /**
017: * Is used to implement the <i>Comet</i> or <i>server push</i> technique to notify
018: * the client to be updated usually when the document is changed.
019: *
020: * <p>The ItsNat Comet approach is based on AJAX, the client is ever waiting for an
021: * AJAX asynchronous event to return. When new code must be sent to the client
022: * this event returns and updates the client and automatically a new AJAX asynchronous
023: * request is sent to the server waiting to new asynchronous server changes
024: * (technique sometimes called as
025: * <a href="http://weblogs.java.net/blog/jfarcand/archive/2007/05/new_adventures.html">"long polling"</a>).
026: * </p>
027: *
028: * <p>Use COMET if you have to monitor by web a never ending server process.</p>
029: *
030: * <p>Current implementation does not need a special server but it locks a thread per client
031: * (and a HTTP connection per client). This thread is stalled most of the time,
032: * the scalability issue is more related to the maximun number of threads
033: * the system can manage.</p>
034: *
035: * @see ClientDocument#createCometNotifier()
036: * @see ItsNatDocument#addAsynchronousTask(Runnable,boolean)
037: * @author Jose Maria Arranz Santamaria
038: */
039: public interface CometNotifier {
040: /**
041: * Returns the asociated document.
042: *
043: * @return the document object this Comet notifier is bound to.
044: */
045: public ItsNatDocument getItsNatDocument();
046:
047: /**
048: * Notifies the client thread to send pending document modifications.
049: *
050: * <p>This method may be called by a non-servlet based thread, and no
051: * synchronization of the {@link ItsNatDocument} is necessary.</p>
052: *
053: * <p>The client thread is woke up to send document modifications and
054: * a new AJAX request is sent to wait again.</p>
055: */
056: public void notifyClient();
057:
058: /**
059: * Stops and disposes this notifier. The stalled client thread is woke up
060: * to send any pending modification and no new request is sent.
061: *
062: * <p>A stopped Comet notifier is invalid and cannot be reused.</p>
063: */
064: public void stop();
065:
066: /**
067: * Informs whether this notifier is stopped. A Comet notifier is stopped if it was
068: * explicitly stopped calling {@link #stop()} or the associated document was destroyed.
069: *
070: * @return true if this notifier is stopped.
071: */
072: public boolean isStopped();
073:
074: /**
075: * Returns the maximum expiration delay. This is the maximum time a stalled client thread
076: * will wait to receive a notification, if this limit is reached this notifier is automatically
077: * stopped.
078: *
079: * <p>This limit is defined to avoid an unlimited wait because the notifier process has ended and the notifier
080: * was not explicitly stopped.</p>
081: *
082: * @return the maximum expiration delay in milliseconds. By default is 1 hour.
083: * @see #setExpirationDelay(long)
084: */
085: public long getExpirationDelay();
086:
087: /**
088: * Sets the maximum expiration delay.
089: *
090: * @param expirationDelay the maximum expiration delay in milliseconds.
091: * @see #getExpirationDelay()
092: */
093: public void setExpirationDelay(long expirationDelay);
094:
095: /**
096: * Returns the default timeout of COMET AJAX events.
097: *
098: * <p>This is the maximum time a stalled COMET AJAX request will wait to receive
099: * a notification, if this limit is reached the last request is aborted
100: * stopping the COMET process. If a timeout is defined this value should be greater than {@link #getExpirationDelay()}.</p>
101: *
102: * <p>COMET AJAX events are ever asynchronous.</p>
103: *
104: * @return the timeout of COMET AJAX events in miliseconds.
105: */
106: public long getAJAXTimeout();
107: }
|