org.itsnat.core

Interface ItsNatDocument

All Superinterfaces:

ItsNatUserData

All Known Subinterfaces:

ItsNatHTMLDocument

public interface ItsNatDocument
extends ItsNatUserData

Is the ItsNat wrapper of a org.w3c.dom.Document object. Usually represents a web page loaded by a client.

Provides many useful utilities to simulate "The Browser Is The Server" approach of ItsNat like event listener registries. Is the factory of DOM utility objects and ItsNat components.

ItsNat document objects are created using a ItsNatDocumentTemplate as pattern and usually obtained calling ItsNatServletRequest.getItsNatDocument() or ItsNatServletResponse.getItsNatDocument() when a new document (page) is loading or calling ItsNatEvent.getItsNatDocument() when an event is received.

Is not thread save and any object depending on this document (DOM utility objects, components etc) is not thread save too. This is not a problem because any ItsNat request/response thread synchronizes this object before calling user defined code, user defined code executed by an ItsNat request/response thread may be unaware of synchronization isues.

Author:

Jose Maria Arranz Santamaria

Method Summary

Methods

Modifier and Type	Method and Description
void	addCodeToSend(Object code) Add JavaScript code to send to any client (owner or remote control) bound to this document (pending code).
void	addCodeToSendListener(CodeToSendListener listener) Registers a new CodeToSendListener, this listener is called every time addCodeToSend(Object) is called.
void	addEventListener(EventListener listener) Adds a global event listener to this document.
void	addEventListener(EventTarget target, String type, EventListener listener, boolean useCapture) Registers a new DOM org.w3c.dom.events.EventListener with the document default communication mode and timeout, no extra parameters and no custom JavaScript code.
void	addEventListener(EventTarget target, String type, EventListener listener, boolean useCapture, int commMode) Registers a new DOM org.w3c.dom.events.EventListener with no extra parameters and no custom JavaScript code, and document default event timeout.
void	addEventListener(EventTarget target, String type, EventListener listener, boolean useCapture, int commMode, ParamTransport[] extraParams, String preSendCode, long eventTimeout) Registers a new DOM org.w3c.dom.events.EventListener.
void	addEventListener(EventTarget target, String type, EventListener listener, boolean useCapture, ParamTransport extraParam) Registers a new DOM org.w3c.dom.events.EventListener with document default communication mode and timeout, the specified extra parameter and no custom JavaScript code.
void	addEventListener(EventTarget target, String type, EventListener listener, boolean useCapture, ParamTransport[] extraParams) Registers a new DOM org.w3c.dom.events.EventListener with document default communication mode and timeout, the specified extra parameters and no custom JavaScript code.
void	addEventListener(EventTarget target, String type, EventListener listener, boolean useCapture, String preSendCode) Registers a new DOM org.w3c.dom.events.EventListener with document default communication mode and event timeout, no extra parameters and the specified custom JavaScript code.
void	addItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener listener) Adds a remote control listener to this document.
void	addMutationEventListener(EventTarget target, EventListener listener, boolean useCapture) Registers a new DOM org.w3c.dom.events.EventListener to receive any node mutation as a mutation event fired by the client, using the default communication mode and timeout of the document and no custom JavaScript code.
void	addMutationEventListener(EventTarget target, EventListener listener, boolean useCapture, int commMode, String preSendCode, long eventTimeout) Registers a new DOM org.w3c.dom.events.EventListener to receive any node mutation as a mutation event fired by the client.
void	addReferrerItsNatServletRequestListener(ItsNatServletRequestListener listener) Registers a new ItsNat referrer request listener.
void	addUserEventListener(EventTarget target, String name, EventListener listener) Registers a "user" EventListener.
void	addUserEventListener(EventTarget target, String name, EventListener listener, int commMode, ParamTransport[] extraParams, String preSendCode, long eventTimeout) Registers a "user" EventListener.
Event	createEvent(String eventType) Create a remote event to be dispatched locally or to the client.
ItsNatVariableResolver	createItsNatVariableResolver() Creates a variable resolver bound to this document.
ItsNatVariableResolver	createItsNatVariableResolver(boolean disconnected) Creates a variable resolver bound to this document if the disconnected parameter is set to false.
void	disableSendCode() Disables the addCodeToSend(Object) method, no new code can be added to send to the client.
Node	disconnectChildNodesFromClient(Node node) Removes the child nodes of the specified node to save server memory but not in client.
boolean	dispatchEvent(EventTarget target, Event evt) Dispatches the specified event to the specified node target.
boolean	dispatchEventLocally(EventTarget target, Event evt) Dispatches the specified event to the specified node target directly on the server.
void	enableSendCode() Enables the addCodeToSend(Object) method, new code can be added to send to the client.
Object	getArtifact(String name) Returns the artifact with the specified name.
Object	getArtifact(String name, boolean cascade) Returns the artifact with the specified name.
Object	getAttribute(String name) Returns the value associated to the specified attribute name.
Enumeration<String>	getAttributeNames() Returns an enumeration with the registered attribute names and values.
ClientDocument	getClientDocumentOwner() Returns the document proxy of the owner of this document.
int	getCommMode() Returns the default communication mode, AJAX or SCRIPT, for events.
Node	getContainerNode() Returns the node containing this document.
long	getCreationTime() Returns the time in milliseconds when this object was created.
DateFormat	getDefaultDateFormat() Returns the default data format used by components such as ItsNatHTMLInputTextFormatted.
NumberFormat	getDefaultNumberFormat() Returns the default number format used by components such as ItsNatHTMLInputTextFormatted.
Document	getDocument() Returns the org.w3c.dom.Document wrapped by this object.
ElementGroupManager	getElementGroupManager() Returns the element group manager utility.
long	getEventDispatcherMaxWait() Returns the default max wait until a server fired event calling ClientDocument.dispatchEvent(org.w3c.dom.events.EventTarget,org.w3c.dom.events.Event,int,long) is processed by the client and returns.
long	getEventTimeout() Returns the default timeout in client of asynchronous AJAX/SCRIPT events.
String	getId() Returns the client identity.
ItsNatComponentManager	getItsNatComponentManager() Returns the component manager utility.
ItsNatDocumentTemplate	getItsNatDocumentTemplate() Returns the template this document is based on.
int	getMaxOpenClientsByDocument() Returns the max number of open clients (owner and attached) associated to a document in server.
ScriptUtil	getScriptUtil() Returns the scripting utility.
boolean	isCreatedByStatelessEvent() If this document was created when processing a stateless event, that is, it was loaded as the result of processing a stateless event fired with a JavaScript call document.getItsNatDoc().dispatchEventStateless(...); provided a itsnat_doc_name parameter.
boolean	isDisconnectedChildNodesFromClient(Node node) Informs whether the specified node is marked as "child nodes disconnected"
boolean	isInvalid() Informs whether this document is invalid.
boolean	isJoystickMode() Informs whether a joystick is enough to control, for instance, components (some kind of mouse, pointer or stylus not present or not necessary).
boolean	isLoading() Informs whether this document is in the load phase.
boolean	isSendCodeEnabled() Informs whether JavaScript code can be added to send to the client calling addCodeToSend(Object)
boolean	isUsePatternMarkupToRender() Informs whether dom utils and components use by default the original (saved as pattern) markup to render.
void	reconnectChildNodesToClient(Node node) Reconnects further new child nodes of the specified node with the client, the child nodes in client are removed and again the client will be in sync with server.
void	registerArtifact(String name, Object value) Registers an artifact with the specified name.
Object	removeArtifact(String name) Removes the artifact with the specified name.
void	removeAttribute(String name) Unregisters the specified attribute with the given name.
void	removeCodeToSendListener(CodeToSendListener listener) Removes a previously registered CodeToSendListener.
void	removeEventListener(EventListener listener) Removes the specified global event listener registered in this document.
void	removeEventListener(EventTarget target, String type, EventListener listener, boolean useCapture) Removes the listener registration with the specified node target, name, listener and capture.
void	removeItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener listener) Removes the specified remote control listener.
void	removeMutationEventListener(EventTarget target, EventListener listener, boolean useCapture) Removes the mutation listener registration with the specified node target, listener and capture.
void	removeReferrerItsNatServletRequestListener(ItsNatServletRequestListener listener) Unregisters the specified user defined referrer request listener.
void	removeUserEventListener(EventTarget target, String name, EventListener listener) Removes the listener registration with the specified node target, name and listener.
void	setAttribute(String name, Object value) Registers the specified attribute name and value.
void	setCommMode(int commMode) Sets the default communication mode, AJAX or SCRIPT, for events.
void	setDefaultDateFormat(DateFormat format) Sets the default data format used by components such as ItsNatHTMLInputTextFormatted.
void	setDefaultNumberFormat(NumberFormat format) Sets the default data format used by components such as ItsNatHTMLInputTextFormatted.
void	setEventDispatcherMaxWait(long wait) Sets the default max wait until a server fired event with ClientDocument.dispatchEvent(org.w3c.dom.events.EventTarget,org.w3c.dom.events.Event,int,long) is processed by the client and returns.
void	setEventTimeout(long timeout) Sets the default timeout of asynchronous AJAX/SCRIPT events.
void	setInvalid() Sets this document as invalid.
void	setJoystickMode(boolean value) Informs whether a joystick is enough to control, for instance, components (some kind of mouse, pointer or stylus not present or not necessary).
void	setMaxOpenClientsByDocument(int value) Sets the max number of open clients (owner and attached) associated to a document in server.
void	setUsePatternMarkupToRender(boolean value) Sets whether dom utils and components use by default the original (saved as pattern) markup to render.
DocumentFragment	toDOM(String code) Parses and converts to DOM the specified string containing markup usually to be inserted into the document.

