Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.nexaweb.xml
Interface Document

public interface Document

The Document interface represents an entire XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.

Listeners may be registered at the Document level to hear changes in the entire document.

The Document has a map of id to Element for every Element. Therefore it is able to provide efficient hash based element lookup by id.

Documents may be obtained from Parser objects.

IMPORTANT:

Nexaweb's Document Object Model (DOM) is a data structure. As with most data structures (such as List, Set, Map, etc.) Nexaweb's DOM is not thread safe. You must obtain the DOM lock before accessing the DOM.

In the case of the UI Document, you must ALWAYS get the DOM lock before manipulating the DOM because Nexaweb's client code accesses the DOM too. Failure to obtain the lock when accessing and manipulating the DOM can cause the client to freeze.

With other documents (such as local datasets) where your code is the only code that accesses the data structure, if you are operating in a single thread there is no need to obtain the lock. Note that synchronized or shared datasets are accessed by Nexaweb's synchronization threads and the lock must be obtained.

EXAMPLE:

When modifying the client side DOM from an MCO developers MUST wrap their changes in a synchronized block in the following way. 

 
 ClientSession session = getClientSession();
 Document uiDoc = session.getDocumentRegistry()
    .findDocument(DocumentRegistry.UI_DOCUMENT_NAME);
 synchronized ( uiDoc.getDomSynchronizationObject() ) {
 
     // MAKE ALL UI DOM OR NFC CHANGES HERE
     // Any and all changes to any shared document
     // should be done inside the synchronized block.
 }

Since:
4.0
See Also:
DocumentRegistry, Element, Parser, ParserFactory

Method Summary
 void addAttributeChangeListener(AttributeChangeListener listener)
          Adds a listener to this document for attribute changes.
 void addStructureChangeListener(StructureChangeListener listener)
          Adds a listener to this document for DOM structure changes.
 Element createElement(java.lang.String localName)
          Creates an element with the specified local name.
 Element createElement(java.lang.String localName, java.lang.String ns)
          Creates an element with the specified local name and namespace URI.
 Element createElement(java.lang.String localName, java.lang.String prefix, java.lang.String ns)
          Creates an element with the specified local name, prefix, and namespace URI.
 java.lang.Object getDomSynchronizationObject()
          Returns an object that users of this document should synchronized on.
 Element getElementById(java.lang.String id)
          Returns the Element contained in this document with the specified ID.
 java.lang.String getEncoding()
          Returns the encoding for this document.
 Element getRootElement()
          Returns the root Element of this Document.
 boolean removeAttributeChangeListener(AttributeChangeListener listener)
          Removes an AttributeChangeListener from this Document.
 boolean removeStructureChangeListener(StructureChangeListener listener)
          Removes an StructureChangeListener from this Document.
 void setRootElement(Element root)
          Sets this Document's root element.
 java.lang.String toXml(boolean prettyPrint)
          Returns a String representation of this Document with any Nexaweb-generated XML ID attributes.
 java.lang.String toXmlWithoutAutoAssignedIds(boolean prettyPrint)
          Returns a String representation of this Document without any Nexaweb-generated XML ID attributes.
 

Method Detail

createElement

public Element createElement(java.lang.String localName)
                      throws java.lang.IllegalArgumentException
Creates an element with the specified local name. The Element created will not have a parent or an owner document. If the element is added to a document (or added to an element already owned by a document) the element will inherit it's parent's owner document.

Parameters:
localName - The local name of the new element.
Throws:
java.lang.IllegalArgumentException - Thrown if the specified local name is not a legal xml localname or null.
Since:
4.0

createElement

public Element createElement(java.lang.String localName,
                             java.lang.String ns)
                      throws java.lang.IllegalArgumentException
Creates an element with the specified local name and namespace URI. The Element created will not have a parent or an owner document. If the element is added to a document (or added to an element already owned by a document) the element will inherit it's parent's owner document.

Parameters:
localName - The local name of the new element.
ns - The namespace URI for the new element.
Throws:
java.lang.IllegalArgumentException - Thrown if the specified local name is not a legal xml localname, or any of the arguments are null.
Since:
4.0

createElement

public Element createElement(java.lang.String localName,
                             java.lang.String prefix,
                             java.lang.String ns)
                      throws java.lang.IllegalArgumentException
Creates an element with the specified local name, prefix, and namespace URI. The Element created will not have a parent or an owner document. If the element is added to a document (or added to an element already owned by a document) the element will inherit it's parent's owner document.

