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: import java.util.Date;
017: import org.itsnat.core.event.CodeToSendListener;
018: import org.w3c.dom.events.Event;
019: import org.w3c.dom.events.EventException;
020: import org.w3c.dom.events.EventTarget;
021:
022: /**
023: * Represents the browser's document/page. A browser's document may be a "normal" document (owner)
024: * or a remote view/control document (viewer).
025: *
026: * @see ItsNatDocument#getClientDocumentOwner()
027: * @see ItsNatServletRequest#getClientDocument()
028: * @author Jose Maria Arranz Santamaria
029: */
030: public interface ClientDocument extends ItsNatUserData {
031: /**
032: * Returns the client identity. This value is unique per {@link ItsNatSession}
033: * and never reused in this context.
034: *
035: * <p>The identity value is unique no other session-identified object in the same session
036: * shares the same id.</p>
037: *
038: * <p>Although this object is garbage collected, the identity value is never reused
039: * by another session-identified object in the same session.</p>
040: *
041: * @return the identity value.
042: */
043: public String getId();
044:
045: /**
046: * Returns the parent ItsNat session. If this object is a viewer the session
047: * may be different to the document owner session.
048: *
049: * @return the ItsNat session.
050: */
051: public ItsNatSession getItsNatSession();
052:
053: /**
054: * Returns the ItsNat document associated. If this object is a viewer
055: * the document is not hold by a strong reference and may be null if
056: * it was destroyed (the observer browser page may outlive to the main/owner page, only
057: * the owner destroys the document).
058: *
059: * @return the ItsNat document, may be null if this client is a viewer.
060: */
061: public ItsNatDocument getItsNatDocument();
062:
063: /**
064: * Add JavaScript code to send to the client (pending code). This code is removed and
065: * sent to the client as the return of the load process or any AJAX event.
066: *
067: * <p>Use this method exceptionally if <i>only</i> this client must receive the code,
068: * otherwise use {@link ItsNatDocument#addCodeToSend(Object)}</p>
069: *
070: * @param code the code to send, <code>Object.toString()</code> is called to convert to string.
071: * @see #isSendCodeEnabled()
072: * @see org.itsnat.core.script.ScriptUtil
073: * @throws ItsNatException if no code can be added.
074: */
075: public void addCodeToSend(Object code);
076:
077: /**
078: * Informs whether JavaScript code can be added to send to the client
079: * calling {@link #addCodeToSend(Object)}
080: *
081: * @return true if new code can be added.
082: * @see #disableSendCode()
083: */
084: public boolean isSendCodeEnabled();
085:
086: /**
087: * Disables the {@link #addCodeToSend(Object)} method, no new code can be added
088: * to send to the client.
089: *
090: * @see #enableSendCode()
091: */
092: public void disableSendCode();
093:
094: /**
095: * Enables the {@link #addCodeToSend(Object)} method, new code can be added
096: * to send to the client.
097: *
098: * @see #disableSendCode()
099: */
100: public void enableSendCode();
101:
102: /**
103: * Registers a new <code>CodeToSendListener</code>, this listener is called
104: * every time {@link #addCodeToSend(Object)} is called.
105: *
106: * @param listener the new listener.
107: * @see #removeCodeToSendListener(CodeToSendListener)
108: */
109: public void addCodeToSendListener(CodeToSendListener listener);
110:
111: /**
112: * Removes a previously registered <code>CodeToSendListener</code>.
113: *
114: * @param listener the new listener.
115: * @see #addCodeToSendListener(CodeToSendListener)
116: */
117: public void removeCodeToSendListener(CodeToSendListener listener);
118:
119: /**
120: * Returns the date when this object was created.
121: *
122: * @return the creation date
123: */
124: public Date getCreationDate();
125:
126: /**
127: * Creates a COMET notifier bound to this client and to the server document associated.
128: *
129: * <p>Current implementation calls {@link #createCometNotifier(long)} with the
130: * default AJAX timeout returned by {@link ItsNatDocument#getAJAXTimeout()}.</p>
131: *
132: * @return a new COMET notifier.
133: */
134: public CometNotifier createCometNotifier();
135:
136: /**
137: * Creates a COMET notifier bound to this client and to the server document associated.
138: *
139: * @param ajaxTimeout the timeout for the AJAX requests used to notify the client. If negative no timeout is defined.
140: * @return a new COMET notifier.
141: */
142: public CometNotifier createCometNotifier(long ajaxTimeout);
143:
144: /**
145: * Executes the specified task in a new thread, this code is ready to
146: * call <code>EventTarget.dispatchEvent(Event)</code> or
147: * {@link #dispatchEvent(EventTarget,Event,int,long)}
148: * many times.
149: *
150: * <p>Use the thread created by this method to send events fired in the server
151: * to the browser simulating user actions.
152: * </p>
153: *
154: * <p>This method must be called using a servlet-request thread.</p>
155: *
156: * @param task the task to execute.
157: */
158: public void startEventDispatcherThread(Runnable task);
159:
160: /**
161: * Sends the specified event to the browser and waits until this event is dispatched
162: * calling dispatchEvent (FireFox) or fireEvent (MSIE) on the browser.
163: * The call returns when the event is processed by the browser.
164: *
165: * <p>This method must not be called using a servlet-request thread.
166: * See the Reference Manual ("Events fired by the server" chapter) about requirements of the caller thread.
167: * </p>
168: *
169: * <p>The <code>syncMode</code> parameter and <code>ajaxTimeout</code> are used to specify the synchronous
170: * mode and timeout of the internal event sent to the server to notify the client has
171: * already dispatched the event.
172: * </p>
173: *
174: * @param target the event target DOM object.
175: * @param evt the DOM event to send to target.
176: * @param syncMode synchronization mode.
177: * @param ajaxTimeout the timeout of the AJAX event whether asynchronous. If negative no timeout is defined.
178: * @see ItsNatDocument#dispatchEvent(EventTarget,Event)
179: * @see #startEventDispatcherThread(Runnable code)
180: */
181: public boolean dispatchEvent(EventTarget target, Event evt,
182: int syncMode, long ajaxTimeout) throws EventException;
183:
184: }
|