Methods inherited from interface org.itsnat.core.ItsNatUserData

containsUserValueName, getUserValue, getUserValueNames, removeUserValue, setUserValue

Method Detail

getId

String getId()

Returns the client identity. This value is unique per ItsNatSession and never reused in this context.

The identity value is unique no other session-identified object in the same session shares the same id.

Although this object is garbage collected, the identity value is never reused by another session-identified object in the same session.

Returns:

the identity value.

getContainerNode

Node getContainerNode()

Returns the node containing this document.

This method returns a non-null object if this document was loaded using an <iframe> or <object> or <embed> following the automatic binding technique (the data or src attribute has the format "?itsnat_doc_name=docName&...").

The returned node is owned by a different DOM document (the parent document of this document), use Document.importNode(Node,boolean) to migrate nodes between documents.

Use ItsNatNode.getItsNatDocument() to get the parent ItsNat document

ItsNat documents and dependent objects are single threaded, ItsNat automatically locks the document associated to the web request thread and parent documents, in this case synchronization is not needed.

Returns:

the node containing this document. May be null.

getCommMode

int getCommMode()

Returns the default communication mode, AJAX or SCRIPT, for events. Is used for new event listeners when no communication mode is specified. is specified.

The default value is defined by ItsNatDocumentTemplate.getCommMode()

