Document (OpenText Process Suite Platform 10.8 Java SDK API)

java.lang.Object
- com.eibus.xml.nom.Document

```
public class Document
extends java.lang.Object
```
This Document class is a java wrapper over a NOM (Native Object Model) document. A NOM document is a native document object comprising a set of native memory structures, and functions to work with an XML document.

Two or more java Document objects can point to a single NOM document, i.e., a single NOM document can be shared by many java document objects.

To work on an XML document, the document needs to be loaded into memory using load()/parseString() method of Document object. This method returns an int which points to the root element of the document.
```
 Example:
 
                String myfile = "c:/test/myfile.xml"
                static com.eibus.xml.nom.Document doc = new com.eibus.xml.nom.Document()
                int root =  doc.load(myfile);
 
 
```
To gain performance, all XML nodes (elements, text nodes, etc.) are referenced using integers. Creating Java objects for each XML node is much slower in Java than 'creating' integers.

Garbage collection is implicitly taken care in Document class. If all the java document objects releases their reference to the NOM document object, then the NOM document and its corresponding memory (heap) will be removed automatically. A Document is a wrapper around a set of XML functions that have been implemented natively. A Document does NOT represent a single XML Document, but it is a context for the XML functions it wraps. These functions all make use of the same caching of tagnames. You can parse an XML documents with the load() method of Document . You can then again call the same function on a different XML document, using the same Document object. The parsing process will then have a better performance. If you parse an XML document, the method returns the root element of that XML document as a Java int. You can do all kinds of operations on this root with the Node functions, that work on Java integers. The reason for working with int instead of Object is for better performance. Creating Java objects for each XML node is much slower in Java 1.1 than 'creating' integers. Use the create() methods on Document to create new nodes in your XML tree. You can have several instances of the Document object that all refer to the same native context. When the garbage collector of the Java VM calls the finalize() method on the Document object, a reference counter is decreased. When the counter is 0, the native context will be deleted. When a new Document object is created for the same context (this happens, for example, if you call Node.getDocument()), the counter will be increased. This means, that if you loose all handles to the Document object, your native context will automatically be deleted.
Caution: Usage of any functions of Node or Document on deleted native context may lead to crash of virtual machine.

Note: Manipulation methods like createElement() will not check for either the validness or welformedness of the resultant xml.

You can use all kinds of search functions on your nodes with the methods in XPath. The Document class loads the native library called xmlForJava. You can overwrite this name by setting the property com.eibus.xml.nom.dll. For any errors occurred with the usage of the API, it will throw XMLException
See Also:

Node, XPath

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static interface Document._IDocumentCreationEventListener
This interface has to be implemented while creating custom eventListener.

Nested Classes
Modifier and Type	Class and Description
`static interface`	`Document._IDocumentCreationEventListener` This interface has to be implemented while creating custom eventListener.

Constructor Summary

Constructors
Constructor and Description

Document()
Creates a new document.

