0001: /*
0002: ItsNat Java Web Application Framework
0003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
0004: Author: Jose Maria Arranz Santamaria
0005:
0006: This program is free software: you can redistribute it and/or modify
0007: it under the terms of the GNU Affero General Public License as published by
0008: the Free Software Foundation, either version 3 of the License, or
0009: (at your option) any later version. See the GNU Affero General Public
0010: License for more details. See the copy of the GNU Affero General Public License
0011: included in this program. If not, see <http://www.gnu.org/licenses/>.
0012: */
0013:
0014: package org.itsnat.core;
0015:
0016: import java.text.DateFormat;
0017: import java.text.NumberFormat;
0018: import java.util.Date;
0019: import java.util.Enumeration;
0020: import org.itsnat.comp.ItsNatComponentManager;
0021: import org.itsnat.core.domutil.ElementLabel;
0022: import org.itsnat.core.domutil.ElementLabelRenderer;
0023: import org.itsnat.core.script.ScriptUtil;
0024: import org.itsnat.core.domutil.ElementRenderer;
0025: import org.itsnat.core.domutil.ElementList;
0026: import org.itsnat.core.domutil.ElementTable;
0027: import org.itsnat.core.domutil.ElementTreeNode;
0028: import org.itsnat.core.event.CodeToSendListener;
0029: import org.itsnat.core.event.RemoteControlEventListener;
0030: import org.itsnat.core.event.ParamTransport;
0031: import org.itsnat.core.domutil.ElementListFree;
0032: import org.itsnat.core.domutil.ElementListRenderer;
0033: import org.itsnat.core.domutil.ElementTableRenderer;
0034: import org.itsnat.core.domutil.ElementTreeNodeRenderer;
0035: import org.itsnat.core.domutil.ElementListStructure;
0036: import org.itsnat.core.domutil.ElementTableFree;
0037: import org.itsnat.core.domutil.ElementTableStructure;
0038: import org.itsnat.core.domutil.ElementTree;
0039: import org.itsnat.core.domutil.ElementTreeNodeList;
0040: import org.itsnat.core.domutil.ElementTreeNodeStructure;
0041: import org.itsnat.core.event.ItsNatServletRequestListener;
0042: import org.w3c.dom.Document;
0043: import org.w3c.dom.Element;
0044: import org.w3c.dom.Node;
0045: import org.w3c.dom.events.Event;
0046: import org.w3c.dom.events.EventException;
0047: import org.w3c.dom.events.EventListener;
0048: import org.w3c.dom.events.EventTarget;
0049:
0050: /**
0051: * Is the ItsNat wrapper of a <code>org.w3c.dom.Document</code> object. Usually represents a web page
0052: * loaded by a client.
0053: *
0054: * <p>Provides many useful utilities to simulate "The Browser Is The Server" approach of
0055: * ItsNat like event listener registries. Is the factory of DOM utility objects and ItsNat components.</p>
0056: *
0057: * <p>ItsNat document objects are created using a {@link DocumentTemplate} as pattern and
0058: * usually obtained calling {@link ItsNatServletRequest#getItsNatDocument()}
0059: * or {@link ItsNatServletResponse#getItsNatDocument()}
0060: * when a new document (page) is loading or calling {@link org.itsnat.core.event.ItsNatEvent#getItsNatDocument()}
0061: * when an AJAX event is received.</p>
0062: *
0063: * <p>Is not thread save and any object depending on this document (DOM utility objects,
0064: * components etc) is not thread save too. This is not a problem because any ItsNat request/response
0065: * thread synchronizes this object before calling user defined code, user defined code
0066: * executed by an ItsNat request/response thread may be unaware of synchronization isues.</p>
0067: *
0068: * @author Jose Maria Arranz Santamaria
0069: */
0070: public interface ItsNatDocument extends ItsNatUserData, ItsNatNode {
0071: /**
0072: * Returns the client identity. This value is unique per {@link ItsNatSession}
0073: * and never reused in this context.
0074: *
0075: * <p>The identity value is unique no other session-identified object in the same session
0076: * shares the same id.</p>
0077: *
0078: * <p>Although this object is garbage collected, the identity value is never reused
0079: * by another session-identified object in the same session.</p>
0080: *
0081: * @return the identity value.
0082: */
0083: public String getId();
0084:
0085: /**
0086: * Returns the default synchronous mode of AJAX events. Is used to new event listeners when no sync mode
0087: * is specified.
0088: *
0089: * <p>The default value is defined by {@link DocumentTemplate#getDefaultSyncMode()}</p>
0090: *
0091: * @return the synchronous mode.
0092: * @see #setDefaultSyncMode(int)
0093: * @see SyncMode
0094: */
0095: public int getDefaultSyncMode();
0096:
0097: /**
0098: * Sets the default synchronous mode of AJAX events. Current defined event listeners
0099: * are not affected.
0100: *
0101: * @param syncMode the new synchronous mode.
0102: * @see #getDefaultSyncMode()
0103: */
0104: public void setDefaultSyncMode(int syncMode);
0105:
0106: /**
0107: * Returns the default timeout of asynchronous AJAX events.
0108: *
0109: * <p>This feature is ignored in synchronous AJAX events</p>
0110: *
0111: * <p>When an unfinished AJAX request takes more time than the specified timeout,
0112: * the request is aborted.</p>
0113: *
0114: * <p>The default value is defined by {@link DocumentTemplate#getAJAXTimeout()}</p>
0115: *
0116: * @return the timeout of asynchronous AJAX events in miliseconds.
0117: * @see #setAJAXTimeout(long)
0118: */
0119: public long getAJAXTimeout();
0120:
0121: /**
0122: * Sets the default timeout of asynchronous AJAX events.
0123: *
0124: * @param timeout the new timeout. If negative no timeout is defined.
0125: * @see #getAJAXTimeout()
0126: */
0127: public void setAJAXTimeout(long timeout);
0128:
0129: /**
0130: * Returns the default data format used by components such as
0131: * {@link org.itsnat.comp.html.ItsNatHTMLInputTextFormatted}.
0132: *
0133: * <p>The default value is defined by {@link DocumentTemplate#getDefaultDateFormat()}</p>
0134: *
0135: * @return the default date format.
0136: * @see #setDefaultDateFormat(DateFormat)
0137: */
0138: public DateFormat getDefaultDateFormat();
0139:
0140: /**
0141: * Sets the default data format used by components such as
0142: * {@link org.itsnat.comp.html.ItsNatHTMLInputTextFormatted}.
0143: *
0144: * @param format the default data format.
0145: * @see #getDefaultDateFormat()
0146: */
0147: public void setDefaultDateFormat(DateFormat format);
0148:
0149: /**
0150: * Returns the default number format used by components such as
0151: * {@link org.itsnat.comp.html.ItsNatHTMLInputTextFormatted}.
0152: *
0153: * <p>The default value is defined by {@link DocumentTemplate#getDefaultNumberFormat()}</p>
0154: *
0155: * @return the default data format.
0156: * @see #setDefaultNumberFormat(NumberFormat)
0157: */
0158: public NumberFormat getDefaultNumberFormat();
0159:
0160: /**
0161: * Sets the default data format used by components such as
0162: * {@link org.itsnat.comp.html.ItsNatHTMLInputTextFormatted}.
0163: *
0164: * @param format the default data format.
0165: * @see #getDefaultNumberFormat()
0166: */
0167: public void setDefaultNumberFormat(NumberFormat format);
0168:
0169: /**
0170: * Returns the default max wait until a server fired event calling
0171: * {@link ClientDocument#dispatchEvent(org.w3c.dom.events.EventTarget,org.w3c.dom.events.Event,int,long)}
0172: * is processed by the client and returns.
0173: *
0174: * <p>The default value is defined by {@link DocumentTemplate#getEventDispatcherMaxWait()}</p>
0175: *
0176: * @return the default max wait in milliseconds.
0177: * @see #setEventDispatcherMaxWait(long)
0178: * @see #getItsNatNode(org.w3c.dom.Node)
0179: */
0180: public long getEventDispatcherMaxWait();
0181:
0182: /**
0183: * Sets the default max wait until a server fired event with
0184: * {@link ClientDocument#dispatchEvent(org.w3c.dom.events.EventTarget,org.w3c.dom.events.Event,int,long)}
0185: * is processed by the client and returns.
0186: *
0187: * @param wait the default max wait in milliseconds.
0188: * @see #getEventDispatcherMaxWait()
0189: */
0190: public void setEventDispatcherMaxWait(long wait);
0191:
0192: /**
0193: * Informs whether dom utils and components use by default the original
0194: * (saved as pattern) markup to render.
0195: *
0196: * <p>The default value is defined by {@link DocumentTemplate#isUsePatternMarkupToRender()}</p>
0197: *
0198: * @return true if by default the original markup is used.
0199: * @see #setUsePatternMarkupToRender(boolean)
0200: */
0201: public boolean isUsePatternMarkupToRender();
0202:
0203: /**
0204: * Sets whether dom utils and components use by default the original
0205: * (saved as pattern) markup to render.
0206: *
0207: * @param value true to enable the use of original markup to render.
0208: * @see #isUsePatternMarkupToRender()
0209: */
0210: public void setUsePatternMarkupToRender(boolean value);
0211:
0212: /**
0213: * Returns the template this document is based on.
0214: *
0215: * @return the template of this document.
0216: */
0217: public DocumentTemplate getDocumentTemplate();
0218:
0219: /**
0220: * Returns the <code>org.w3c.dom.Document</code> wrapped by this object. This is
0221: * the original Xerces document.
0222: *
0223: * @return the wrapped Xerces Document object.
0224: */
0225: public Document getDocument();
0226:
0227: /**
0228: * Returns the document proxy of the owner of this document. This object represents
0229: * the browser document/page that requested (loaded) this document by first time (the owner).
0230: *
0231: * @return the document proxy of the owner of this document.
0232: */
0233: public ClientDocument getClientDocumentOwner();
0234:
0235: /**
0236: * Creates a timer utility object.
0237: *
0238: * @return a timer object.
0239: */
0240: public ItsNatTimer createItsNatTimer();
0241:
0242: /**
0243: * Returns the scripting utility.
0244: *
0245: * @return the scripting utility.
0246: */
0247: public ScriptUtil getScriptUtil();
0248:
0249: /**
0250: * Returns the component manager utility.
0251: *
0252: * @return the component manager.
0253: */
0254: public ItsNatComponentManager getItsNatComponentManager();
0255:
0256: /**
0257: * Informs whether this document is in the load phase.
0258: *
0259: * @return true if this document is in the load phase.
0260: * @see org.itsnat.core.event.ItsNatServletRequestListener#processRequest(ItsNatServletRequest,ItsNatServletResponse)
0261: */
0262: public boolean isLoading();
0263:
0264: /**
0265: * Informs whether this document is invalid.
0266: *
0267: * <p>The document is marked as invalid when is unloaded (no more attached to a browser document/page).
0268: * Non-HTML (XML) documents are automatically invalidated after the XML generation.</p>
0269: *
0270: * <p>If invalid the document is not found anymore on session registry ({@link ItsNatSession#getItsNatDocumentById(String)}).
0271: *
0272: * @return true if this document is invalid.
0273: * @see #setInvalid()
0274: */
0275: public boolean isInvalid();
0276:
0277: /**
0278: * Sets this document as invalid.
0279: *
0280: * @see #isInvalid()
0281: */
0282: public void setInvalid();
0283:
0284: /**
0285: * Returns the value associated to the specified attribute name.
0286: *
0287: * <p>This method is symmetric to
0288: * <code>ServletRequest.getAttribute(String)</code> and
0289: * <code>ServletContext.getAttribute(String)</code>.
0290: * </p>
0291: *
0292: * <p>The purpose is to provide a document level attribute registry to complement
0293: * <code>ServletRequest</code> and <code>ServletContext</code> attribute registries.</p>
0294: *
0295: * <p>Is called by {@link ItsNatVariableResolver#getVariable(String)}
0296: * when the variable resolver was created using {@link #createItsNatVariableResolver()}
0297: * and does not contain the specified variable name.
0298: * </p>
0299: *
0300: * @param name the attribute name to search.
0301: * @return the attribute value of null if no attribute exists with the given name.
0302: * @see #setAttribute(String,Object)
0303: * @see #getAttributeNames()
0304: * @see #removeAttribute(String)
0305: */
0306: public Object getAttribute(String name);
0307:
0308: /**
0309: * Registers the specified attribute name and value.
0310: *
0311: * <p>This method is symmetric to
0312: * <code>ServletRequest.setAttribute(String,Object)</code> and
0313: * <code>ServletContext.setAttribute(String,Object)</code>.
0314: * </p>
0315: *
0316: * @param name the attribute name.
0317: * @param value the attribute value.
0318: * @see #getAttribute(String)
0319: */
0320: public void setAttribute(String name, Object value);
0321:
0322: /**
0323: * Returns an enumeration with the registered attribute names and values.
0324: *
0325: * <p>This method is symmetric to
0326: * <code>ServletRequest.getAttributeNames()</code> and
0327: * <code>ServletContext.getAttributeNames()</code>.
0328: * </p>
0329: *
0330: * @return an enumeration with the registered attributes.
0331: * @see #getAttribute(String)
0332: */
0333: public Enumeration getAttributeNames();
0334:
0335: /**
0336: * Unregisters the specified attribute with the given name.
0337: *
0338: * <p>This method is symmetric to
0339: * <code>ServletRequest.removeAttribute(String)</code> and
0340: * <code>ServletContext.removeAttribute(String)</code>.
0341: * </p>
0342: *
0343: * @param name the attribute name.
0344: * @see #getAttribute(String)
0345: */
0346: public void removeAttribute(String name);
0347:
0348: /**
0349: * Creates a variable resolver bound to this document.
0350: *
0351: * @return a variable resolver bound to this document.
0352: */
0353: public ItsNatVariableResolver createItsNatVariableResolver();
0354:
0355: /**
0356: * Registers a new DOM <code>org.w3c.dom.events.EventListener</code> with the
0357: * document default synchronization mode and AJAX timeout, no extra parameters and no custom JavaScript code.
0358: *
0359: *
0360: * @param target target element. Can not be null.
0361: * @param type the DOM event type name (click, change etc).
0362: * @param listener the listener to receive events.
0363: * @param useCapture if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).
0364: * @see #addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long)
0365: */
0366: public void addEventListener(EventTarget target, String type,
0367: EventListener listener, boolean useCapture);
0368:
0369: /**
0370: * Registers a new DOM <code>org.w3c.dom.events.EventListener</code> with no extra
0371: * parameters and no custom JavaScript code, and document default AJAX timeout.
0372: *
0373: *
0374: * @param target target element. Can not be null.
0375: * @param type the DOM event type name (click, change etc).
0376: * @param listener the listener to receive events.
0377: * @param useCapture if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).
0378: * @param syncMode synchronization mode.
0379: * @see #addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long)
0380: */
0381: public void addEventListener(EventTarget target, String type,
0382: EventListener listener, boolean useCapture, int syncMode);
0383:
0384: /**
0385: * Registers a new DOM <code>org.w3c.dom.events.EventListener</code> with
0386: * document default synchronization mode and AJAX timeout, the specified extra
0387: * parameter and no custom JavaScript code.
0388: *
0389: *
0390: * @param target target element. Can not be null.
0391: * @param type the DOM event type name (click, change etc).
0392: * @param listener the listener to receive events.
0393: * @param useCapture if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).
0394: * @param extraParam client to server data transport and synchronization rule.
0395: * @see #addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long)
0396: */
0397: public void addEventListener(EventTarget target, String type,
0398: EventListener listener, boolean useCapture,
0399: ParamTransport extraParam);
0400:
0401: /**
0402: * Registers a new DOM <code>org.w3c.dom.events.EventListener</code> with
0403: * document default synchronization mode and AJAX timeout, the specified extra
0404: * parameters and no custom JavaScript code.
0405: *
0406: *
0407: * @param target target element. Can not be null.
0408: * @param type the DOM event type name (click, change etc).
0409: * @param listener the listener to receive events.
0410: * @param useCapture if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).
0411: * @param extraParams client to server data transport and synchronization rules.
0412: * @see #addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long)
0413: */
0414: public void addEventListener(EventTarget target, String type,
0415: EventListener listener, boolean useCapture,
0416: ParamTransport[] extraParams);
0417:
0418: /**
0419: * Registers a new DOM <code>org.w3c.dom.events.EventListener</code> with
0420: * document default synchronization mode and AJAX timeout, no extra
0421: * parameters and the specified custom JavaScript code.
0422: *
0423: *
0424: * @param target target element. Can not be null.
0425: * @param type the DOM event type name (click, change etc).
0426: * @param listener the listener to receive events.
0427: * @param useCapture if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).
0428: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired.
0429: * @see #addEventListener(EventTarget,String,EventListener,boolean,int,ParamTransport[],String,long)
0430: */
0431: public void addEventListener(EventTarget target, String type,
0432: EventListener listener, boolean useCapture,
0433: String preSendCode);
0434:
0435: /**
0436: * Registers a new DOM <code>org.w3c.dom.events.EventListener</code>.
0437: *
0438: * <p>When this listener is registered the server sends custom JavaScript code to register
0439: * a handler in the client side with the specified node target and DOM event type.
0440: * When an event is fired this handler forwards the client event to the server
0441: * and the registered listener receives an <code>org.w3c.dom.events.Event</code> with
0442: * the same client event data.</p>
0443: *
0444: * <p>If two or more listeners are registered sharing the same node target and event type,
0445: * they all will receive the same event.</p>
0446: *
0447: * @param target target element. Can not be null.
0448: * @param type the DOM event type name (click, change etc).
0449: * @param listener the listener to receive events.
0450: * @param useCapture if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).
0451: * @param syncMode synchronization mode.
0452: * @param extraParams optional client to server data transport and synchronization rules. May be null.
0453: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
0454: * @param ajaxTimeout the timeout of asynchronous AJAX events. If negative no timeout is defined.
0455: * @see #removeEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean)
0456: * @see SyncMode
0457: */
0458: public void addEventListener(EventTarget target, String type,
0459: EventListener listener, boolean useCapture, int syncMode,
0460: ParamTransport[] extraParams, String preSendCode,
0461: long ajaxTimeout);
0462:
0463: /**
0464: * Removes the listener registration with the specified node target, name, listener and capture.
0465: *
0466: *
0467: * @param target the target element. Can not be null.
0468: * @param type the DOM event type name.
0469: * @param listener the registered listener.
0470: * @param useCapture event capture mode.
0471: * @see #addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long)
0472: */
0473: public void removeEventListener(EventTarget target, String type,
0474: EventListener listener, boolean useCapture);
0475:
0476: /**
0477: * Registers a new DOM <code>org.w3c.dom.events.EventListener</code> to receive any node mutation
0478: * as a mutation event fired by the client, using the default document synchronization mode and AJAX timeout
0479: * and no custom JavaScript code.
0480: *
0481: * @param target target element. Can not be null.
0482: * @param listener the listener to receive events.
0483: * @param useCapture if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).
0484: * @see #addMutationEventListener(org.w3c.dom.events.EventTarget,org.w3c.dom.events.EventListener,boolean,int,String,long)
0485: */
0486: public void addMutationEventListener(EventTarget target,
0487: EventListener listener, boolean useCapture);
0488:
0489: /**
0490: * Registers a new DOM <code>org.w3c.dom.events.EventListener</code> to receive any node mutation
0491: * as a mutation event fired by the client.
0492: *
0493: * <p>When a mutation event is received, this event carries the necessary
0494: * data to synchronize the server target element with the client. After this
0495: * automatic synchronization the listener is called.
0496: *
0497: * <p>Current implementation does the following:</p>
0498: * <blockquote><pre>
0499: * ParamTransport[] params = new ParamTransport[]{ new ClientMutation() };
0500: * addEventListener(target,"DOMAttrModified",listener,useCapture,syncMode,params,preSendCode,ajaxTimeout);
0501: * addEventListener(target,"DOMNodeInserted",listener,useCapture,syncMode,params,preSendCode,ajaxTimeout);
0502: * addEventListener(target,"DOMNodeRemoved",listener,useCapture,syncMode,params,preSendCode,ajaxTimeout);
0503: * addEventListener(target,"DOMCharacterDataModified",listener,useCapture,syncMode,params,preSendCode,ajaxTimeout);
0504: * </pre></blockquote>
0505: *
0506: * <p>If the target is the org.w3c.dom.Document object, every document change in the client
0507: * us automatically synchronized in the server.</p>
0508: *
0509: * <p>Mutation events only works with Mozilla/FireFox (MSIE 6 does not support W3C DOM mutation events).</p>
0510: *
0511: *
0512: * @param target target element. Can not be null.
0513: * @param listener the listener to receive events.
0514: * @param useCapture if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).
0515: * @param syncMode synchronization mode.
0516: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
0517: * @param ajaxTimeout the timeout of asynchronous AJAX events. If negative no timeout is defined.
0518: * @see #removeMutationEventListener(org.w3c.dom.events.EventTarget,org.w3c.dom.events.EventListener,boolean)
0519: * @see #addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long)
0520: */
0521: public void addMutationEventListener(EventTarget target,
0522: EventListener listener, boolean useCapture, int syncMode,
0523: String preSendCode, long ajaxTimeout);
0524:
0525: /**
0526: * Removes the mutation listener registration with the specified node target, listener and capture.
0527: *
0528: *
0529: * @param target the target element. Can not be null.
0530: * @param listener the registered listener.
0531: * @param useCapture event capture mode.
0532: * @see #addMutationEventListener(org.w3c.dom.events.EventTarget,org.w3c.dom.events.EventListener,boolean,int,String,long)
0533: */
0534: public void removeMutationEventListener(EventTarget target,
0535: EventListener listener, boolean useCapture);
0536:
0537: /**
0538: * Registers a "continue" <code>EventListener</code>.
0539: *
0540: * <p>When this listener is registered the server sends custom JavaScript code to fire automatically
0541: * a {@link org.itsnat.core.event.ContinueEvent} sent to the listener. This event usually carries
0542: * client data necesary to continue a pending server task (and any JavaScript code sent to the client
0543: * prior to register the listener was executed, this new client state may be the carried data if any).</p>
0544: *
0545: * <p>There is no "remove listener" method because the listener is automatically
0546: * removed when receives and processes the event.</p>
0547: *
0548: *
0549: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
0550: * @param listener the listener to receive the event.
0551: * @param syncMode synchronization mode.
0552: * @param extraParams optional client to server data transport and synchronization rules. May be null.
0553: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
0554: * @param ajaxTimeout the timeout of asynchronous AJAX events. If negative no timeout is defined.
0555: * @see SyncMode
0556: */
0557: public void addContinueEventListener(EventTarget target,
0558: EventListener listener, int syncMode,
0559: ParamTransport[] extraParams, String preSendCode,
0560: long ajaxTimeout);
0561:
0562: /**
0563: * Executes the specified <code>task</code> in a new thread and ensures that any DOM modification performed by this task
0564: * is sent to the client asynchronously when the task ends. Max wait is specified.
0565: *
0566: * <p>If <code>lockDoc</code> is true this document is synchronized during
0567: * the task execution, but if <code>lockDoc</code> is false the task code
0568: * must synchronize the document before any access.</p>
0569: *
0570: * <p>In a long running task is highly recommended to set <code>lockDoc</code>
0571: * as false to avoid a long document lock.</p>
0572: *
0573: * @param task the task to execute in a new thread.
0574: * @param lockDoc whether the document is synchronized by the framework.
0575: * @param maxWait maximum time in milliseconds to wait until the task ends. 0 means unlimited wait.
0576: * @param ajaxTimeout the timeout for the AJAX request used to notify the client. If negative no timeout is defined.
0577: */
0578: public void addAsynchronousTask(Runnable task, boolean lockDoc,
0579: int maxWait, long ajaxTimeout);
0580:
0581: /**
0582: * Executes the specified <code>task</code> in a new thread and ensures that any DOM modification performed by this task
0583: * is sent to the client asynchronously when the task ends. Waits indefinitely.
0584: *
0585: * @param task the task to execute in a new thread.
0586: * @param lockDoc whether the document is synchronized by the framework.
0587: * @see #addAsynchronousTask(Runnable,boolean,int,long)
0588: */
0589: public void addAsynchronousTask(Runnable task, boolean lockDoc);
0590:
0591: /**
0592: * Registers a "user" <code>EventListener</code>.
0593: *
0594: * <p>When this listener is registered the server sends custom JavaScript code to register
0595: * a handler in the client side with the specified node target and name.</p>
0596: *
0597: * <p>User events are fired in the client calling the ItsNat JavaScript method
0598: * <code>fireUserEvent(targetNode,name,args)</code>. For instance:</p>
0599: *
0600: * <code>document.getItsNatDoc().fireUserEvent(document.body,"myUserAction",[ document.title, document.location ]);</code>
0601: *
0602: * <p>Target node and name must be the same parameters used to register the listener.
0603: * {@link org.itsnat.core.event.ParamTransport} objects may be used
0604: * to transport client data (args parameter).</p>
0605: *
0606: * <p>If two or more listeners are registered sharing the same node target and name,
0607: * they all will receive the same event fired by <code>fireUserEvent</code> with this
0608: * target/name pair.</p>
0609: *
0610: *
0611: * @param target target element. Can not be null.
0612: * @param name the user defined event type name.
0613: * @param listener the listener to receive events.
0614: * @param syncMode synchronization mode.
0615: * @param extraParams optional client to server data transport and synchronization rules. May be null.
0616: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
0617: * @param ajaxTimeout the timeout of asynchronous AJAX events. If negative no timeout is defined.
0618: * @see #removeUserEventListener(org.w3c.dom.events.EventTarget,String,EventListener)
0619: * @see #addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long)
0620: * @see SyncMode
0621: */
0622: public void addUserEventListener(EventTarget target, String name,
0623: EventListener listener, int syncMode,
0624: ParamTransport[] extraParams, String preSendCode,
0625: long ajaxTimeout);
0626:
0627: /**
0628: * Registers a "user" <code>EventListener</code>.
0629: *
0630: * <p>This method calls {@link #addUserEventListener(EventTarget,String,EventListener,int,ParamTransport[],String,long)}
0631: * with the document default values (sync mode, AJAX timeout) and no extra parameters and custom code.</p>
0632: *
0633: *
0634: * @param target target element. Can not be null.
0635: * @param name the user defined event type name.
0636: * @param listener the listener to receive events.
0637: */
0638: public void addUserEventListener(EventTarget target, String name,
0639: EventListener listener);
0640:
0641: /**
0642: * Removes the listener registration with the specified node target, name and listener.
0643: *
0644: *
0645: * @param target the target element. Can not be null.
0646: * @param name the user defined event type name.
0647: * @param listener the registered listener.
0648: * @see #addUserEventListener(org.w3c.dom.events.EventTarget,String,EventListener,int,org.itsnat.core.event.ParamTransport[],String,long)
0649: */
0650: public void removeUserEventListener(EventTarget target,
0651: String name, EventListener listener);
0652:
0653: /**
0654: * Add JavaScript code to send to any client (owner or viewers) bound to this document (pending code).
0655: * This code is distributed to the clients calling {@link ClientDocument#addCodeToSend(Object)}.
0656: *
0657: * @param code the code to send, <code>Object.toString()</code> is called to convert to string.
0658: * @see #isSendCodeEnabled()
0659: * @see org.itsnat.core.script.ScriptUtil
0660: * @throws ItsNatException if no code can be added.
0661: */
0662: public void addCodeToSend(Object code);
0663:
0664: /**
0665: * Informs whether JavaScript code can be added to send to the client
0666: * calling {@link #addCodeToSend(Object)}
0667: *
0668: * @return true if new code can be added.
0669: * @see #disableSendCode()
0670: */
0671: public boolean isSendCodeEnabled();
0672:
0673: /**
0674: * Disables the {@link #addCodeToSend(Object)} method, no new code can be added
0675: * to send to the client.
0676: *
0677: * @see #enableSendCode()
0678: */
0679: public void disableSendCode();
0680:
0681: /**
0682: * Enables the {@link #addCodeToSend(Object)} method, new code can be added
0683: * to send to the client.
0684: *
0685: * @see #disableSendCode()
0686: */
0687: public void enableSendCode();
0688:
0689: /**
0690: * Registers a new <code>CodeToSendListener</code>, this listener is called
0691: * every time {@link #addCodeToSend(Object)} is called.
0692: *
0693: * @param listener the new listener.
0694: * @see #removeCodeToSendListener(CodeToSendListener)
0695: */
0696: public void addCodeToSendListener(CodeToSendListener listener);
0697:
0698: /**
0699: * Removes a previously registered <code>CodeToSendListener</code>.
0700: *
0701: * @param listener the new listener.
0702: * @see #addCodeToSendListener(CodeToSendListener)
0703: */
0704: public void removeCodeToSendListener(CodeToSendListener listener);
0705:
0706: /**
0707: * Creates a DOM element list manager. Initial DOM list may be not empty
0708: * and child elements may have different tag names.
0709: *
0710: * @param parentElement the parent element of the list.
0711: * @param master if true only the manager must be used to make structural changes (add, remove or replace elements), avoiding direct DOM manipulation.
0712: * @return the element list.
0713: * @see #createElementList(org.w3c.dom.Element,boolean,org.itsnat.core.domutil.ElementListStructure,org.itsnat.core.domutil.ElementListRenderer)
0714: */
0715: public ElementListFree createElementListFree(Element parentElement,
0716: boolean master);
0717:
0718: /**
0719: * Creates a DOM element table manager. Initial DOM table may be not empty
0720: * and row elements and cells may have different tag names.
0721: *
0722: * @param parentElement the parent element of the table.
0723: * @param master if true only the manager must be used to make structural changes (add, remove or replace elements), avoiding direct DOM manipulation.
0724: * @return the element table.
0725: * @see #createElementTable(org.w3c.dom.Element,boolean,org.itsnat.core.domutil.ElementTableStructure,org.itsnat.core.domutil.ElementTableRenderer)
0726: */
0727: public ElementTableFree createElementTableFree(
0728: Element parentElement, boolean master);
0729:
0730: /**
0731: * Creates a pattern based DOM element label. The content of the element is used as the pattern to render the first
0732: * value.
0733: *
0734: * @param parentElement the parent element of the label.
0735: * @param removePattern if true the current content is removed, otherwise the label shows the current content.
0736: * @param renderer the used label renderer. If null the default renderer is used.
0737: * @return the element label.
0738: */
0739: public ElementLabel createElementLabel(Element parentElement,
0740: boolean removePattern, ElementLabelRenderer renderer);
0741:
0742: /**
0743: * Creates a pattern based DOM element list. The first child element is used as the pattern to create new
0744: * child elements.
0745: *
0746: * @param parentElement the parent element of the list.
0747: * @param removePattern if true the current content (the pattern as minimun) is removed, otherwise the list represents the current content.
0748: * @param structure the used list structure. If null the default structure is used.
0749: * @param renderer the used list renderer. If null the default renderer is used.
0750: * @return the element list.
0751: * @see #createElementList(org.w3c.dom.Element,boolean)
0752: * @see #createElementListFree(Element,boolean)
0753: */
0754: public ElementList createElementList(Element parentElement,
0755: boolean removePattern, ElementListStructure structure,
0756: ElementListRenderer renderer);
0757:
0758: /**
0759: * Creates a pattern based DOM element list. The first child element is used as the pattern to create new
0760: * child elements. The list uses the default structure and renderer.
0761: *
0762: * @param parentElement the parent element of the list.
0763: * @param removePattern if true the current content (the pattern as minimun) is removed, otherwise the list represents the current content.
0764: * @return the element list.
0765: * @see #createElementList(org.w3c.dom.Element,boolean,org.itsnat.core.domutil.ElementListStructure,org.itsnat.core.domutil.ElementListRenderer)
0766: * @see #createDefaultElementListStructure()
0767: * @see #createDefaultElementListRenderer()
0768: */
0769: public ElementList createElementList(Element parentElement,
0770: boolean removePattern);
0771:
0772: /**
0773: * Creates a pattern based DOM element table. The first child element is used as the row pattern and the first
0774: * element cell is the cell pattern used to create new cells (columns).
0775: *
0776: * @param parentElement the parent element of the table.
0777: * @param removePattern if true the current content (the first row as minimu) is removed, otherwise the table represents the current content.
0778: * @param structure the used table structure. If null the default structure is used.
0779: * @param renderer the used table renderer. If null the default renderer is used.
0780: * @return the element table.
0781: * @see #createElementTable(org.w3c.dom.Element,boolean)
0782: * @see #createElementTableFree(Element,boolean)
0783: */
0784: public ElementTable createElementTable(Element parentElement,
0785: boolean removePattern, ElementTableStructure structure,
0786: ElementTableRenderer renderer);
0787:
0788: /**
0789: * Creates a pattern based DOM element table. The first child element is used as the row pattern and the first
0790: * element cell is the cell pattern used to create new cells (columns).
0791: * The table uses the default structure and renderer.
0792: *
0793: * @param parentElement the parent element of the table.
0794: * @param removePattern if true the current content (the first row as minimu) is removed, otherwise the table represents the current content.
0795: * @return the element table.
0796: * @see #createElementTable(org.w3c.dom.Element,boolean,org.itsnat.core.domutil.ElementTableStructure,org.itsnat.core.domutil.ElementTableRenderer)
0797: * @see #createDefaultElementTableStructure()
0798: * @see #createDefaultElementTableRenderer()
0799: */
0800: public ElementTable createElementTable(Element parentElement,
0801: boolean removePattern);
0802:
0803: /**
0804: * Creates a pattern based DOM element tree node. This node is the fixed root of the tree.
0805: *
0806: * @param parentElement the parent element of the node and tree.
0807: * @param removePattern if true the pattern of child nodes (the first child if any) is removed, otherwise the child node list represents the current child node list.
0808: * @param structure the used tree node structure. If null the default structure is used.
0809: * @param renderer the used tree node renderer. If null the default renderer is used.
0810: * @return the element tree node.
0811: * @see #createElementTreeNode(org.w3c.dom.Element,boolean)
0812: * @see #createElementTree(boolean,Element,boolean,ElementTreeNodeStructure,ElementTreeNodeRenderer)
0813: * @see #createElementTreeNodeList(boolean,Element,boolean,ElementTreeNodeStructure,ElementTreeNodeRenderer)
0814: */
0815: public ElementTreeNode createElementTreeNode(Element parentElement,
0816: boolean removePattern, ElementTreeNodeStructure structure,
0817: ElementTreeNodeRenderer renderer);
0818:
0819: /**
0820: * Creates a pattern based DOM element tree node. This node is the fixed (non-removable) root of the tree.
0821: * The tree node uses the default structure and renderer.
0822: *
0823: * @param parentElement the parent element of the node and tree.
0824: * @param removePattern if true the pattern of child nodes (the first child if any) is removed, otherwise the child node list represents the current child node list.
0825: * @return the element tree node.
0826: * @see #createElementTreeNode(org.w3c.dom.Element,boolean,ElementTreeNodeStructure,ElementTreeNodeRenderer)
0827: * @see #createDefaultElementTreeNodeStructure()
0828: * @see #createDefaultElementTreeNodeRenderer()
0829: */
0830: public ElementTreeNode createElementTreeNode(Element parentElement,
0831: boolean removePattern);
0832:
0833: /**
0834: * Creates a pattern based DOM element tree. The root node is the only one top level node
0835: * and is not fixed (removable).
0836: *
0837: * @param treeTable if true the tree is a tree-table structurally.
0838: * @param parentElement the parent element of the tree.
0839: * @param removePattern if true the first node (the root node used as pattern) is removed, otherwise this node is the root.
0840: * @param structure the used tree node structure. If null the default structure is used.
0841: * @param renderer the used tree node renderer. If null the default renderer is used.
0842: * @return the element tree.
0843: * @see #createElementTree(boolean,Element,boolean)
0844: * @see #createElementTreeNode(org.w3c.dom.Element,boolean,ElementTreeNodeStructure,ElementTreeNodeRenderer)
0845: * @see #createElementTreeNodeList(boolean,Element,boolean,ElementTreeNodeStructure,ElementTreeNodeRenderer)
0846: */
0847: public ElementTree createElementTree(boolean treeTable,
0848: Element parentElement, boolean removePattern,
0849: ElementTreeNodeStructure structure,
0850: ElementTreeNodeRenderer renderer);
0851:
0852: /**
0853: * Creates a pattern based DOM element tree. The root node is the only one top level node
0854: * and is not fixed (removable). The tree uses the default structure and renderer.
0855: *
0856: * @param treeTable if true the tree is a tree-table structurally.
0857: * @param parentElement the parent element of the tree.
0858: * @param removePattern if true the first tree node (used as pattern) is removed, otherwise this node is the root.
0859: * @return the element tree.
0860: * @see #createElementTree(boolean,Element,boolean,ElementTreeNodeStructure,ElementTreeNodeRenderer)
0861: * @see #createDefaultElementTreeNodeStructure()
0862: * @see #createDefaultElementTreeNodeRenderer()
0863: */
0864: public ElementTree createElementTree(boolean treeTable,
0865: Element parentElement, boolean removePattern);
0866:
0867: /**
0868: * Creates a pattern based rootless DOM element tree.
0869: *
0870: * @param treeTable if true the tree is a tree-table structurally.
0871: * @param parentElement the parent element of the tree.
0872: * @param removePattern if true the first child node is removed, otherwise the tree represents the current content (current top child nodes).
0873: * @param structure the used tree node structure. If null the default structure is used.
0874: * @param renderer the used tree node renderer. If null the default renderer is used.
0875: * @return the rootless element tree.
0876: * @see #createElementTreeNodeList(boolean,Element,boolean)
0877: * @see #createElementTreeNode(org.w3c.dom.Element,boolean,ElementTreeNodeStructure,ElementTreeNodeRenderer)
0878: * @see #createElementTree(boolean,Element,boolean,ElementTreeNodeStructure,ElementTreeNodeRenderer)
0879: */
0880: public ElementTreeNodeList createElementTreeNodeList(
0881: boolean treeTable, Element parentElement,
0882: boolean removePattern, ElementTreeNodeStructure structure,
0883: ElementTreeNodeRenderer renderer);
0884:
0885: /**
0886: * Creates a pattern based rootless DOM element tree. The tree uses the default structure and renderer.
0887: *
0888: * @param treeTable if true the tree is a tree-table structurally.
0889: * @param parentElement the parent element of the tree.
0890: * @param removePattern if true the first child node is removed, otherwise the tree represents the current content (current top child nodes).
0891: * @return the rootless element tree.
0892: * @see #createElementTreeNodeList(boolean,Element,boolean,ElementTreeNodeStructure,ElementTreeNodeRenderer)
0893: * @see #createDefaultElementTreeNodeStructure()
0894: * @see #createDefaultElementTreeNodeRenderer()
0895: */
0896: public ElementTreeNodeList createElementTreeNodeList(
0897: boolean treeTable, Element parentElement,
0898: boolean removePattern);
0899:
0900: /**
0901: * Creates the default DOM element renderer. This renderer writes the specified value
0902: * as a string into the first found text node.
0903: *
0904: * @return the default renderer.
0905: */
0906: public ElementRenderer createDefaultElementRenderer();
0907:
0908: /**
0909: * Creates the default DOM element label renderer. This renderer uses
0910: * the default {@link org.itsnat.core.domutil.ElementRenderer} to
0911: * render the specified value.
0912: *
0913: * @return the default renderer.
0914: */
0915: public ElementLabelRenderer createDefaultElementLabelRenderer();
0916:
0917: /**
0918: * Creates the default DOM element list renderer. This renderer uses
0919: * the default {@link org.itsnat.core.domutil.ElementRenderer} to
0920: * render the specified value.
0921: *
0922: * @return the default renderer.
0923: */
0924: public ElementListRenderer createDefaultElementListRenderer();
0925:
0926: /**
0927: * Creates the default DOM element table renderer. This renderer uses
0928: * the default {@link org.itsnat.core.domutil.ElementRenderer} to
0929: * render the specified value.
0930: *
0931: * @return the default renderer.
0932: */
0933: public ElementTableRenderer createDefaultElementTableRenderer();
0934:
0935: /**
0936: * Creates the default DOM element table renderer. This renderer uses
0937: * the default {@link org.itsnat.core.domutil.ElementRenderer} to
0938: * render a user value usually into the label element.
0939: *
0940: *
0941: *
0942: * @return the default renderer.
0943: */
0944: public ElementTreeNodeRenderer createDefaultElementTreeNodeRenderer();
0945:
0946: /**
0947: * Creates the default DOM element list structure. This structure
0948: * returns as content element the <td> element if the
0949: * item parent is a <tr> otherwise the item parent element.
0950: *
0951: * @return the default structure.
0952: */
0953: public ElementListStructure createDefaultElementListStructure();
0954:
0955: /**
0956: * Creates the default DOM element table structure. This structure
0957: * returns as row content element the row parent element (itself),
0958: * and as cell content element the cell parent element (itself).
0959: *
0960: * @return the default structure.
0961: */
0962: public ElementTableStructure createDefaultElementTableStructure();
0963:
0964: /**
0965: * Creates the default DOM element tree node structure. This structure
0966: * is flexible enough to deal with several scenarios like tree-table,
0967: * no handle and icon etc.
0968: *
0969: * <p>The reference manual explains with examples
0970: * how this default structure works.</p>
0971: *
0972: * @return the default structure.
0973: */
0974: public ElementTreeNodeStructure createDefaultElementTreeNodeStructure();
0975:
0976: /**
0977: * Returns the {@link ItsNatNode} object wrapping the specified object. The
0978: * returned object instance is ever the same for every concrete node and can be casted
0979: * to org.w3c.dom.Node.
0980: *
0981: * <p>If the specified node is already an {@link ItsNatNode} returns self.
0982: *
0983: * @return the wrapper node.
0984: */
0985: public ItsNatNode getItsNatNode(Node node);
0986:
0987: /**
0988: * Registers an artifact with the specified name.
0989: *
0990: * @param name the artifact name
0991: * @param value the artifact.
0992: * @see #getArtifact(String)
0993: * @see #removeArtifact(String)
0994: * @see org.itsnat.core.NameValue
0995: */
0996: public void registerArtifact(String name, Object value);
0997:
0998: /**
0999: * Returns the artifact with the specified name.
1000: *
1001: * @param name the artifact name to look for.
1002: * @return the artifact or null if not found.
1003: * @see #registerArtifact(String,Object)
1004: * @see #getArtifact(String,boolean)
1005: */
1006: public Object getArtifact(String name);
1007:
1008: /**
1009: * Removes the artifact with the specified name.
1010: *
1011: * @param name the artifact name to look for.
1012: * @return the removed artifact.
1013: * @see #registerArtifact(String,Object)
1014: */
1015: public Object removeArtifact(String name);
1016:
1017: /**
1018: * Returns the artifact with the specified name.
1019: *
1020: * <p>If no artifact is found and <code>cascade</code> is true,
1021: * the method {@link DocumentTemplate#getArtifact(String,boolean)}
1022: * is called with <code>cascade</code> set to true to continue searching.</p>
1023: *
1024: * @param name the artifact name to look for.
1025: * @return the artifact or null if not found.
1026: * @see #getArtifact(String)
1027: */
1028: public Object getArtifact(String name, boolean cascade);
1029:
1030: /**
1031: * Adds a remote control listener to this document. This listener is called when a remote view/control
1032: * is requested to control a document loaded using this template.
1033: *
1034: * @param listener the listener to add.
1035: * @see #removeRemoteControlEventListener(RemoteControlEventListener)
1036: * @see ItsNatServlet#addRemoteControlEventListener(RemoteControlEventListener)
1037: * @see DocumentTemplate#addRemoteControlEventListener(RemoteControlEventListener)
1038: */
1039: public void addRemoteControlEventListener(
1040: RemoteControlEventListener listener);
1041:
1042: /**
1043: * Removes the specified remote control listener.
1044: *
1045: * @param listener the listener to remove.
1046: * @see #addRemoteControlEventListener(RemoteControlEventListener)
1047: */
1048: public void removeRemoteControlEventListener(
1049: RemoteControlEventListener listener);
1050:
1051: /**
1052: * Dispatches the specified event to the specified node target.
1053: *
1054: * <p>If the current thread was not started calling {@link ClientDocument#startEventDispatcherThread(Runnable)}
1055: * current implementation calls {@link #dispatchEventLocally(EventTarget,Event)},
1056: * otherwise calls {@link ClientDocument#dispatchEvent(EventTarget,Event,int,long)} using
1057: * document default synchronous mode ({@link #getDefaultSyncMode()}) and AJAX timeout ({@link #getAJAXTimeout()}).
1058: * </p>
1059: *
1060: * <p>This method is called by the enhanced version of the method
1061: * <code>org.w3c.dom.events.EventTarget#dispatchEvent(Event)</code>
1062: * called with the enhanced node returned by {@link #getItsNatNode(Node)}
1063: * </p>
1064: *
1065: * @param target the event target DOM object.
1066: * @param evt the DOM event to send to target.
1067: */
1068: public boolean dispatchEvent(EventTarget target, Event evt)
1069: throws EventException;
1070:
1071: /**
1072: * Dispatches the specified event to the specified node target directly on the server.
1073: *
1074: * <p>The event is routed across the server DOM tree and dispatched to listeners as specified by the W3C DOM Events
1075: * standard including bubbling and capturing.
1076: * </p>
1077: *
1078: * @param target the event target DOM object.
1079: * @param evt the DOM event to send to target.
1080: */
1081: public boolean dispatchEventLocally(EventTarget target, Event evt)
1082: throws EventException;
1083:
1084: /**
1085: * Returns the date when this object was created.
1086: *
1087: * @return the creation date.
1088: */
1089: public Date getCreationDate();
1090:
1091: /**
1092: * Registers a new ItsNat referrer request listener. This listener is called when the framework loads
1093: * a new target document and this document is being unloaded <i>before</i> the target request listeners are executed
1094: * (referrer push).
1095: *
1096: * @param listener the listener to register.
1097: * @see #removeReferrerItsNatServletRequestListener(ItsNatServletRequestListener)
1098: * @see DocumentTemplate#isReferrerPushEnabled()
1099: */
1100: public void addReferrerItsNatServletRequestListener(
1101: ItsNatServletRequestListener listener);
1102:
1103: /**
1104: * Unregisters the specified user defined referrer request listener.
1105: *
1106: * @param listener the listener to remove.
1107: * @see #addReferrerItsNatServletRequestListener(ItsNatServletRequestListener)
1108: */
1109: public void removeReferrerItsNatServletRequestListener(
1110: ItsNatServletRequestListener listener);
1111: }
|