This feature only affects to non-XML documents with events enabled.

Returns:

the communication mode.

See Also:

setCommMode(int), CommMode

setCommMode

void setCommMode(int commMode)

Sets the default communication mode, AJAX or SCRIPT, for events. Current defined event listeners are not affected.

Parameters:

commMode - the new communication mode.

See Also:

getCommMode()

getEventTimeout

long getEventTimeout()

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

When an unfinished request takes more time than the specified timeout, the request is aborted.

The default value is defined by ItsNatDocumentTemplate.getEventTimeout()

This feature only affects non-XML documents with events enabled and is ignored in synchronous AJAX events.

Returns:

the timeout of asynchronous AJAX/SCRIPT events in milliseconds.

See Also:

setEventTimeout(long)

setEventTimeout

void setEventTimeout(long timeout)

Sets the default timeout of asynchronous AJAX/SCRIPT events.

Parameters:

timeout - the new timeout. If negative no timeout is defined.

See Also:

getEventTimeout()

getDefaultDateFormat

DateFormat getDefaultDateFormat()

Returns the default data format used by components such as ItsNatHTMLInputTextFormatted.

The default value is defined by ItsNatDocumentTemplate.getDefaultDateFormat()

Returns:

the default date format.

See Also:

setDefaultDateFormat(DateFormat)

setDefaultDateFormat

void setDefaultDateFormat(DateFormat format)

Sets the default data format used by components such as ItsNatHTMLInputTextFormatted.

Parameters:

format - the default data format.

See Also:

getDefaultDateFormat()

getDefaultNumberFormat

NumberFormat getDefaultNumberFormat()

Returns the default number format used by components such as ItsNatHTMLInputTextFormatted.

The default value is defined by ItsNatDocumentTemplate.getDefaultNumberFormat()

Returns:

the default data format.

See Also:

setDefaultNumberFormat(NumberFormat)

setDefaultNumberFormat

void setDefaultNumberFormat(NumberFormat format)

Sets the default data format used by components such as ItsNatHTMLInputTextFormatted.

Parameters:

format - the default data format.

See Also:

getDefaultNumberFormat()

getEventDispatcherMaxWait

long getEventDispatcherMaxWait()

Returns the default max wait until a server fired event calling ClientDocument.dispatchEvent(org.w3c.dom.events.EventTarget,org.w3c.dom.events.Event,int,long) is processed by the client and returns.

The default value is defined by ItsNatDocumentTemplate.getEventDispatcherMaxWait()

This feature only affects non-XML documents with events enabled.

Returns:

the default max wait in milliseconds.

See Also:

setEventDispatcherMaxWait(long)

setEventDispatcherMaxWait

void setEventDispatcherMaxWait(long wait)

Sets the default max wait until a server fired event with ClientDocument.dispatchEvent(org.w3c.dom.events.EventTarget,org.w3c.dom.events.Event,int,long) is processed by the client and returns.

Parameters:

wait - the default max wait in milliseconds.

See Also:

getEventDispatcherMaxWait()

getMaxOpenClientsByDocument

int getMaxOpenClientsByDocument()

Returns the max number of open clients (owner and attached) associated to a document in server.

This feature only affects to non-XML documents with events enabled

The default value is defined by ItsNatDocumentTemplate.getMaxOpenClientsByDocument()

Returns:

the max number of open clients. Defaults to 10.

setMaxOpenClientsByDocument

void setMaxOpenClientsByDocument(int value)

Sets the max number of open clients (owner and attached) associated to a document in server.

Parameters:

value - the new max number of open clients.

See Also:

getMaxOpenClientsByDocument()

isUsePatternMarkupToRender

boolean isUsePatternMarkupToRender()