Parameters:
localName - The local name of the new element.
prefix - The prefix for the new element.
ns - The namespace URI for the new element.
Throws:
java.lang.IllegalArgumentException - Thrown if the specified local name is not a legal xml localname, or any of the arguments are null.
Since:
4.0

getRootElement

public Element getRootElement()
Returns the root Element of this Document.

Returns:
the root element
Since:
4.0
See Also:
Element

getEncoding

public java.lang.String getEncoding()
Returns the encoding for this document. The encoding can be found in the xml tag (<?xml version="1.0" encoding="ISO-8859-1"?>). If no encoding is specified in the document null is returned.

Returns:
the document encoding if defined in the document, null otherwise
Since:
4.0

addAttributeChangeListener

public void addAttributeChangeListener(AttributeChangeListener listener)
Adds a listener to this document for attribute changes.

Parameters:
listener - - the listener to register
Since:
4.0
See Also:
AttributeChangeListener, AttributeChangeEvent

removeAttributeChangeListener

public boolean removeAttributeChangeListener(AttributeChangeListener listener)
Removes an AttributeChangeListener from this Document.

Parameters:
listener - - the listener to remove
Returns:
- returns true if it was removed, false otherwise
Since:
4.0
See Also:
AttributeChangeListener, AttributeChangeEvent

addStructureChangeListener

public void addStructureChangeListener(StructureChangeListener listener)
Adds a listener to this document for DOM structure changes.

Parameters:
listener - - the listener to register
Since:
4.0
See Also:
StructureChangeListener, StructureChangeEvent

removeStructureChangeListener

public boolean removeStructureChangeListener(StructureChangeListener listener)
Removes an StructureChangeListener from this Document.

Parameters:
listener - - the listener to remove
Returns:
- returns true if it was removed, false otherwise
Since:
4.0
See Also:
StructureChangeListener, StructureChangeEvent

getElementById

public Element getElementById(java.lang.String id)
Returns the Element contained in this document with the specified ID. null is returned if an Element with that ID does not exist.

Parameters:
id - the id of the Element to return.
Returns:
the Element with the specified ID, or null if it does not exist.
Since:
4.0

setRootElement

public void setRootElement(Element root)
Sets this Document's root element. If the element being set is already a member of a document, it will be removed from its old document. This Document's current root element will be discarded.

Parameters:
root - the new root element of this Document.
Since:
4.0

toXml

public java.lang.String toXml(boolean prettyPrint)
Returns a String representation of this Document with any Nexaweb-generated XML ID attributes.

Parameters:
prettyPrint - If true, newlines and tabs will be present in the resulting string to make it more readable.
Returns:
A String representation of this Document
Since:
4.0

toXmlWithoutAutoAssignedIds

public java.lang.String toXmlWithoutAutoAssignedIds(boolean prettyPrint)
Returns a String representation of this Document without any Nexaweb-generated XML ID attributes.

Parameters:
prettyPrint - If true, newlines and tabs will be present in the resulting string to make it more readable.
Returns:
A String representation of this Document
Since:
4.0

getDomSynchronizationObject

public java.lang.Object getDomSynchronizationObject()
Returns an object that users of this document should synchronized on. This object should be synchronized on when manipulating any element contained in this document.

IMPORTANT:

Nexaweb's Document Object Model (DOM) is a data structure. As with most data structures (such as List, Set, Map, etc.) Nexaweb's DOM is not thread safe. You must obtain the DOM lock before accessing the DOM.

In the case of the UI Document, you must ALWAYS get the DOM lock before manipulating the DOM because Nexaweb's client code accesses the DOM too. Failure to obtain the lock when accessing and manipulating the DOM can cause the client to freeze.

With other documents (such as local datasets) where your code is the only code that accesses the data structure, if you are operating in a single thread there is no need to obtain the lock. Note that synchronized or shared datasets are accessed by Nexaweb's synchronization threads and the lock must be obtained.

EXAMPLE:

When modifying the client side DOM from an MCO developers MUST wrap their changes in a synchronized block in the following way. 

 
 ClientSession session = getClientSession();
 Document uiDoc = session.getDocumentRegistry()
    .findDocument(DocumentRegistry.UI_DOCUMENT_NAME);
 synchronized ( uiDoc.getDomSynchronizationObject() ) {
 
     // MAKE ALL UI DOM OR NFC CHANGES HERE
     // Any and all changes to shared documents
     // should be done inside the synchronized block.
 }

Returns:
An object to synchronize on when manipulating elements contained in this document.
Since:
4.0
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2005 Nexaweb Technologies, Inc. All Rights Reserved.