Constructors
Constructor and Description
`Document()` Creates a new document.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static void`	`addDocumentCreationEventListener(Document._IDocumentCreationEventListener listener)` This method adds an event listener that is informed when a new document is created.
`static void`	`clearLeakInfoBaseline()` Clears any existing 'memory-leak' baseline, if already set.
`int`	`createCData(java.lang.String text)` Creates a new CData node with 'text' as CData section
`int`	`createCDataElement(java.lang.String tag, java.lang.String text)` Creates a new element by name 'tag' with 'text' as CData section
`int`	`createCDataElement(java.lang.String tag, java.lang.String text, int parent)` Creates a new element by name 'tag' with 'text' as CData section, and appends it to 'parent'
`int`	`createCDataElementNS(java.lang.String name, java.lang.String CDataContent, int parent)` Deprecated. in C3, use createCDataElementWithParentNS()
`int`	`createCDataElementNS(java.lang.String name, java.lang.String CDataContent, java.lang.String prefix, int parent)` Deprecated. in C3, use createCDataElementNSWithPrefix()
`int`	`createCDataElementNS(java.lang.String name, java.lang.String CDataContent, java.lang.String prefix, java.lang.String namespaceURI, int parent)` Creates a new CDATA element with input namespace details and appends it to the children of the indicated parent.
`int`	`createCDataElementNSWithPrefix(java.lang.String name, java.lang.String CDataContent, java.lang.String prefix, int parent)` Creates a new CDATA element with input 'prefix' and appends to the parent.
`int`	`createCDataElementWithParentNS(java.lang.String name, java.lang.String CDataContent, int parent)` Creates a new CDATA element with parent namespace details and appends to the parent.
`int`	`createComment(java.lang.String data, int parent)` Creates a new comment node
`int`	`createElement(java.lang.String tag)` Creates a new element.
`int`	`createElement(java.lang.String tag, int parent)` Creates a new element with the given tag and appends it to parent.
`int`	`createElementNS(java.lang.String name, java.lang.String content, int parent)` Deprecated. in C3.Use createElementWithParentNS(String name, String content, int parent) instead.
`int`	`createElementNS(java.lang.String name, java.lang.String content, java.lang.String prefix, int parent)` Deprecated. in C3, use createElementNSWithPrefix()
`int`	`createElementNS(java.lang.String name, java.lang.String content, java.lang.String prefix, java.lang.String namespaceURI, int parent)` Creates a new element with the given Namespace details and appends it to the children of the indicated parent.
`int`	`createElementNSWithPrefix(java.lang.String name, java.lang.String content, java.lang.String prefix, int parent)` Creates a new element with namespace prefix 'prefix' and appends it to the children of the indicated parent.
`int`	`createElementWithParentNS(java.lang.String name, java.lang.String content, int parent)` Creates a new element with parent namespace details and appends it to the children of the indicated parent.
`int`	`createText(java.lang.String text)` Creates a new text node.
`int`	`createText(java.lang.String text, int parent)` Creates a new text node and appends it to the children of the indicated parent.
`int`	`createTextElement(java.lang.String tag, java.lang.String text)` Creates a new element and creates a new text node which is appended to the newly created element.
`int`	`createTextElement(java.lang.String tag, java.lang.String text, int parent)` Creates a new element, appends it to parent, and creates a new text node which is appended to the newly created element.
`boolean`	`enableInvalidUriErrorSuppression(boolean mode)` Setting to suppress throwing NomException when loading a document with invalid namespace uri's (e.g.
`boolean`	`equals(java.lang.Object obj)` Returns true if two Documents have the same native handle.
`protected void`	`finalize()` This method should only be called by the Java VM.
`long`	`getAttributesMemory()` Deprecated. since BOP4-FP1
`static int`	`getCountOfUsedNodesAndAttr()` Gets the Total number of Nodes and Attributes currently used( those are not deleted yet) in this JVM.
`long`	`getElementsMemory()` Deprecated.
`long`	`getHandle()` Returns the handle to the native context of the Document.
`static java.lang.String`	`getInstantiationStackTrace()` Provides detailed instantiation StackTrace information of all the instances of Document objects.
`static java.lang.String`	`getLeakInfo(int newTreesThreshold)` Deprecated. Use getLeakInfo(int newTreesThreshold,boolean includeNodeStackTrace). Note: This operation is 'very heavy' (consumes lot of both CPU cycles and memory) and should not be used for regular processing, it is recommended to use only for debugging purposes. Example: `int analysis = 0; Document tempDoc = null; try { tempDoc = new Document(); Document.setLeakInfoBaseline(); tempDoc.createElement("root3"); analysis = tempDoc.parseString(Document.getLeakInfo(0,true)); assertTrue( "The pattern ?<TreeContents><root3> SHOULD BE matched, problems with baseline", XPath.getFirstMatch(".//TreeContents/root3", null, analysis) != 0); } finally { Document.clearLeakInfoBaseline(); Node.delete(analysis); tempDoc = null; }`
`static java.lang.String`	`getLeakInfo(int newTreesThreshold, boolean includeNodeStackTrace)` Provides detailed information of 'leaked nodes' with option for stackTrace information of nodes.
`int`	`getNumUsedNodes(boolean printUsedNodes)` Returns the number of used Nodes and Attributes in the Document.
`long`	`getStringsMemory()` Returns allocated memory for string in bytes
`static long`	`getTotalDataMemory()` Deprecated. use getTotalHeapMemory.
`static long`	`getTotalHeapMemory()` Returns total used Heap memory(Memory used by Strings).
`static long`	`getTotalMemory()` Deprecated. Use getTotalVirtualMemory and getTotalHeapMemory. Example: `Document oDocument = new Document(); String xmlStr = "<note a=\"xyz\"><from/></note>"; try { oDocument.load(xmlStr.getBytes()); Document.getToatalMemory();//Returns the ToatalMemory(TotalNodesMemory+TotalDataMemory) } catch (XMLException e) { e.printStackTrace(); }`
`static long`	`getTotalNodesMemory()` Deprecated. use getTotalVirtualMemory to get memory allocated for elements and attributes together. Example: `Document oDocument = new Document(); String xmlStr = "<note a=\"xyz\"><from/></note>"; try { oDocument.load(xmlStr.getBytes()); Document.getToatalNodesMemory();//Returns the ToatalNodesMemory } catch (XMLException e) { e.printStackTrace(); }`
`static int`	`getTotalNumDocuments()` Returns total active 'Document' instances.
`static int`	`getTotalNumNodes()` Returns total used nodes.
`static long`	`getTotalVirtualMemory()` Returns total used virtual memory(elements+attributes).
`int[]`	`getUsedNodesList()` Returns the root node handles that exist presently in the document
`int`	`hashCode()` Returns a hash code value for the object.
`boolean`	`includeCommentsByParsing(boolean mode)` Sets new mode for XML document loading
`int`	`includeCommentsByParsing(int mode)` Sets new mode for XML document loading whether to include comments or not while loading the xml content.
`boolean`	`includeWhiteSpacesByParsing(boolean mode)` Include or remove white-spaces while loading or parsing XML content.
`int`	`includeWhiteSpacesByParsing(int mode)` Include or remove white-spaces while loading or parsing XML content.
`static boolean`	`isDocumentCreationStackTracesEnabled()` Returns the status of DocumentCreationStackTracesEnabled
`static boolean`	`isXMLExceptionsEnable()` Gets mode for XML Exceptions Enabled
`int`	`load(byte[] bytes)` Parses the byte array
`int`	`load(byte[] bytes, int length)` Parses the first `length` number of bytes from `bytes`.
`int`	`load(byte[] xmlBytes, Schema schema)` Parses the byte array by validating against the schema
`int`	`load(java.lang.String filename)` Parses an XML file.
`int`	`loadByPreserveSpace(byte[] bytes)` Parses the a byte array by preserving the white spaces.
`int`	`loadByPreserveSpace(byte[] bytes, int length)` Parses the first `length` number of bytes from `bytes` by preserving the white spaces.
`int`	`loadByPreserveSpace(java.lang.String filename)` Parses the file having XML content by preserving the white space.
`void`	`lock()` Locks the document for synchronization with other threads.
`int`	`parseString(java.lang.String xml)` Parses the string.
`int`	`parseString(java.lang.String xml, java.lang.String encoding)` Parses the string.
`int`	`parseStringByPreserveSpace(java.lang.String xml)` Parses the string by preserving the white spaces.
`int`	`parseStringByPreserveSpace(java.lang.String xml, java.lang.String encoding)` Parses the string by preserving the white spaces.
`static void`	`removeDocumentCreationEventListener(Document._IDocumentCreationEventListener listener)` This method removes a document creation event listener.
`void`	`setDeletionTrace(boolean option)`
`static void`	`setLeakInfoBaseline()` Initializes 'memory-leak' baseline for XML Nodes.
`static void`	`setXMLExceptionsEnable(boolean mode)` Deprecated. from C3.001 and D1 onwards. Use `bus.xml.nom.exceptions.enabled` located in "wcp.properties" file. Note: Once the mode is set, the new mode is applicable for all documents. It is for the developers who can set it to true while developing code. It will help them to find the invalid use of XML and throw exceptions accordingly. XMLExceptions can be enabled or disabled by adding a property `bus.xml.nom.exceptions.enabled` to true or false in wcp.properties file.
`java.lang.String`	`toString()` Returns java address and native address of the document.
`void`	`unlock()` Unlocks the document for other threads.

Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail
- Document
```
public Document()
```
  Creates a new document. This will also allocate native memory space. That memory is freed when the method finalize() is called.
  
  Example:
```
 
 Document oDocument = new Document();
 
 
```

Method Detail

finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
This method should only be called by the Java VM. It frees the memory that has been allocated by native functions.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

getHandle
```
public long getHandle()
```
Returns the handle to the native context of the Document.

setXMLExceptionsEnable
```
@Deprecated
public static void setXMLExceptionsEnable(boolean mode)
```
Deprecated. from C3.001 and D1 onwards. Use bus.xml.nom.exceptions.enabled located in "wcp.properties" file.

Note:
Once the mode is set, the new mode is applicable for all documents. It is for the developers who can set it to true while developing code. It will help them to find the invalid use of XML and throw exceptions accordingly.
XMLExceptions can be enabled or disabled by adding a property bus.xml.nom.exceptions.enabled to true or false in wcp.properties file.

Sets new mode for Xml Exceptions Enabled

Parameters:

mode - If mode is true, it enables the xml exceptions. If mode is false, it disables the xml exceptions.

setDeletionTrace

public void setDeletionTrace(boolean option)

isXMLExceptionsEnable

public static boolean isXMLExceptionsEnable()

Gets mode for XML Exceptions Enabled

Returns:

returns mode which is set.

Example:

        
 boolean exceptions = Document.isXMLExceptionsEnable();

load

public int load(byte[] xmlBytes,
                Schema schema)
         throws XMLException

Parses the byte array by validating against the schema

Parameters:

xmlBytes - The bytes to parse

schema - The schema object to be used for validation.

Returns:

The root element reference of the parsed content if the schema validation is successful.

Throws:

Throws - XMLException if the parser could not parse the bytes or the schema validation fails.

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<note><to>Tove</to><from>Jani</from><heading>Reminder</heading><body>Don't forget me this weekend!</body></note>";
 String schemaStr = "<xs:schema xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" "
                + "targetNamespace=\"http://www.cordys.com\" "
                + "xmlns=\"http://www.cordys.com\">" + "<xs:element name=\"note\">"
                + "<xs:complexType>" + "<xs:sequence>"
                + "<xs:element name=\"to\" type=\"xs:string\"/>"
                + "<xs:element name=\"from\" type=\"xs:string\"/>"
                + "<xs:element name=\"heading\" type=\"xs:string\"/>"
                + "<xs:element name=\"body\" type=\"xs:string\"/>" + "</xs:sequence>"
                + "</xs:complexType>" + "</xs:element></xs:schema>";
 int result = 0;
 try {
        com.eibus.xml.nom.Schema oSchema = SchemaFactory.newSchema(schemaStr
                        .getBytes());
        result = oDocument.load(xmlStr.getBytes(), oSchema);
        assertTrue("Failed to load the xml with schema validation", result != 0);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

load

public int load(byte[] bytes,
                int length)
         throws XMLException

Parses the first length number of bytes from bytes.

Parameters:

bytes - The bytes to parse

length - Indicates the length up to which byte to read the byte array

Throws:

Throws - XMLException if the parser could not parse the bytes

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<note>" + "<to>Tove</to>" + "</note>";
 byte byteXml[] = xmlStr.getBytes();
 int result = 0;
 try {
        result = oDocument.load(xmlStr.getBytes(), byteXml.length);
        String resultStr = Node.writeToString(result, false);
        assertEquals(xmlStr, resultStr);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

loadByPreserveSpace

public int loadByPreserveSpace(byte[] bytes,
                               int length)
                        throws XMLException

Parses the first length number of bytes from bytes by preserving the white spaces.

Parameters:

bytes - The bytes to parse

length - Indicates the length up to which byte to read in the byte array

Throws:

Throws - XMLException if the parser could not parse the bytes

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<note>" + "\n<to>Tove</to>\n" + "</note>";
 byte byteXml[] = xmlStr.getBytes();
 int result = 0;
 try {
        result = oDocument.loadByPreserveSpace(xmlStr.getBytes(),
                        byteXml.length);
        String resultStr = Node.writeToString(result, false);
        assertEquals(xmlStr, resultStr);
        System.out.println(Node.writeToString(result, false));//prints space preserved output
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

load

public int load(byte[] bytes)
         throws XMLException

Parses the byte array

Parameters:

bytes - The bytes to parse

Returns:

The root element reference of the parsed content

Throws:

Throws - XMLException if the parser could not parse the bytes

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<root><fchild></fchild></root>";
 int result = 0;
 try {
        result = oDocument.load(xmlStr.getBytes());
        assertTrue("Failed to parse", result != 0);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

loadByPreserveSpace

public int loadByPreserveSpace(byte[] bytes)
                        throws XMLException

Parses the a byte array by preserving the white spaces.

Parameters:

bytes - The bytes to parse

Returns:

The root element reference of the parsed content

Throws:

Throws - XMLException if the parser could not parse the bytes

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<note>\n\t" + "<to>\tTove\t</to>" + "\n</note>";
 String expectedResult = "<note>\n\t<to>\tTove\t</to>\n</note>";
 int result = 0;
 try {
        result = oDocument.loadByPreserveSpace(xmlStr.getBytes());
        String resultStr = Node.writeToString(result, false);
        assertEquals(expectedResult, resultStr);
        System.out.println(Node.writeToString(result, false));//prints space preserved output
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

load

public int load(java.lang.String filename)
         throws XMLException

Parses an XML file. Ignores all the comments and Processing Instructions that appear before root node

Parameters:

filename - The name of the file to parse

Returns:

The root element reference of the parsed content

Throws:

Throws - XMLException if the parser could not parse the file or the file does not exist

Example:

 
 Document oDocument = new Document();
 String fileName = ".\\cd_catalog.xml";
 int result = 0;
 try {
        result = oDocument.load(fileName);
        assertTrue("Failed to parse", result != 0);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

parseString

public int parseString(java.lang.String xml)
                throws XMLException,
                       java.io.UnsupportedEncodingException

Parses the string. (All comments and PIs before root element will be ignored.) Calls method parseString(xml, "UTF8");

Parameters:

xml - A string containing XML.

Returns:

The root element reference of the parsed content.

Throws:

Throws - XMLException if the parser could not parse the string

Throws - UnsupportedEncodingException If this system does not have a UTF8 encoder

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<root><fchild></fchild></root>";
 int result = 0;
 try {
        result = oDocument.parseString(xmlStr);
        assertTrue("Failed to parse", result != 0);
 } catch (XMLException e) {
        e.printStackTrace();
 } catch (UnsupportedEncodingException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

java.io.UnsupportedEncodingException

parseString

public int parseString(java.lang.String xml,
                       java.lang.String encoding)
                throws XMLException,
                       java.io.UnsupportedEncodingException

Parses the string. Converts the string into bytes, using the specified encoding, and calls the method load(byte[]).

Parameters:

xml - A string containing XML.

encoding - Encoding to be used for the conversion from string to bytes.

Returns:

The root element reference of the parsed content

Throws:

Throws - XMLException if the parser could not parse the string

Throws - UnsupportedEncodingException If this system does not have a coder for the specified encoding

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<root><fchild></fchild></root>";
 int result = 0;
 try {
        result = oDocument.parseString(xmlStr, "UTF-16");
        assertTrue("Failed to parse", result != 0);
 } catch (XMLException e) {
        e.printStackTrace();
 } catch (UnsupportedEncodingException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

java.io.UnsupportedEncodingException

loadByPreserveSpace

public int loadByPreserveSpace(java.lang.String filename)
                        throws XMLException

Parses the file having XML content by preserving the white space. Ignores all the comments and Processing Instructions that appear before root node

Parameters:

filename - The name of the file to parse

Returns:

The root element reference of the parsed content

Throws:

Throws - XMLException if the parser could not parse the file or the file does not exist

Example:

 
 Document oDocument = new Document();
 String fileName = ".\\cd_catalog.xml";
 int result = 0;
 try {
        result = oDocument.loadByPreserveSpace(fileName);
        assertTrue("Failed to parse", result != 0);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

parseStringByPreserveSpace

public int parseStringByPreserveSpace(java.lang.String xml)
                               throws XMLException,
                                      java.io.UnsupportedEncodingException

Parses the string by preserving the white spaces. Ignores all the comments and Processing Instructions that appear before root node. Calls method parseStringByPreserveSpace(xml, "UTF8");

Parameters:

xml - A string containing XML.

Returns:

The root element reference of the parsed content.

Throws:

Throws - XMLException if the parser could not parse the string

Throws - UnsupportedEncodingException If this system does not have a UTF8 encoder

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<note>\n" + "<to>Tove</to>" + "\n</note>";
 String expectedResult = "<note>\n<to>Tove</to>\n</note>";
 int result = 0;
 try {
        result = oDocument.parseStringByPreserveSpace(xmlStr);
        String resultStr = Node.writeToString(result, false);
        assertEquals(expectedResult, resultStr);
        System.out.println(Node.writeToString(result, false));//prints space preserved output
 } catch (XMLException e) {
        e.printStackTrace();
 } catch (UnsupportedEncodingException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

java.io.UnsupportedEncodingException

parseStringByPreserveSpace

public int parseStringByPreserveSpace(java.lang.String xml,
                                      java.lang.String encoding)
                               throws XMLException,
                                      java.io.UnsupportedEncodingException

Parses the string by preserving the white spaces. Converts the string into bytes, using the specified encoding, and calls the method load(byte[]).Ignores all the comments and Processing Instructions that appear before root node.

Parameters:

xml - A string containing XML.

encoding - Encoding to be used for the conversion from string to bytes.

Returns:

The root element reference of the parsed content

Throws:

Throws - XMLException if the parser could not parse the string.

Throws - UnsupportedEncodingException If this system does not have a encoder for the specified encoding

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<note>\n" + "<to>Tove</to>" + "\n</note>";
 String expectedResult = "<note>\n<to>Tove</to>\n</note>";
 int result = 0;
 try {
        result = oDocument.parseStringByPreserveSpace(xmlStr, "UTF-16");
        String resultStr = Node.writeToString(result, false);
        assertEquals(expectedResult, resultStr);
        System.out.println(Node.writeToString(result, false));//prints space preserved output
 } catch (XMLException e) {
        e.printStackTrace();
 } catch (UnsupportedEncodingException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

XMLException

java.io.UnsupportedEncodingException

createElement
```
public int createElement(java.lang.String tag,
                         int parent)
```
Creates a new element with the given tag and appends it to parent. If parent is 0, the element will not have any parent.
Parameters:

tag - The tag for the new element

parent - The parent for the new element

Returns:
returns the created element node reference. Returns 0, if it fails to create the element

Note:
This method can't be used before creating a Document object.It doesn't restrict the element name to follow XML specification. For example,element name shouldn't contain space character as per XML specification, but this method allows it.
int result=oDocument.load("<Root/>".getBytes()); oDocument.createElement("My name",result); //creates "<Root></My Name></Root>"

Example:
```
 
 Document oDocument = new Document();
 String xmlStr = "<note/>";
 int result = 0;
 try {
        result = oDocument.load(xmlStr.getBytes());
        oDocument.createElement("to", result);
        String resultStr = Node.writeToString(result, false);
        assertEquals("<note><to/></note>", resultStr);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }
 
 
 
```

createElement
```
public int createElement(java.lang.String tag)
```
Creates a new element.
Parameters:

tag - The tagname for the new element

Returns:
returns the created element node reference. Returns 0, if it fails to create the element

Note:
This method cannot be used before creating a Document object.It doesn't restrict the element name to follow XML specification. For example,element name shouldn't contain space character as per XML specification, but this method allows it.
oDocument.createElement("my name"); //creates "<my name/>"

Example:
```
 
 Document oDocument = new Document();
 String xmlStr = "<note/>";
 int ret = 0;
 try {
        ret = oDocument.createElement("to");
        String resultStr = Node.writeToString(ret, false);
        assertEquals("<to/>", resultStr);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(ret);
 }
 
 
```

createComment

public int createComment(java.lang.String data,
                         int parent)

Creates a new comment node

Parameters:

data - the data of the comment node

parent - the parent for the new comment node. if 0, then the new comment node will not have a parent.

Returns:

the new comment node
Example:

 
 String expected = "This is a commented text";
 int parent = doc.createElement("parent");
 doc.createComment(expected, parent);
 assertEquals(expected, Node.getData(parent));

createText

public int createText(java.lang.String text,
                      int parent)

Creates a new text node and appends it to the children of the indicated parent.

Parameters:

text - The data for the new node

parent - The parent for the new node

Returns:

returns the created element node reference. Returns 0, if it fails to create the element

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<note/>";
 int result = 0;
 try {
        result = oDocument.load(xmlStr.getBytes());
        oDocument.createText("to", result);
        String resultStr = Node.writeToString(result, false);
        assertEquals("<note>to</note>", resultStr);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }

createText

public int createText(java.lang.String text)

Creates a new text node.

Parameters:

text - The data for the new node

Returns:

returns the created element node reference. Returns 0, if it fails to create the element

Example:

 
 Document oDocument = new Document();
 String xmlStr = "<note/>";
 int result = 0;
 int ret = 0;
 try {
        result = oDocument.load(xmlStr.getBytes());
        ret = oDocument.createText("to");
        String resultStr = Node.writeToString(ret, false);
        assertEquals("to", resultStr);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
        Node.delete(ret);
 }

createTextElement
```
public int createTextElement(java.lang.String tag,
                             java.lang.String text,
                             int parent)
```
Creates a new element, appends it to parent, and creates a new text node which is appended to the newly created element.
Parameters:

tag - The tag for the new element

text - The data for the new node

parent - The parent for the new element

Returns:
returns the created element node reference. Returns 0, if it fails to create the element

Note:
This method can't be used before creating a Document object.It doesn't restrict the element name to follow XML specification. For example,element name shouldn't contain space character as per XML specification, but this method allows it.
int result=oDocument.load("<Root/>".getBytes()); oDocument.createTextElement("My name","abc",result); //creates "<Root><My Name>abc</My Name></Root>" Example: Document oDocument = new Document(); String xmlStr = "<note/>"; int result = 0; try { result = oDocument.load(xmlStr.getBytes()); oDocument.createTextElement("to", "abc", result); String resultStr = Node.writeToString(result, false); assertEquals("<note><to>abc</to></note>", resultStr); } catch (XMLException e) { e.printStackTrace(); }finally { Node.delete(result); }







createTextElement
public int createTextElement(java.lang.String tag,
                             java.lang.String text)
Creates a new element and creates a new text node which is appended to
 the newly created element.

Parameters:
tag - The tag for the new element
text - The data for the new node
Returns:
returns the created element node reference. Returns 0, if it
         fails to create the element 

 

         Note:

         This method can't be used before creating a Document object.It
         doesn't restrict the element name to follow XML specification.
         For example,element name shouldn't contain space character as per
         XML specification, but this method allows it. 

         oDocument.createTextElement("my name", "abc");
         //creates "<my name>abc</my name>" 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note/>";
 int result = 0;
 try {
        oDocument.load(xmlStr.getBytes());
        result = oDocument.createTextElement("to", "abc");
        String resultStr = Node.writeToString(ret, false);
        assertEquals("<to>abc</to>", resultStr);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }
 
 








lock
public void lock()
Locks the document for synchronization with other threads.
 
 

 

 Example:
 
  
 Document oDocument = new Document();
 oDocument.lock();
 
 







unlock
public void unlock()
Unlocks the document for other threads.
 
 

 

 Example:
 
  
 Document oDocument = new Document();
 oDocument.unlock();
 
 







getNumUsedNodes
public int getNumUsedNodes(boolean printUsedNodes)
Returns the number of used Nodes and Attributes in the Document.

Parameters:
printUsedNodes - if true, writes the tag names of the nodes to
            System.out/stdout
Returns:
the number of used nodes in the Document, or -1 in case of any
         failure
 
 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note><to>xyz</to></note>";
 int result = 0;
 try {
        result = oDocument.load(xmlStr.getBytes());
        int numNodes = oDocument.getNumUsedNodes(true);
        assertEquals(4, numNodes);//for 'note','to','xyz' & 'documentRoot'(not visible).
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }
 
 








includeWhiteSpacesByParsing
public int includeWhiteSpacesByParsing(int mode)
Include or remove white-spaces while loading or parsing XML content.

Parameters:
mode - If mode is 1, it includes white-spaces while loading the XML
            document. If mode is 0, it does not include white-spaces while
            loading the XML document.
Returns:
returns existing mode before set (old mode)
 
          
  Document oDocument = new Document();
  String xmlStr = "<note>\n" + "<to>Tove</to>" + "\n</note>";
  String expectedResult = "<note>\n<to>Tove</to>\n</note>";
  int result = 0;
  try {
        oDocument.includeWhiteSpacesByParsing(1);
        result = oDocument.parseStringByPreserveSpace(xmlStr);
        String resultStr = Node.writeToString(result, false);
        assertEquals(expectedResult, resultStr);
  } catch (XMLException e) {
        e.printStackTrace();
  } catch (UnsupportedEncodingException e) {
        e.printStackTrace();
  }finally {
                Node.delete(result);
 }
  
 








includeCommentsByParsing
public int includeCommentsByParsing(int mode)
Sets new mode for XML document loading whether to include comments or not while loading the xml content.

Parameters:
mode - mode is 1, it includes comments while loading the XML
            document. If mode is 0, it does not include comments while
            loading the XML document
Returns:
returns existing mode before set (old mode) 

 

         Note:

         Once the mode is set, the new mode is applicable for all other
         method calls on the document context. 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note>\n" + "<!--To address for the note--><to>Tove</to>"
                + "\n</note>";
 String expectedResult = "<note>\n<!--To address for the note--><to>Tove</to>\n</note>";
 int result = 0;
 try {
        oDocument.includeCommentsByParsing(1);
        result = oDocument.parseStringByPreserveSpace(xmlStr);
        String resultStr = Node.writeToString(result, false);
        assertEquals(expectedResult, resultStr);
 } catch (XMLException e) {
        e.printStackTrace();
 } catch (UnsupportedEncodingException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }
 
 








equals
public boolean equals(java.lang.Object obj)
Returns true if two Documents have the same native handle.

Overrides:
equals in class java.lang.Object
Parameters:
obj - The Document object reference.
Returns:
Returns true if two Documents have the same native handle.
 
 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note>\n" + "<to>Tove</to>" + "<from>Tove</from>"
                + "\n</note>";
 int result =  0;
 try {
        oDocument.includeCommentsByParsing(1);
        result = oDocument.load(xmlStr.getBytes());
        int child1 = Node.getFirstChild(result);
        int child2 = Node.getNextSibling(child1);
        assertTrue(Node.getDocument(child1).equals(Node.getDocument(child2)));
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }
 
 








hashCode
public int hashCode()
Returns a hash code value for the object.

Overrides:
hashCode in class java.lang.Object








toString
public java.lang.String toString()
Returns java address and native address of the document.

Overrides:
toString in class java.lang.Object








createCData
public int createCData(java.lang.String text)
Creates a new CData node with 'text' as CData section

Parameters:
text - The content for the new node
Returns:
returns the created text node reference
 
 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note/>";
 int result = 0;
 try {
        result = oDocument.createCData("to");
        String resultStr = Node.writeToString(ret, false);
        assertEquals("<![CDATA[to]]>", resultStr);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }
 
 
 








createCDataElement
public int createCDataElement(java.lang.String tag,
                              java.lang.String text)
Creates a new element by name 'tag' with 'text' as CData section

Parameters:
tag - The tag for the new element
text - The CData for the new node
Returns:
returns the created element node reference 

 

         Note:

         This method can't be used before creating a Document object.It
         doesn't restrict the element name to follow XML specification.
         For example,element name shouldn't contain space character as per
         XML specification, but this method allows it. 

         oDocument.createCDataElement("My Name", "abc");
         //creates "<My Name><![CDATA[abc]]></My
         Name>>" 

 

         Example:
 
          
 Document oDocument = new Document();
 int ret = oDocument.createCDataElement("to", "abc");
 String resultStr = Node.writeToString(ret, false);
 assertEquals("<to><![CDATA[abc]]></to>", resultStr);
 
 








createCDataElement
public int createCDataElement(java.lang.String tag,
                              java.lang.String text,
                              int parent)
Creates a new element by name 'tag' with 'text' as CData section, and
 appends it to 'parent'

Parameters:
tag - The tag for the new element
text - The CData for the new node
parent - The parent for the new element
Returns:
returns the created element node reference 

 

         Note:

         This method can't be used before creating a Document object.It
         doesn't restrict the element name to follow XML specification.
         For example,element name shouldn't contain space character as per
         XML specification, but this method allows it. 

         int result=oDocument.load("<Root/>".getBytes());
oDocument.createCDataElement("My Name", "abc",result);
         //creates "<Root><My
         Name><![CDATA[abc]]></My Name></Root>" 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note/>";
 int result = 0;
 try {
        result = oDocument.load(xmlStr.getBytes());
        oDocument.createCDataElement("to", "abc", result);
        String resultStr = Node.writeToString(result, false);
        assertEquals("<note><to><![CDATA[abc]]></to></note>", resultStr);
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }
 
 








includeWhiteSpacesByParsing
public boolean includeWhiteSpacesByParsing(boolean mode)
Include or remove white-spaces while loading or parsing XML content.

Parameters:
mode - If mode is true, Includes white-spaces while loading the XML document. If mode is false, does not include white-spaces while
          loading the XML document
Returns:
returns the existing mode before set (old mode).
 
          
 Document doc = new Document();
 doc.includeWhiteSpacesByParsing(true);
 
 








enableInvalidUriErrorSuppression
public boolean enableInvalidUriErrorSuppression(boolean mode)
Setting to suppress throwing NomException when loading a document with invalid namespace uri's (e.g. with spaces).

Parameters:
mode - If mode is true, suppresses throwing NomException when loading a document with invalid namespace uri's (e.g. with spaces).
Returns:
returns the existing mode before set (old mode).
 
          
 Document doc = new Document();
 doc.enableInvalidUriErrorSuppression(true);
 doc.load("".getBytes());
 
 








includeCommentsByParsing
public boolean includeCommentsByParsing(boolean mode)
Sets new mode for XML document loading

Parameters:
mode - If mode is true, Includes comments while loading the XML
            document. If mode is false, does not include comments while
            loading the XML document
Returns:
returns the existing mode before set (old mode). 

 

         Note:

         Once the mode is set, the new mode is applicable for all other
         method calls on the document context.
 
          
 Document doc = new Document();
 doc.includeCommentsByParsing(true);
 
 








addDocumentCreationEventListener
public static void addDocumentCreationEventListener(Document._IDocumentCreationEventListener listener)
This method adds an event listener that is informed when a new document
 is created. Currently, only a single event listener is supported.

Parameters:
listener - the listener to add
 
 

 

            Example:
 
             
  //The following class implements _IDocumentCreationEventListener interface.It will be used 
  //to create argument for addDocumentCreationEventListener method.
 class ImplementedListener implements _IDocumentCreationEventListener
 {
        public void _onDocumentCreate() {
                System.out.println("DocumentCreated");        
        }
        //The following code shows how to use the addDocumentCreationEventListener method.
         ImplementedListener oListener=new DocumentCreationEventListener();
        Document.addDocumentCreationEventListener(oListener);
        String xmlStr = "<note a=\"xyz\"><from/></note>";
        try {
                Document oDocument = new Document();//Returns 'DocumentCreated'.
                oDocument.load(xmlStr.getBytes());
        } catch (XMLException e) {
                e.printStackTrace();
        }
  }
  
 








removeDocumentCreationEventListener
public static void removeDocumentCreationEventListener(Document._IDocumentCreationEventListener listener)
This method removes a document creation event listener.

Parameters:
listener - the listener to remove 

 

            Example:
 
             
  //The following class implements _IDocumentCreationEventListener interface.It will be used 
  //to create argument for removeDocumentCreationEventListener method.
 class ImplementedListener implements _IDocumentCreationEventListener
 {
  
        public void _onDocumentCreate() {
                System.out.println("DocumentCreated");        
        }
        //The following code shows how to use the addDocumentCreationEventListener method.
         ImplementedListener oListener=new DocumentCreationEventListener();
        Document.addDocumentCreationEventListener(oListener);
        String xmlStr = "<note a=\"xyz\"><from/></note>";
        try {
                Document oDocument = new Document();//Returns 'DocumentCreated'.
                oDocument.load(xmlStr.getBytes());
                Document.removeDocumentCreationEventListener(oListener);
        } catch (XMLException e) {
                e.printStackTrace();
        }
  }
  
 








isDocumentCreationStackTracesEnabled
public static boolean isDocumentCreationStackTracesEnabled()
Returns the status of DocumentCreationStackTracesEnabled

Returns:
status of DocumentCreationStackTracesEnabled 

 

         Example:
 
          
 Document oDocument = new Document();
 Document.isDocumentCreationStackTracesEnabled();
 
 








createElementNS
@Deprecated
public int createElementNS(java.lang.String name,
                                        java.lang.String content,
                                        int parent)
Deprecated. in C3.Use createElementWithParentNS(String name, String
             content, int parent) instead.
Creates a new element with parent Namespace details and appends it to the
 children of the indicated parent.

Parameters:
name - local name of new element
content - content/data of the new element
parent - handle of parent element. If 0 is passed, then the created is
            created without any parent.
Returns:
The reference of the created element








createElementWithParentNS
public int createElementWithParentNS(java.lang.String name,
                                     java.lang.String content,
                                     int parent)
Creates a new element with parent namespace details and appends it to the
 children of the indicated parent.

Parameters:
name - local name of new element
content - content/data of the new element
parent - handle of parent element. If 0 passed, then new element will
            have no parent.
Returns:
The reference of the created element 

 

         Note:

         This method can't be used before creating a Document object.It
         doesn't restrict the element name to follow XML specification.
         For example,element name shouldn't contain space character as per
         XML specification, but this method allows it. 

 

         // Creates an element which is child to root element as
         "<ns:My Name>abc</ns:My Name>" 

         doc.createElementWithParentNS("My Name","abc", root); // parent element has namespace 'ns'
 

 

         Example:
 
          
  String xml =
 "<ns:root xmlns:ns="http://cordys.com/test/">
        <ns:employee> Cordys employee </ns:employee>
        <employee1>
                <test> Cordys employee </test>
        </employee1>
 </ns:root>";
 
        Document doc = new com.eibus.xml.nom.Document();
  int root = doc.load(xml); // delete this node after usage
  int emp = Node.getElement(root, "employee1");
 
 // Creates an element which is child to root element as "<ns:employee2>emplyee2 data</ns:employee2>"
  doc.createElementWithParentNS("employee2","employee2 data", root); // parent element has namespace 'ns'
 
 // Creates an element which is child to employee1 element as "<employee3>emplyee3 data</employee3>"
  doc.createElementWithParentNS("employee3","employee3 data", emp); // parent element has no namespace
 
 
 
 








createElementNS
@Deprecated
public int createElementNS(java.lang.String name,
                                        java.lang.String content,
                                        java.lang.String prefix,
                                        int parent)
Deprecated. in C3, use createElementNSWithPrefix()
Creates a new element with input 'prefix' and appends it to the children
 of the indicated parent. An exception will be thrown if 'prefix' is not
 defined in any of the ancestors of new element.

Parameters:
name - local name of new element
prefix - prefix for new element
content - content/data of the new element
parent - handle of parent element. If 0 passed, then new element will
            have no parent
Returns:
handle of created element








createElementNSWithPrefix
public int createElementNSWithPrefix(java.lang.String name,
                                     java.lang.String content,
                                     java.lang.String prefix,
                                     int parent)
Creates a new element with namespace prefix 'prefix' and appends it to
 the children of the indicated parent. An exception will be thrown if
 'prefix' is not defined in any of the ancestors of new element.

Parameters:
name - local name of new element
prefix - prefix for new element
content - content/data of the new element
parent - handle of parent element. If 0 passed, then new element will
            have no parent
Returns:
The reference of the created element 

 

         Note:

         This method can't be used before creating a Document object.It
         doesn't restrict the element name to follow XML specification.
         For example,element name shouldn't contain space character as per
         XML specification, but this method allows it. 

 

         // Creates an element which is child to root element as
         "<ns:My Name>abc</ns:My Name>". The element
         "root" has namespace "ns". 

         doc.createElementNSWithPrefix("My Name","abc", "ns", root);
 

 

         Example:
 
          
  String xml =
 "<ns:root xmlns:ns="http://cordys.com/test/">
        <ns:employee> Cordys employee </ns:employee>
        <employee1>
                <test> Cordys employee </test>
        </employee1>
 </ns:root>";
 
        Document doc = new com.eibus.xml.nom.Document();
  int root = doc.load(xml);
  int emp = Node.getElement(root, "employee1");
 
 // Creates an element which is child to root element as "<ns:employee2>emplyee2 data</ns:employee2>"
  doc.createElementNSWithPrefix("employee2","employee2 data", "ns", root);
 
 // Creates an element which is child to employee1 element as "<ns:employee3>emplyee3 data</ns:employee3>"
  doc.createElementNSWithPrefix("employee3","employee3 data", "ns", emp);
 
 
 
 








createElementNS
public int createElementNS(java.lang.String name,
                           java.lang.String content,
                           java.lang.String prefix,
                           java.lang.String namespaceURI,
                           int parent)
Creates a new element with the given Namespace details and appends it to
 the children of the indicated parent.

Parameters:
name - The tagname for the new element
content - content/data of the new element
prefix - 'prefix' for the new element, if the prefix is null then the
            created element will have a default namespace with the given
            namespaceURI.
namespaceURI - namespace URI of the 'prefix'
parent - handle of parent element. If 0 passed, then new element will
            have no parent
Returns:
The reference of the created element 

 

         Note:

         This method can't be used before creating a Document object.It
         doesn't restrict the element name to follow XML specification.
         For example,element name shouldn't contain space character as per
         XML specification, but this method allows it. 

 

         // Creates an element which is child to root element as
         "<prefix:My Name
         xmlns:prefix="http://www.cordys.com/
         test/">abc</prefix:My Name>" 

         doc.createElementNS("My Name","abc", "prefix", "http://www.cordys.com/test/", root);
 

 

         Example:
 
          
  String xml =
 "<ns:root xmlns:ns="http://cordys.com/test/">
        <ns:employee> Cordys employee </ns:employee>
        <employee1>
                <test> Cordys employee </test>
        </employee1>
 </ns:root>";
 
        Document doc = new com.eibus.xml.nom.Document();
  int root = doc.load(xml);
 
 // Creates an element which is child to root element as "<prefix:employee2 xmlns:prefix="http://www.cordys.com/test/">emplyee2 data</prefix:employee2>"
  doc.createElementNS("employee2","employee2 data", "prefix", "http://www.cordys.com/test/", root);
 
 
 
 








createCDataElementNS
@Deprecated
public int createCDataElementNS(java.lang.String name,
                                             java.lang.String CDataContent,
                                             int parent)
Deprecated. in C3, use createCDataElementWithParentNS()
Creates a new element with parent namespace details and appends it to the
 children of the indicated parent.

Parameters:
name - local name of new element
CDataContent - content/data of the new element
parent - handle of parent element. If 0 passed, then new element will
            have no parent
Returns:
handle of created element








createCDataElementWithParentNS
public int createCDataElementWithParentNS(java.lang.String name,
                                          java.lang.String CDataContent,
                                          int parent)
Creates a new CDATA element with parent namespace details and appends to the parent.

Parameters:
name - local name of new element
CDataContent - content/data of the new element
parent - handle of parent element. If 0 passed, then new element will
            have no parent
Returns:
The reference of the created element 

 

         Note:

         This method can't be used before creating a Document object.It
         doesn't restrict the element name to follow XML specification.
         For example,element name shouldn't contain space character as per
         XML specification, but this method allows it. 

 

         // Creates an element which is child to root element as
         "<ns:My Name><![CDATA[abc]]></ns:My
         Name>" 

         doc.createCDataElementWithParentNS("My Name","abc", root); // parent element has namespace 'ns'
 

 

         Example:
 
          
  String xml =
 "<ns:root xmlns:ns="http://cordys.com/test/">
        <ns:employee> Cordys employee </ns:employee>
        <employee1>
                <test> Cordys employee </test>
        </employee1>
 </ns:root>";
 
        Document doc = new com.eibus.xml.nom.Document();
  int root = doc.load(xml);
  int emp = Node.getElement(root, "employee1");
 
 // Creates an element which is child to root element as "<ns:employee2><![CDATA[employee2 data]]></ns:employee2>"
  doc.createCDataElementWithParentNS("employee2","employee2 data", root); // parent element has namespace 'ns'
 
 // Creates an element which is child to employee1 element as "<employee3><![CDATA[employee3 data]]></employee3>"
  doc.createCDataElementWithParentNS("employee3","employee3 data", emp); // parent element has no namespace
 
 
 
 








createCDataElementNS
@Deprecated
public int createCDataElementNS(java.lang.String name,
                                             java.lang.String CDataContent,
                                             java.lang.String prefix,
                                             int parent)
Deprecated. in C3, use createCDataElementNSWithPrefix()
Creates a new element with input 'prefix' and appends it to the children
 of the indicated parent. An exception will be thrown if 'prefix' is not
 defined in any of the ancestors of new element.

Parameters:
name - local name of new element
prefix - prefix for new element
CDataContent - CDataContent of the new element
parent - handle of parent element. If 0 passed, then new element will
            have no parent
Returns:
handle of created element








createCDataElementNSWithPrefix
public int createCDataElementNSWithPrefix(java.lang.String name,
                                          java.lang.String CDataContent,
                                          java.lang.String prefix,
                                          int parent)
Creates a new CDATA element with input 'prefix' and appends to the parent. 
 An exception will be thrown if 'prefix' is not defined in any of the ancestors of new element.

Parameters:
name - local name of new element
prefix - prefix for new element
CDataContent - Content of the new element
parent - handle of parent element. If 0 passed, then new element will
            have no parent
Returns:
The reference of the created element 

 

         Note:

         This method can't be used before creating a Document object.It
         doesn't restrict the element name to follow XML specification.
         For example,element name shouldn't contain space character as per
         XML specification, but this method allows it. 

 

         // Creates an element which is child to root element as
         "<ns:My Name><![CDATA[abc]]></ns:My
         Name>" 

         doc.createCDataElementNSWithPrefix("My Name","abc", "ns", root); // parent element has namespace 'ns'
 

 

         Example:
 
          
  String xml =
 "<ns:root xmlns:ns="http://cordys.com/test/">
        <ns:employee> Cordys employee </ns:employee>
        <employee1>
                <test> Cordys employee </test>
        </employee1>
 </ns:root>";
 
        Document doc = new com.eibus.xml.nom.Document();
  int root = doc.load(xml);
  int emp = Node.getElement(root, "employee1");
 
 // Creates an element which is child to root element as "<ns:employee2><![CDATA[employee2 data]]></ns:employee2>"
  doc.createCDataElementNSWithPrefix("employee2","employee2 data", "ns", root); // parent element has namespace 'ns'
 
 // Creates an element which is child to employee1 element as "<ns:employee3><![CDATA[employee3 data]]></ns:employee3>"
  doc.createCDataElementNSWithPrefix("employee3","employee3 data", "ns", emp); // parent element has no namespace
 
 
 
 








createCDataElementNS
public int createCDataElementNS(java.lang.String name,
                                java.lang.String CDataContent,
                                java.lang.String prefix,
                                java.lang.String namespaceURI,
                                int parent)
Creates a new CDATA element with input namespace details and appends it
 to the children of the indicated parent.

Parameters:
name - The tagname for the new element
CDataContent - Content of the new element
prefix - 'prefix' for the new element, if the prefix is null then the
            created element will have a default namespace with the given
            namespaceURI.
namespaceURI - namespace URI of the 'prefix'
parent - handle of parent element. If 0 passed, then new element will
            have no parent
Returns:
The reference of the created element 

 

         Note:

         This method can't be used before creating a Document object.It
         doesn't restrict the element name to follow XML specification.
         For example,element name shouldn't contain space character as per
         XML specification, but this method allows it. 

 

         //creates "<prefix:My Name
         xmlns:prefix="http://www.cordys
         .com/test/"><![CDATA[abc]]></prefix:My
         Name>" 

         doc.createCDataElementNS("My Name","abc", "prefix", "http://www.cordys.com/test/", root);
 

 

 

         Example:
 
          
  String xml =
 "<ns:root xmlns:ns="http://cordys.com/test/">
        <ns:employee> Cordys employee </ns:employee>
        <employee1>
                <test> Cordys employee </test>
        </employee1>
 </ns:root>";
 
        Document doc = new com.eibus.xml.nom.Document();
  int root = doc.load(xml);
 
 // Creates an element which is child to root element as "<prefix:employee2 xmlns:prefix="http://www.cordys.com/test/"><![CDATA[employee2 data]]></prefix:employee2>"
  doc.createCDataElementNS("employee2","employee2 data", "prefix", "http://www.cordys.com/test/", root);
 
 
 
 








getStringsMemory
public long getStringsMemory()
Returns allocated memory for string in bytes

Returns:
allocated memory for strings in Bytes
 
 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note><from/></note>";
 int result = 0;
 try {
        result = oDocument.load(xmlStr.getBytes());
        oDocument.getStringsMemory();//Returns the StringsMemory
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }
 
 








getAttributesMemory
@Deprecated
public long getAttributesMemory()
Deprecated. since BOP4-FP1
Returns allocated memory for attributes in Bytes

Returns:
allocated memory for attributes in Bytes
 
 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note a=\"xyz\"><from/></note>";
 try {
        oDocument.load(xmlStr.getBytes());
        oDocument.getAttributesMemory();//returns the AttributesMemory
 } catch (XMLException e) {
        e.printStackTrace();
 }
 
 








getElementsMemory
@Deprecated
public long getElementsMemory()
Deprecated. 
Returns allocated memory for elements in Bytes

Returns:
allocated memory for elements in Bytes 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note a=\"xyz\"><from/></note>";
 try {
        oDocument.load(xmlStr.getBytes());
        oDocument.getElementsMemory();//Returns the ElementsMemory
 } catch (XMLException e) {
        e.printStackTrace();
 }
 
 








getTotalVirtualMemory
public static long getTotalVirtualMemory()
Returns total used virtual memory(elements+attributes).

Returns:
returns the total virtual memory across all active document in
         the jvm. 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note a=\"xyz\"><from/></note>";
 int result = 0;
 try {
        result = oDocument.load(xmlStr.getBytes());
        Document.getTotalVirtualMemory();//Returns the TotalVirtualMemory
 } catch (XMLException e) {
        e.printStackTrace();
 }finally {
        Node.delete(result);
 }
 
 








getTotalHeapMemory
public static long getTotalHeapMemory()
Returns total used Heap memory(Memory used by Strings). This includes the
 memory consumed by all the Document instances.

Returns:
returns the total Heap memory across all active document in the
         jvm. 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr = "<note a=\"xyz\"><from/></note>";
 try {
        oDocument.load(xmlStr.getBytes());
        Document.getTotalHeapMemory();//Returns the TotalHeapMemory
 } catch (XMLException e) {
        e.printStackTrace();
 }
 
 








getTotalDataMemory
@Deprecated
public static long getTotalDataMemory()
Deprecated. use getTotalHeapMemory.
Returns the total memory used by Strings in Bytes. This includes the
 memory consumed by all the Document instances.

Returns:
total memory consumed by all NOM Document instances in this VM,
         measured in Bytes








getTotalNodesMemory
@Deprecated
public static long getTotalNodesMemory()
Deprecated. use getTotalVirtualMemory to get memory allocated for
             elements and attributes together. 

 

             Example:
 
              
 Document oDocument = new Document();
 String xmlStr = "<note a=\"xyz\"><from/></note>";
 try {
        oDocument.load(xmlStr.getBytes());
        Document.getToatalNodesMemory();//Returns the ToatalNodesMemory
 } catch (XMLException e) {
        e.printStackTrace();
 }
 
 
Returns allocated virtual memory for Nodes in Bytes This is the total
 memory used by all XML-Nodes across all NOM Document instances in this
 process

Returns:
allocated memory for nodes in Bytes








getTotalMemory
@Deprecated
public static long getTotalMemory()
Deprecated. Use getTotalVirtualMemory and getTotalHeapMemory. 

 

             Example:
 
              
 Document oDocument = new Document();
 String xmlStr = "<note a=\"xyz\"><from/></note>";
 try {
        oDocument.load(xmlStr.getBytes());
        Document.getToatalMemory();//Returns the ToatalMemory(TotalNodesMemory+TotalDataMemory)
 } catch (XMLException e) {
        e.printStackTrace();
 }
 
 
Returns total allocated for Nodes, attributes, Strings in Bytes This is
 the total memory used by NOM Document instances in this process

Returns:
total memory for nodes in Bytes








getUsedNodesList
public int[] getUsedNodesList()
Returns the root node handles that exist presently in the document

Returns:
array of node handles existing in document
 
 

 

         Example:
 
          
 Document oDocument = new Document();
 String xmlStr1 = "<note/>";
 String xmlStr2 = "<note><to/></note>";
 int result1 = 0;
 int result1 = 0;
 try {
        result1 = oDocument.load(xmlStr1.getBytes());
        result2 = oDocument.load(xmlStr2.getBytes());
        int ret[] = oDocument.getUsedNodesList();
        assertEquals("<note/>", Node.writeToString(ret[0], false));
        assertEquals("<note><to/></note>", Node.writeToString(ret[1], false));
        assertEquals(2, ret.length);
 } catch (XMLException e) {
        e.printStackTrace();
 } finally {
        Node.delete(result1);
        Node.delete(result2);
 }
 
 








getTotalNumDocuments
public static int getTotalNumDocuments()
Returns total active 'Document' instances.

Returns:
returns the total number of documents active in the jvm. 

         The total number of documents is calculated only once a second,
         so frequent calling of this method is without effect.
 
 

 

         Example:
 
          
 Document oDocument1 = new Document();
 Document oDocument2 = new Document();
 String xmlStr1 = "<note/>";
 String xmlStr2 = "<note><to/></note>";
 try {
        oDocument1.load(xmlStr1.getBytes());
        oDocument2.load(xmlStr2.getBytes());
        assertEquals(2, Document.getTotalNumDocuments());
 } catch (XMLException e) {
        e.printStackTrace();
 }
 
 








getTotalNumNodes
public static int getTotalNumNodes()
Returns total used nodes.

Returns:
returns the total number of used nodes across all active document
         active in the jvm. 

         The total number of nodes is calculated only once a second, so
         frequent calling of this method is without effect.
 
 

 

         Example:
 
          
 Document oDocument1 = new Document();
 Document oDocument2 = new Document();
 String xmlStr1 = "<note><from/></note>";
 String xmlStr2 = "<note><to/></note>";
 try {
        oDocument1.load(xmlStr1.getBytes());
        oDocument2.load(xmlStr2.getBytes());
        assertEquals(6, Document.getTotalNumNodes());
 } catch (XMLException e) {
        e.printStackTrace();
 }
 
 
 








getCountOfUsedNodesAndAttr
public static int getCountOfUsedNodesAndAttr()
Gets the Total number of Nodes and Attributes currently used( those are
 not deleted yet) in this JVM. This includes the Document node which
 cannot be accessed by NOM user.

Returns:
The total number of used nodes and attributes across all active
         document active in the jvm. 

 
 

 

         Example:
 
          
 Document oDocument1 = new Document();
 Document oDocument2 = new Document();
 String xmlStr1 = "<note attr="value"><from/></note>";
 String xmlStr2 = "<note><to/></note>";
 int node1 = 0;
 int node2 = 0;
 try {
        node1  = oDocument1.load(xmlStr1.getBytes());
        node2 = oDocument2.load(xmlStr2.getBytes());
        assertEquals(9, Document.getTotalNumNodes());
  
 
 } catch (XMLException e) {
        e.printStackTrace();
 } finally{
        Node.delete(node1);
  Node.delete(node2);
 }
 
 
 








setLeakInfoBaseline
public static void setLeakInfoBaseline()
Initializes 'memory-leak' baseline for XML Nodes. Helps developers to
 identify leaking code. When invoked, a snapshot on the nodes created so
 far is taken and stored. All nodes created after invoking the API are
 considered 'leaked nodes', if not deleted explicitly. 

 

 Note:

 This operation is 'very heavy' (consumes lot of both CPU cycles and
 memory) and should not be used for regular processing, it is recommended
 to use only for debugging purposes. 

 

 Example:
 
  
 int analysis = 0;
 Document tempDoc = null;
 try {
 
        tempDoc = new Document();
 
        Document.setLeakInfoBaseline();
 
        tempDoc.createElement("root3");
        analysis = tempDoc.parseString(Document.getLeakInfo(0,true));
        assertTrue(
                        "The pattern ?<TreeContents><root3> SHOULD BE matched, problems with baseline",
                        XPath.getFirstMatch(".//TreeContents/root3", null, analysis) != 0);
 } finally {
        Document.clearLeakInfoBaseline();
        Node.delete(analysis);
        tempDoc = null;
 }
 
 

See Also:
getLeakInfo(int,boolean), 
clearLeakInfoBaseline()








clearLeakInfoBaseline
public static void clearLeakInfoBaseline()
Clears any existing 'memory-leak' baseline, if already set.
 

 Note:

 This operation should not be used for regular processing. It is
 recommended to use only for debugging purposes. 

 

 Example:
 
  
 int analysis = 0;
 Document tempDoc = null;
 try {
 
        tempDoc = new Document();
 
        Document.setLeakInfoBaseline();
 
        tempDoc.createElement("root3");
        analysis = tempDoc.parseString(Document.getLeakInfo(0,true));
        assertTrue(
                        "The pattern ?<TreeContents><root3> SHOULD BE matched, problems with baseline",
                        XPath.getFirstMatch(".//TreeContents/root3", null, analysis) != 0);
 } finally {
        Document.clearLeakInfoBaseline();
        Node.delete(analysis);
        tempDoc = null;
 }
 
 

See Also:
getLeakInfo(int,boolean), 
setLeakInfoBaseline()








getLeakInfo
@Deprecated
public static java.lang.String getLeakInfo(int newTreesThreshold)
Deprecated. Use getLeakInfo(int newTreesThreshold,boolean
             includeNodeStackTrace). 

 

             Note:

             This operation is 'very heavy' (consumes lot of both CPU
             cycles and memory) and should not be used for regular
             processing, it is recommended to use only for debugging
             purposes. 

 

             Example:
 
              
 int analysis = 0;
 Document tempDoc = null;
 try {
 
        tempDoc = new Document();
 
        Document.setLeakInfoBaseline();
 
        tempDoc.createElement("root3");
        analysis = tempDoc.parseString(Document.getLeakInfo(0,true));
        assertTrue(
                        "The pattern ?<TreeContents><root3> SHOULD BE matched, problems with baseline",
                        XPath.getFirstMatch(".//TreeContents/root3", null, analysis) != 0);
 } finally {
        Document.clearLeakInfoBaseline();
        Node.delete(analysis);
        tempDoc = null;
 }
 
 
Provides detailed information of 'leaked nodes'. Helps developers to
 identify leaking code. Must be invoked after the 'setLeakInfoBaseline' is
 invoked.

Parameters:
newTreesThreshold - Only documents that have more than newTreesThreshold( new
            trees since the baseline is set) are reported as growing. Some
            fluctuation in the number of trees of a document is normal.
            Set this parameter to a value higher than 0 (e.g. 2 or 3) to
            omit this regular fluctuations from the leakage report.
Returns:
A String that contains information about the 'leaked nodes'. The
         description includes the source code location of the 'leaked
         nodes' and the content etc.
See Also:
setLeakInfoBaseline(), 
clearLeakInfoBaseline()








getLeakInfo
public static java.lang.String getLeakInfo(int newTreesThreshold,
                                           boolean includeNodeStackTrace)
Provides detailed information of 'leaked nodes' with option for
 stackTrace information of nodes. Helps developers to identify leaking
 code. Must be invoked after the 'setLeakInfoBaseline' is invoked.

Parameters:
newTreesThreshold - Only documents that have more than newTreesThreshold( new
            trees since the baseline is set) are reported as growing. Some
            fluctuation in the number of trees of a document is normal.
            Set this parameter to a value higher than 0 (e.g. 2 or 3) to
            omit this regular fluctuations from the leakage report.
includeNodeStackTrace - Option to include stackTrace information of nodes.If it is
            true, then allocation stack trace is reported for leaking
            nodes.
Returns:
A String that contains information about the 'leaked nodes'. The
         description includes the source code location of the 'leaked
         nodes' and the content etc. 

 

         Note:

         This operation is 'very heavy' (consumes lot of both CPU cycles
         and memory) and should not be used for regular processing, it is
         recommended to use only for debugging purposes. 

         This method will give stackTrace only for nodes that are created
         using Java API. 

 

         Example:
 
          
 int analysis = 0;
 Document tempDoc = null;
 try {
 
        tempDoc = new Document();
 
        Document.setLeakInfoBaseline();
 
        tempDoc.createElement("root3");
        analysis = tempDoc.parseString(Document.getLeakInfo(0,false));
        assertTrue(
                        "The pattern ?<TreeContents><root3> SHOULD BE matched, problems with baseline",
                        XPath.getFirstMatch(".//NewTree/AllocationStackTrace", null, analysis) != 1);
 } finally {
        Document.clearLeakInfoBaseline();
        Node.delete(analysis);
        tempDoc = null;
 }
 
 
See Also:
setLeakInfoBaseline(), 
clearLeakInfoBaseline()








getInstantiationStackTrace
public static java.lang.String getInstantiationStackTrace()
Provides detailed instantiation StackTrace information of all the
 instances of Document objects.

Returns:
A String containing the StackTrace Information. It includes the
         source code location of document creation.

Class Document

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Document

Method Detail

finalize

getHandle

setXMLExceptionsEnable

setDeletionTrace

isXMLExceptionsEnable

load

load

loadByPreserveSpace

load

loadByPreserveSpace

load

parseString

parseString

loadByPreserveSpace

parseStringByPreserveSpace

parseStringByPreserveSpace

createElement

createElement

createComment

createText

createText

createTextElement

createTextElement

lock

unlock

getNumUsedNodes

includeWhiteSpacesByParsing

includeCommentsByParsing

equals

hashCode

toString

createCData

createCDataElement

createCDataElement

includeWhiteSpacesByParsing

enableInvalidUriErrorSuppression

includeCommentsByParsing

addDocumentCreationEventListener

removeDocumentCreationEventListener

isDocumentCreationStackTracesEnabled

createElementNS

createElementWithParentNS

createElementNS

createElementNSWithPrefix

createElementNS

createCDataElementNS

createCDataElementWithParentNS

createCDataElementNS

createCDataElementNSWithPrefix

createCDataElementNS

getStringsMemory

getAttributesMemory

getElementsMemory

getTotalVirtualMemory

getTotalHeapMemory

getTotalDataMemory

getTotalNodesMemory

getTotalMemory

getUsedNodesList

getTotalNumDocuments

getTotalNumNodes

getCountOfUsedNodesAndAttr

setLeakInfoBaseline

clearLeakInfoBaseline

getLeakInfo

getLeakInfo

getInstantiationStackTrace