Informs whether dom utils and components use by default the original (saved as pattern) markup to render.

The default value is defined by ItsNatDocumentTemplate.isUsePatternMarkupToRender()

Returns:

true if by default the original markup is used.

See Also:

setUsePatternMarkupToRender(boolean)

setUsePatternMarkupToRender

void setUsePatternMarkupToRender(boolean value)

Sets whether dom utils and components use by default the original (saved as pattern) markup to render.

Parameters:

value - true to enable the use of original markup to render.

See Also:

isUsePatternMarkupToRender()

isJoystickMode

boolean isJoystickMode()

Informs whether a joystick is enough to control, for instance, components (some kind of mouse, pointer or stylus not present or not necessary).

The default value is defined by ItsNatDocumentTemplate.isJoystickMode()

This feature only affects to non-XML documents with events enabled.

Returns:

true if joystick mode is on.

See Also:

setJoystickMode(boolean), ItsNatFreeList.isJoystickMode(), ItsNatTable.isJoystickMode(), ItsNatTree.isJoystickMode()

setJoystickMode

void setJoystickMode(boolean value)

Informs whether a joystick is enough to control, for instance, components (some kind of mouse, pointer or stylus not present or not necessary).

This method does not change the current state of already created components but may be the default value of new components with this feature.

Parameters:

value - true to enable joystick mode.

See Also:

isJoystickMode()

isCreatedByStatelessEvent

boolean isCreatedByStatelessEvent()

If this document was created when processing a stateless event, that is, it was loaded as the result of processing a stateless event fired with a JavaScript call document.getItsNatDoc().dispatchEventStateless(...); provided a itsnat_doc_name parameter.

Returns:

true if is a stateless document.

toDOM

DocumentFragment toDOM(String code)

Parses and converts to DOM the specified string containing markup usually to be inserted into the document.

The specified markup must not be a complete document and must be a well-formatted markup fragment.

This method does not perform caching, markup code is ever parsed from the scratch. Use with small markup fragments. For very small fragments use normal DOM methods and for big fragments use the fragment templating system.

Be careful with the security using this method when the string is constructed containing user data. For instance, a malicious user can add unexpected elements like <script>, <link> or <object>. This is not the recommended approach, insert user provided data using DOM APIs after this call.

Parameters:

code - the markup to parse and convert to DOM

Returns:

a document fragment with the result of parsing.

getItsNatDocumentTemplate

ItsNatDocumentTemplate getItsNatDocumentTemplate()

Returns the template this document is based on.

Returns:

the template of this document.

getDocument

Document getDocument()

Returns the org.w3c.dom.Document wrapped by this object.

Returns:

the wrapped DOM Document object.

getClientDocumentOwner

ClientDocument getClientDocumentOwner()

Returns the document proxy of the owner of this document. This object represents the browser document/page that requested (loaded) this document by first time (the owner).

Returns:

the document proxy of the owner of this document.

getScriptUtil

ScriptUtil getScriptUtil()

Returns the scripting utility.

Returns:

the scripting utility.

getItsNatComponentManager

ItsNatComponentManager getItsNatComponentManager()

Returns the component manager utility.

Returns:

the component manager.

isLoading

boolean isLoading()

Informs whether this document is in the load phase.

Returns:

true if this document is in the load phase.

See Also:

ItsNatServletRequestListener.processRequest(ItsNatServletRequest,ItsNatServletResponse)

isInvalid

boolean isInvalid()

Informs whether this document is invalid.

The document is marked as invalid when is unloaded (no more attached to a browser document/page). XML documents are automatically invalidated after loading.

If invalid the document is not found anymore on session registry (ItsNatSession.getItsNatDocumentById(String)).

Returns:

true if this document is invalid.

See Also:

setInvalid()

setInvalid

void setInvalid()

Sets this document as invalid.

See Also:

isInvalid()

getAttribute

Object getAttribute(String name)

Returns the value associated to the specified attribute name.

This method is symmetric to ServletRequest.getAttribute(String) and ServletContext.getAttribute(String).

The purpose is to provide a document level attribute registry to complement ServletRequest and ServletContext attribute registries.

Is called by ItsNatVariableResolver.getVariable(String) when the variable resolver was created using createItsNatVariableResolver() and does not contain the specified variable name.

Parameters:

name - the attribute name to search.

Returns:

the attribute value of null if no attribute exists with the given name.

See Also:

setAttribute(String,Object), getAttributeNames(), removeAttribute(String)

setAttribute

void setAttribute(String name,
                Object value)

Registers the specified attribute name and value.

This method is symmetric to ServletRequest.setAttribute(String,Object) and ServletContext.setAttribute(String,Object).

Parameters:

name - the attribute name.

value - the attribute value.

See Also:

getAttribute(String)

getAttributeNames

Enumeration<String> getAttributeNames()

Returns an enumeration with the registered attribute names and values.

This method is symmetric to ServletRequest.getAttributeNames() and ServletContext.getAttributeNames().

Returns:

an enumeration with the registered attributes.

See Also:

getAttribute(String)

removeAttribute

void removeAttribute(String name)

Unregisters the specified attribute with the given name.

This method is symmetric to ServletRequest.removeAttribute(String) and ServletContext.removeAttribute(String).

Parameters:

name - the attribute name.

See Also:

getAttribute(String)

createItsNatVariableResolver

ItsNatVariableResolver createItsNatVariableResolver()

Creates a variable resolver bound to this document.

Returns:

a variable resolver bound to this document.

See Also:

createItsNatVariableResolver(boolean)

createItsNatVariableResolver

ItsNatVariableResolver createItsNatVariableResolver(boolean disconnected)

Creates a variable resolver bound to this document if the disconnected parameter is set to false.

Set disconnected as true if only local variables of the returned variable resolver must be used (this avoids any attempt to resolve unexpected variables in markup).

Parameters:

disconnected - if the new variable resolver is disconnected from the document.

Returns:

a variable resolver bound to this document.

See Also:

createItsNatVariableResolver()

addEventListener

void addEventListener(EventTarget target,
                    String type,
                    EventListener listener,
                    boolean useCapture)

Registers a new DOM org.w3c.dom.events.EventListener with the document default communication mode and timeout, no extra parameters and no custom JavaScript code.

Parameters:

target - target element. Can not be null.

type - the DOM event type name (click, change etc).

listener - the listener to receive events.

useCapture - if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).

See Also:

addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long), ClientDocument.addEventListener(EventTarget ,String ,EventListener ,boolean )

addEventListener

void addEventListener(EventTarget target,
                    String type,
                    EventListener listener,
                    boolean useCapture,
                    int commMode)

Registers a new DOM org.w3c.dom.events.EventListener with no extra parameters and no custom JavaScript code, and document default event timeout.

Parameters:

target - target element. Can not be null.

type - the DOM event type name (click, change etc).

listener - the listener to receive events.

useCapture - if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).

commMode - communication mode.

See Also:

addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long), ClientDocument.addEventListener(EventTarget ,String ,EventListener ,boolean ,int )

addEventListener

void addEventListener(EventTarget target,
                    String type,
                    EventListener listener,
                    boolean useCapture,
                    ParamTransport extraParam)

Registers a new DOM org.w3c.dom.events.EventListener with document default communication mode and timeout, the specified extra parameter and no custom JavaScript code.

Parameters:

target - target element. Can not be null.

type - the DOM event type name (click, change etc).

listener - the listener to receive events.

useCapture - if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).

extraParam - client to server data transport and synchronization rule.

See Also:

addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long), ClientDocument.addEventListener(EventTarget ,String ,EventListener ,boolean ,ParamTransport )

addEventListener

void addEventListener(EventTarget target,
                    String type,
                    EventListener listener,
                    boolean useCapture,
                    ParamTransport[] extraParams)

Registers a new DOM org.w3c.dom.events.EventListener with document default communication mode and timeout, the specified extra parameters and no custom JavaScript code.

Parameters:

target - target element. Can not be null.

type - the DOM event type name (click, change etc).

listener - the listener to receive events.

useCapture - if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).

extraParams - client to server data transport and synchronization rules.

See Also:

addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long), ClientDocument.addEventListener(EventTarget ,String ,EventListener ,boolean ,ParamTransport[] )

addEventListener

void addEventListener(EventTarget target,
                    String type,
                    EventListener listener,
                    boolean useCapture,
                    String preSendCode)

Registers a new DOM org.w3c.dom.events.EventListener with document default communication mode and event timeout, no extra parameters and the specified custom JavaScript code.

Parameters:

target - target element. Can not be null.

type - the DOM event type name (click, change etc).

listener - the listener to receive events.

useCapture - if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).

preSendCode - custom JavaScript code to execute before an event of this listener type is fired.

See Also:

addEventListener(EventTarget,String,EventListener,boolean,int,ParamTransport[],String,long), ClientDocument.addEventListener(EventTarget ,String ,EventListener ,boolean ,String )

addEventListener

void addEventListener(EventTarget target,
                    String type,
                    EventListener listener,
                    boolean useCapture,
                    int commMode,
                    ParamTransport[] extraParams,
                    String preSendCode,
                    long eventTimeout)

Registers a new DOM org.w3c.dom.events.EventListener.

When this listener is registered the server sends custom JavaScript code to register a handler in the client side with the specified node target and DOM event type. When an event is fired this handler forwards the client event to the server and the registered listener receives an org.w3c.dom.events.Event with the same client event data.

If two or more listeners are registered sharing the same node target and event type, they all will receive the same event.

Parameters:

target - target element. Can not be null.

type - the DOM event type name (click, change etc).

listener - the listener to receive events.

useCapture - if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).

commMode - communication mode.

extraParams - optional client to server data transport and synchronization rules. May be null.

preSendCode - custom JavaScript code to execute before an event of this listener type is fired. May be null.

eventTimeout - the timeout of asynchronous events. If negative no timeout is defined.

See Also:

removeEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean), ClientDocument.addEventListener(EventTarget ,String ,EventListener ,boolean ,int ,ParamTransport[] ,String ,long ), CommMode

removeEventListener

void removeEventListener(EventTarget target,
                       String type,
                       EventListener listener,
                       boolean useCapture)

Removes the listener registration with the specified node target, name, listener and capture.

Parameters:

target - the target element. Can not be null.

type - the DOM event type name.

listener - the registered listener.

useCapture - event capture mode.

See Also:

addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long), ClientDocument.removeEventListener(org.w3c.dom.events.EventTarget, java.lang.String, org.w3c.dom.events.EventListener, boolean)

addMutationEventListener

void addMutationEventListener(EventTarget target,
                            EventListener listener,
                            boolean useCapture)

Registers a new DOM org.w3c.dom.events.EventListener to receive any node mutation as a mutation event fired by the client, using the default communication mode and timeout of the document and no custom JavaScript code.

Parameters:

target - target element. Can not be null.

listener - the listener to receive events.

useCapture - if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).

See Also:

addMutationEventListener(org.w3c.dom.events.EventTarget,org.w3c.dom.events.EventListener,boolean,int,String,long), ClientDocument.addMutationEventListener(org.w3c.dom.events.EventTarget, org.w3c.dom.events.EventListener, boolean)

addMutationEventListener

void addMutationEventListener(EventTarget target,
                            EventListener listener,
                            boolean useCapture,
                            int commMode,
                            String preSendCode,
                            long eventTimeout)

Registers a new DOM org.w3c.dom.events.EventListener to receive any node mutation as a mutation event fired by the client.

When a mutation event is received, this event carries the necessary data to synchronize the server target element with the client. After this automatic synchronization, the listener is called.

Current implementation does the following:

  ParamTransport[] params = new ParamTransport[]{ new ClientMutation() };
        addEventListener(target,"DOMAttrModified",listener,useCapture,commMode,params,preSendCode,eventTimeout);
        addEventListener(target,"DOMNodeInserted",listener,useCapture,commMode,params,preSendCode,eventTimeout);
        addEventListener(target,"DOMNodeRemoved",listener,useCapture,commMode,params,preSendCode,eventTimeout);
        addEventListener(target,"DOMCharacterDataModified",listener,useCapture,commMode,params,preSendCode,eventTimeout);
 

If the target is the org.w3c.dom.Document object, every document change in the client is automatically synchronized in the server.

Mutation events only works with some W3C browses like Mozilla/FireFox, Safari and Opera (MSIE 6 does not support W3C DOM mutation events).

Parameters:

target - target element. Can not be null.

listener - the listener to receive events.

useCapture - if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).

commMode - communication mode.

preSendCode - custom JavaScript code to execute before an event of this listener type is fired. May be null.

eventTimeout - the timeout of asynchronous events. If negative no timeout is defined.

See Also:

removeMutationEventListener(org.w3c.dom.events.EventTarget,org.w3c.dom.events.EventListener,boolean), addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long), ClientDocument.addMutationEventListener(EventTarget ,EventListener ,boolean ,int ,String ,long )

removeMutationEventListener

void removeMutationEventListener(EventTarget target,
                               EventListener listener,
                               boolean useCapture)

Removes the mutation listener registration with the specified node target, listener and capture.

Parameters:

target - the target element. Can not be null.

listener - the registered listener.

useCapture - event capture mode.

See Also:

addMutationEventListener(org.w3c.dom.events.EventTarget,org.w3c.dom.events.EventListener,boolean,int,String,long), ClientDocument.removeMutationEventListener(EventTarget ,EventListener ,boolean )

addUserEventListener

void addUserEventListener(EventTarget target,
                        String name,
                        EventListener listener,
                        int commMode,
                        ParamTransport[] extraParams,
                        String preSendCode,
                        long eventTimeout)

Registers a "user" EventListener.

When this listener is registered the server sends custom JavaScript code to register a handler in the client side with the specified node target and name.

User events are fired in the client calling the ItsNat JavaScript method fireUserEvent(targetNode,name) or dispatchUserEvent(targetNode,evt) (where evt is a special user event see Manual for more info). For instance:

document.getItsNatDoc().fireUserEvent(document.body,"myUserAction");

Target node and name must be the same parameters used to register the listener.

If two or more listeners are registered sharing the same node target and name, they all will receive the same event fired by fireUserEvent with this target/name pair. If a listener instance was already registered and is registered again with the same target and name, this second call does nothing.

Parameters:

target - target element. Can not be null.

name - the user defined event type name.

listener - the listener to receive events.

commMode - communication mode.

extraParams - optional client to server data transport and synchronization rules. May be null.

preSendCode - custom JavaScript code to execute before an event of this listener type is fired. May be null.

eventTimeout - the timeout of asynchronous events. If negative no timeout is defined.

See Also:

removeUserEventListener(org.w3c.dom.events.EventTarget,String,EventListener), addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long), ClientDocument.addUserEventListener(org.w3c.dom.events.EventTarget, java.lang.String, org.w3c.dom.events.EventListener, int, org.itsnat.core.event.ParamTransport[], java.lang.String, long), CommMode

addUserEventListener

void addUserEventListener(EventTarget target,
                        String name,
                        EventListener listener)

Registers a "user" EventListener.

This method calls addUserEventListener(EventTarget,String,EventListener,int,ParamTransport[],String,long) with the document default values (communication mode, event timeout) and no extra parameters and custom code.

Parameters:

target - target element. Can not be null.

name - the user defined event type name.

listener - the listener to receive events.

See Also:

ClientDocument.addUserEventListener(EventTarget ,String ,EventListener )

removeUserEventListener

void removeUserEventListener(EventTarget target,
                           String name,
                           EventListener listener)

Removes the listener registration with the specified node target, name and listener.

Parameters:

target - the target element. Can not be null.

name - the user defined event type name.

listener - the registered listener.

See Also:

addUserEventListener(org.w3c.dom.events.EventTarget,String,EventListener,int,org.itsnat.core.event.ParamTransport[],String,long), ClientDocument.removeUserEventListener(EventTarget ,String ,EventListener)

addEventListener

void addEventListener(EventListener listener)

Adds a global event listener to this document. This listener is called when any DOM event (standard or extended) is received by this document.

The listener is called before calling any DOM event listener registered in this document. This listener registry is passive, in no way the client is modified (no listener is registered on the client) and usually used for monitoring.

Parameters:

listener - the listener to add.

See Also:

removeEventListener(EventListener), ItsNatServlet.addEventListener(EventListener), ItsNatDocumentTemplate.addEventListener(EventListener), ClientDocument.addEventListener(org.w3c.dom.events.EventListener)

removeEventListener

void removeEventListener(EventListener listener)

Removes the specified global event listener registered in this document.

Parameters:

listener - the listener to remove.

See Also:

addEventListener(EventListener), ClientDocument.removeEventListener(org.w3c.dom.events.EventListener)

addCodeToSend

void addCodeToSend(Object code)

Add JavaScript code to send to any client (owner or remote control) bound to this document (pending code). This code is distributed to the clients calling ClientDocument.addCodeToSend(Object).

Parameters:

code - the code to send, Object.toString() is called to convert to string.

Throws:

ItsNatException - if no code can be added.

See Also:

isSendCodeEnabled(), ScriptUtil

isSendCodeEnabled

boolean isSendCodeEnabled()

Informs whether JavaScript code can be added to send to the client calling addCodeToSend(Object)

Returns:

true if new code can be added.

See Also:

disableSendCode()

disableSendCode

void disableSendCode()

Disables the addCodeToSend(Object) method, no new code can be added to send to the client.

See Also:

enableSendCode()

enableSendCode

void enableSendCode()

Enables the addCodeToSend(Object) method, new code can be added to send to the client.

See Also:

disableSendCode()

addCodeToSendListener

void addCodeToSendListener(CodeToSendListener listener)

Registers a new CodeToSendListener, this listener is called every time addCodeToSend(Object) is called.

Parameters:

listener - the new listener.

See Also:

removeCodeToSendListener(CodeToSendListener)

removeCodeToSendListener

void removeCodeToSendListener(CodeToSendListener listener)

Removes a previously registered CodeToSendListener.

Parameters:

listener - the new listener.

See Also:

addCodeToSendListener(CodeToSendListener)

getElementGroupManager

ElementGroupManager getElementGroupManager()

Returns the element group manager utility.

Returns:

the element group manager utility.

registerArtifact

void registerArtifact(String name,
                    Object value)

Registers an artifact with the specified name.

Parameters:

name - the artifact name

value - the artifact.

See Also:

getArtifact(String), removeArtifact(String), NameValue

getArtifact

Object getArtifact(String name)

Returns the artifact with the specified name.

Parameters:

name - the artifact name to look for.

Returns:

the artifact or null if not found.

See Also:

registerArtifact(String,Object), getArtifact(String,boolean)

removeArtifact

Object removeArtifact(String name)

Removes the artifact with the specified name.

Parameters:

name - the artifact name to look for.

Returns:

the removed artifact.

See Also:

registerArtifact(String,Object)

getArtifact

Object getArtifact(String name,
                 boolean cascade)

Returns the artifact with the specified name.

If no artifact is found and cascade is true, the method ItsNatDocumentTemplate.getArtifact(String,boolean) is called with cascade set to true to continue searching.

Parameters:

name - the artifact name to look for.

Returns:

the artifact or null if not found.

See Also:

getArtifact(String)

addItsNatAttachedClientEventListener

void addItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener listener)

Adds a remote control listener to this document. This listener is called when a remote view/control is requested to control a document loaded using this template.

Parameters:

listener - the listener to add.

See Also:

removeItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener), ItsNatServlet.addItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener), ItsNatDocumentTemplate.addItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener)

removeItsNatAttachedClientEventListener

void removeItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener listener)

Removes the specified remote control listener.

Parameters:

listener - the listener to remove.

See Also:

addItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener)

createEvent

Event createEvent(String eventType)
                  throws DOMException

Create a remote event to be dispatched locally or to the client.

This method works the same as org.w3c.dom.events.Document.createEvent(String), in this case the event object created is ready to be dispatched to the remote event listeners registered calling:

• EventTarget.dispatchEvent(Event): this method detects whether the submitted event was created by this factory method then redirects to dispatchEvent(EventTarget,Event).
• dispatchEvent(EventTarget,Event)
• dispatchEventLocally(EventTarget,Event)
• ClientDocument.dispatchEvent(EventTarget,Event)

Parameters:

eventType - The eventType parameter specifies the type of Event interface to be created.

Returns:

the new event.

Throws:

DOMException

dispatchEvent

boolean dispatchEvent(EventTarget target,
                    Event evt)
                      throws EventException

Dispatches the specified event to the specified node target.

If the current thread was not started calling ClientDocument.startEventDispatcherThread(Runnable) current implementation calls dispatchEventLocally(EventTarget,Event), otherwise calls ClientDocument.dispatchEvent(EventTarget,Event).

This method is called by org.w3c.dom.events.EventTarget#dispatchEvent(Event) when the event object was created calling createEvent(String).

Parameters:

target - the event target DOM object.

evt - the DOM event to send to target.

Returns:

The return value is false if at least one of the event handlers which handled this event called Event.preventDefault(). Otherwise it returns true.

Throws:

EventException

dispatchEventLocally

boolean dispatchEventLocally(EventTarget target,
                           Event evt)
                             throws EventException

Dispatches the specified event to the specified node target directly on the server.

The event is routed across the server DOM tree and dispatched to listeners as specified by the W3C DOM Events standard including bubbling and capturing.

Parameters:

target - the event target DOM object.

evt - the DOM event to send to target.

Returns:

The return value is false if at least one of the event handlers which handled this event called Event.preventDefault(). Otherwise it returns true.

Throws:

EventException

getCreationTime

long getCreationTime()

Returns the time in milliseconds when this object was created.

Returns:

the creation time.

addReferrerItsNatServletRequestListener

void addReferrerItsNatServletRequestListener(ItsNatServletRequestListener listener)

Registers a new ItsNat referrer request listener. This listener is called when the framework loads a new target document and this document is being unloaded before the target request listeners are executed (referrer push).

Parameters:

listener - the listener to register.

See Also:

removeReferrerItsNatServletRequestListener(ItsNatServletRequestListener), ItsNatDocumentTemplate.isReferrerPushEnabled()

removeReferrerItsNatServletRequestListener

void removeReferrerItsNatServletRequestListener(ItsNatServletRequestListener listener)

Unregisters the specified user defined referrer request listener.

Parameters:

listener - the listener to remove.

See Also:

addReferrerItsNatServletRequestListener(ItsNatServletRequestListener)

isDisconnectedChildNodesFromClient

boolean isDisconnectedChildNodesFromClient(Node node)

Informs whether the specified node is marked as "child nodes disconnected"

Parameters:

node - the node to ask.

Returns:

true if the specified node is marked as "child nodes disconnected"

See Also:

disconnectChildNodesFromClient(Node), reconnectChildNodesToClient(Node)

disconnectChildNodesFromClient

Node disconnectChildNodesFromClient(Node node)

Removes the child nodes of the specified node to save server memory but not in client.

After this call the child nodes in client are not longer in sync with server and can be freely manipulated (including insertion and removing).

The specified node is marked as "child nodes disconnected", the inmmediate call to isDisconnectedChildNodesFromClient(Node) will return true.

Returns the removed child nodes following the same criteria as ItsNatDOMUtil.extractChildren(Node).

If the content of the parent node is already disconnected or is a node not into the document an ItsNatException is thrown.

Parameters:

node - the parent node which content is going to be disconnected and removed.

Returns:

null if empty, the child node when only a child node or a DocumentFragment containing the child nodes.

See Also:

reconnectChildNodesToClient(Node)

reconnectChildNodesToClient

void reconnectChildNodesToClient(Node node)

Reconnects further new child nodes of the specified node with the client, the child nodes in client are removed and again the client will be in sync with server.

Further insertion of child nodes will be also effective in client.

This method is automatically/implicitly called by ItsNat when a node is inserted into a "child nodes disconnected" node, the node inserted then in also inserted into the client now in sync.

If the speficied node is not a "child nodes disconnected" node this call does nothing.

Parameters:

node - the parent node which content will be in sync again with client.

See Also:

disconnectChildNodesFromClient(Node)