com.quadrique.jbuildingblocks.core.xml.dom
Class JbbDom

java.lang.Object
  com.quadrique.jbuildingblocks.core.xml.dom.JbbDom

public class JbbDom
extends Object

This class provides convenience methods to manipulate any XML data with the DOM api (http://www.w3.org/TR/DOM-Level-2-Core/ and http://www.w3.org/TR/DOM-Level-3-Core/)

Since:

August 16, 2000

Version:

1.0.0

Author:

Hervé Rivere

Constructor Summary

JbbDom()

Method Summary

boolean	areEqual(Node node, Node otherNode) This tells you whether the two nodes are equal in characteristics.
boolean	areSame(Node node, Node otherNode) This tells you whether what you are looking at are proxies to the same object or objects that are actually different.Returns false if any of the arguments is null.
short	comparePosition(Node node, Node otherNode) This method allows you to find out how two nodes are positioned with respect to each other in the document tree.
Document	createDocument() create an empty Document instance
Document	createDocumentFromSerializedXml(String zXmlString, boolean zValidate) create a Document instance from the given string
Document	createDocumentFromSerializedXml(String zXmlString, boolean zValidate, String encoding) create a Document instance from the given string
Document	createDocumentFromSerializedXmlStream(File zFile, boolean zValidate) create a Document instance from the given file
Document	createDocumentFromSerializedXmlStream(File zFile, boolean zValidate, String encoding) create a Document instance from the given file
Document	createDocumentFromSerializedXmlStream(InputStream zXmlStream, boolean zValidate) create a Document instance from the given stream
Document	createDocumentFromSerializedXmlStream(InputStream zXmlStream, boolean zValidate, String encoding) create a Document instance from the given stream
Element	createElement(Document zDocument, String zTagName) create an element with the given tag name.
Element	createElement(Document zDocument, String zTagName, boolean zValue) create an element with an associated text node underneath i.e.
Element	createElement(Document zDocument, String zTagName, double zValue) create an element with an associated text node underneath i.e.
Element	createElement(Document zDocument, String zTagName, float zValue) create an element with an associated text node underneath i.e.
Element	createElement(Document zDocument, String zTagName, int zValue) create an element with an associated text node underneath i.e.
Element	createElement(Document zDocument, String zTagName, long zValue) create an element with an associated text node underneath i.e.
Element	createElement(Document zDocument, String zTagName, String zText) create an element with the given tag name.
Element	createElement(Document zDocument, String zParentTagName, String zTagName, ArrayList<String> zValues) create an element with the given tag name and attach it to the given element If zValues is null, the method simply creates an element (i.e.
Element	createElement(Element zElement, String zTagName) create an element with the given tag name and attach it to the given element If zText is null, the method simply creates an element (i.e.
Element	createElement(Element zElement, String zTagName, boolean zValue) create an element with the given tag name and attach it to the given element.
Element	createElement(Element zElement, String zTagName, double zValue) create an element with the given tag name and attach it to the given element.
Element	createElement(Element zElement, String zTagName, float zValue) create an element with the given tag name and attach it to the given element.
Element	createElement(Element zElement, String zTagName, int zValue) create an element with the given tag name and attach it to the given element.
Element	createElement(Element zElement, String zTagName, long zValue) create an element with the given tag name and attach it to the given element.
Element	createElement(Element zElement, String zTagName, String zText) create an element with the given tag name and attach it to the given element If zText is null, the method simply creates an element (i.e.
Element	createElement(Element zElement, String zParentTagName, String zTagName, ArrayList<String> zValues) create an element with the given tag name and attach it to the given element If zValues is null, the method simply creates an element (i.e.
Element	createElementCData(Document zDocument, String zTagName, String zText) create an element with the given tag name.
Element	createElementCData(Element zElement, String zTagName, String zText) create an element with the given tag name and attach it to the given element If zText is null, the method simply creates an element (i.e.
Element	createElementRoot(Document zDocument, String zTagName) create a root element with the given tag name in the given document.
Element	createElementRoot(Document zDocument, String zTagName, String zText) create a root element with the given tag name in the given document.
Element	createElementRootWithAttribute(Document zDocument, String zTagName, String zAttributeName, String zAttributeValue) create a root element with an attribute i.e.
String	getAttributeValue(Document zDocument, String zTagName, String zAttributeName) To retrieve the value of an attribute of a given element (i.e.
String	getAttributeValue(Element zElement, String zAttributeName) To retrieve the value of an attribute of a given element (i.e.
boolean	getAttributeValueAsBool(Document zDocument, String zTagName, String zAttributeName)
boolean	getAttributeValueAsBool(Element zElement, String zAttributeName)
double	getAttributeValueAsDouble(Document zDocument, String zTagName, String zAttributeName)
double	getAttributeValueAsDouble(Element zElement, String zAttributeName)
float	getAttributeValueAsFloat(Document zDocument, String zTagName, String zAttributeName)
float	getAttributeValueAsFloat(Element zElement, String zAttributeName)
int	getAttributeValueAsInt(Document zDocument, String zTagName, String zAttributeName)
int	getAttributeValueAsInt(Element zElement, String zAttributeName)
long	getAttributeValueAsLong(Document zDocument, String zTagName, String zAttributeName)
long	getAttributeValueAsLong(Element zElement, String zAttributeName)
Element	getElement(Document zDocument, String zTagName)
Element	getElement(Document zDocument, String zParentTagName, String zTagName)
Element	getElement(Element zElement, String zTagName)
Element	getElement(Element zElement, String zParentTagName, String zTagName)
String	getElementCDataValue(Document zDocument, String zTagName)
String	getElementCDataValue(Element zElement)
String	getElementCDataValue(Element zElement, String zTagName)
String	getElementCDataValue(Element zElement, String zParentTagName, String zTagName)
ArrayList<Element>	getElements(Document zDocument, String zTagName)
ArrayList<Element>	getElements(Document zDocument, String zParentTagName, String zTagName)
ArrayList<Element>	getElements(Element element)
ArrayList<Element>	getElements(Element zElement, String zTagName)
ArrayList<Element>	getElements(Element zElement, String zParentTagName, String zTagName)
String	getElementValue(Document zDocument, String zTagName)
String	getElementValue(Element zElement)
String	getElementValue(Element zElement, String zTagName)
String	getElementValue(Element zElement, String zParentTagName, String zTagName)
boolean	getElementValueAsBool(Document zDocument, String zTagName)
boolean	getElementValueAsBool(Element zElement, String zTagName)
boolean	getElementValueAsBool(Element zElement, String zParentTagName, String zTagName)
double	getElementValueAsDouble(Document zDocument, String zTagName)
double	getElementValueAsDouble(Element zElement, String zTagName)
double	getElementValueAsDouble(Element zElement, String zParentTagName, String zTagName)
float	getElementValueAsFloat(Document zDocument, String zTagName)
float	getElementValueAsFloat(Element zElement, String zTagName)
float	getElementValueAsFloat(Element zElement, String zParentTagName, String zTagName)
int	getElementValueAsInt(Document zDocument, String zTagName)
int	getElementValueAsInt(Element zElement, String zTagName)
int	getElementValueAsInt(Element zElement, String zParentTagName, String zTagName)
long	getElementValueAsLong(Document zDocument, String zTagName)
long	getElementValueAsLong(Element zElement, String zTagName)
long	getElementValueAsLong(Element zElement, String zParentTagName, String zTagName)
ArrayList<String>	getElementValues(Document zDocument, String zTagName) To retrieve the value of the text elements with the given tag name in the Document (i.e.
ArrayList<String>	getElementValues(Document zDocument, String zParentTagName, String zTagName) To retrieve the value of the text elements with the given parent tag name and tag name in the Document (i.e.
ArrayList<String>	getElementValues(Element zElement, String zTagName) To retrieve the value of the text elements with the given tag name in the given Element (i.e.
ArrayList<String>	getElementValues(Element zElement, String zParentTagName, String zTagName) To retrieve the value of the text elements with the given parent tag name and tag name in the Element (i.e.
void	importDocument(Document zDocument, Element zParentElement, Document zDocumentToImport) import the given document as a child to the given parent element
void	importElement(Document zDocument, Element zParentElement, Document zDocumentToImportFrom, String zTag)
void	importElement(Element zParentElementFromDocument1, Element zChildElementFromDocument2) To import a DOM subtree from another document into a document.
boolean	isAncestor(Node node, Node otherNode) will return true if otherNode is ancestor of node in the document.
boolean	isDescendant(Node node, Node otherNode) will return true if otherNode is descendant node in the document.
boolean	isFollowing(Node node, Node otherNode) will return true if otherNode is follows node in the document.
boolean	isPreceding(Node node, Node otherNode) will return true if otherNode is precedes node in the document.
static JbbDom	newInstance()
void	removeElement(Element zElement) remove the given element from its document
String	serialize(Document zDoc) serialize the given DOM subtree in a string
String	serialize(Document doc, String encoding) serialize the given DOM document in a String with the given encoding
String	serialize(Element zElement) serialize the given DOM subtree in a string
String	serialize(Element zElement, String encoding) serialize the given DOM subtree in a string with the given encoding
void	serializeToStream(Document document, OutputStream stream) serialize the given DOM document in a stream with the default encoding
void	serializeToStream(Document document, OutputStream stream, String encoding) serialize the given DOM document in a stream with given encoding
void	serializeToStream(Element zElement, OutputStream zStream) serialize the given DOM subtree in a stream
void	serializeToStream(Element zElement, OutputStream zStream, String encoding) serialize the given DOM subtree in a stream with given encoding
void	setAttributeValue(Element zElement, String zAttrName, boolean zAttrValue) to set (including creation) the value of an attribute for a given element
void	setAttributeValue(Element zElement, String zAttrName, double zAttrValue) to set (including creation) the value of an attribute for a given element
void	setAttributeValue(Element zElement, String zAttrName, float zAttrValue) to set (including creation) the value of an attribute for a given element
void	setAttributeValue(Element zElement, String zAttrName, int zAttrValue) to set (including creation) the value of an attribute for a given element
void	setAttributeValue(Element zElement, String zAttrName, long zAttrValue) to set (including creation) the value of an attribute for a given element
void	setAttributeValue(Element zElement, String zAttrName, String zAttrValue) to set (including creation) the value of an attribute for a given element
void	setElementValue(Document zDocument, String zTagName, String zElementValue) To set the value of a given text element (i.e.
void	setElementValue(Element zElement, String zTagName, String zElementValue) To set the value of a given text element (i.e.
void	setElementValues(Document zDocument, String zParentTagName, String zChildTagName, ArrayList<String> zElementValues) To set the text values of a given element (i.e.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JbbDom

public JbbDom()

Method Detail

newInstance

public static JbbDom newInstance()

Returns:

new instance of the JbbDom class. JbbDom lHandler = JbbDom.newInstance();

createDocument

public Document createDocument()
                        throws Exception

create an empty Document instance

Returns:

an empty Document instance

Throws:

Exception - whenever an error occur

createDocumentFromSerializedXml

public Document createDocumentFromSerializedXml(String zXmlString,
                                                boolean zValidate)
                                         throws Exception

create a Document instance from the given string

Parameters:

zXmlString - a string containing the linearized Xml document

zValidate - true if the document is to be validated

Returns:

the DOM Document instance

Throws:

Exception - whenever an error occur

createDocumentFromSerializedXml

public Document createDocumentFromSerializedXml(String zXmlString,
                                                boolean zValidate,
                                                String encoding)
                                         throws Exception

create a Document instance from the given string

Parameters:

zXmlString - a string containing the linearized Xml document

zValidate - true if the document is to be validated

encoding - encoding such as "UTF-8"

Returns:

the DOM Document instance

Throws:

Exception - whenever an error occur

createDocumentFromSerializedXmlStream

public Document createDocumentFromSerializedXmlStream(InputStream zXmlStream,
                                                      boolean zValidate)
                                               throws Exception

create a Document instance from the given stream

Parameters:

zXmlStream - an input stream

zValidate - true if the document is to be validated

Returns:

the DOM Document instance

Throws:

Exception - whenever an error occur

createDocumentFromSerializedXmlStream

public Document createDocumentFromSerializedXmlStream(InputStream zXmlStream,
                                                      boolean zValidate,
                                                      String encoding)
                                               throws Exception

create a Document instance from the given stream

Parameters:

zXmlStream - an input stream

zValidate - true if the document is to be validated

encoding - such as "UTF-8" "US-ASCII" Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set "ISO-8859-1" ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1 "UTF-8" Eight-bit UCS Transformation Format "UTF-16BE" Sixteen-bit UCS Transformation Format, big-endian byte order "UTF-16LE" Sixteen-bit UCS Transformation Format, little-endian byte order "UTF-16" Sixteen-bit UCS Transformation Format, byte order identified by an optional byte-order mark

Returns:

the DOM Document instance

Throws:

Exception - whenever an error occur

createDocumentFromSerializedXmlStream

public Document createDocumentFromSerializedXmlStream(File zFile,
                                                      boolean zValidate)
                                               throws Exception

create a Document instance from the given file

Parameters:

zFile - an input stream

zValidate - true if the document is to be validated

Returns:

the DOM Document instance

Throws:

Exception - whenever an error occur

createDocumentFromSerializedXmlStream

public Document createDocumentFromSerializedXmlStream(File zFile,
                                                      boolean zValidate,
                                                      String encoding)
                                               throws Exception

create a Document instance from the given file

Parameters:

zFile - an input stream

zValidate - true if the document is to be validated

encoding - such as UTF-8

Returns:

the DOM Document instance

Throws:

Exception - whenever an error occur

createElement

public Element createElement(Document zDocument,
                             String zTagName)

create an element with the given tag name. Please note that the newly created Element instance is not "attached" to the given document. You must call "appendChild()" either ton the Document root or on a child Element to add it to the document

Parameters:

zDocument - the document

zTagName - the name of the tag

Returns:

the element

createElement

public Element createElement(Document zDocument,
                             String zTagName,
                             String zText)

create an element with the given tag name. Please note that the newly created Element instance is not "attached" to the given document. You must call "appendChild()" either ton the Document root or on a child Element to add it to the document If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child text node to hold the given value (i.e. zText).

Parameters:

zDocument - the document

zTagName - the name of the tag

zText - the text to put between the tags. Use null if you don't want to create a child text node (Please note that "" is valid and will result in the creation of a text node)

Returns:

the element

createElement

public Element createElement(Document zDocument,
                             String zParentTagName,
                             String zTagName,
                             ArrayList<String> zValues)

create an element with the given tag name and attach it to the given element If zValues is null, the method simply creates an element (i.e. ) If zValues is not null and not empty, the method creates subelements with child text node to hold the given values (i.e. zValue1...zValueN).

Parameters:

zParentTagName -

zTagName -

zValues -

Returns:

element

createElementCData

public Element createElementCData(Document zDocument,
                                  String zTagName,
                                  String zText)

create an element with the given tag name. Please note that the newly created Element instance is not "attached" to the given document. You must call "appendChild()" either ton the Document root or on a child Element to add it to the document If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child CDATA node to hold the given value (i.e. ![CDATA[zText]]).

Parameters:

zDocument - the document

zTagName - the name of the tag

zText - the text to put between the tags. Use null if you don't want to create a child CDATA node (Please note that "" is valid and will result in the creation of a CDATA node)

Returns:

the element

createElement

public Element createElement(Document zDocument,
                             String zTagName,
                             int zValue)
                      throws Exception

create an element with an associated text node underneath i.e. the following: zValue

Parameters:

zDocument - the document

zTagName - the name of the tag

zValue - the integer value

Returns:

the element

Throws:

Exception

createElement

public Element createElement(Document zDocument,
                             String zTagName,
                             long zValue)
                      throws Exception

create an element with an associated text node underneath i.e. the following: zValue

Parameters:

zDocument - the document

zTagName - the name of the tag

zValue - the long value

Returns:

the element

Throws:

Exception

createElement

public Element createElement(Document zDocument,
                             String zTagName,
                             float zValue)
                      throws Exception

create an element with an associated text node underneath i.e. the following: zValue

Parameters:

zDocument - the document

zTagName - the name of the tag

zValue - the float value

Returns:

the element

Throws:

Exception

createElement

public Element createElement(Document zDocument,
                             String zTagName,
                             double zValue)
                      throws Exception

create an element with an associated text node underneath i.e. the following: zValue

Parameters:

zDocument - the document

zTagName - the name of the tag

zValue - the double value

Returns:

the element

Throws:

Exception

createElement

public Element createElement(Document zDocument,
                             String zTagName,
                             boolean zValue)

create an element with an associated text node underneath i.e. the following: zValue

Parameters:

zDocument - the document

zTagName - the name of the tag

zValue - the boolean value

Returns:

the element

createElement

public Element createElement(Element zElement,
                             String zTagName,
                             String zText)

create an element with the given tag name and attach it to the given element If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child text node to hold the given value (i.e. zText).

Parameters:

zElement - the element

zTagName - the name of the tag

zText - the text to put between the tags. Use null if you don't want to create a child text node (Please note that "" is valid and will result in the creation of a text node)

Returns:

the element

createElement

public Element createElement(Element zElement,
                             String zTagName)

create an element with the given tag name and attach it to the given element If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child text node to hold the given value (i.e. zText).

Parameters:

zElement - the element

zTagName - the name of the tag

Returns:

the element

createElement

public Element createElement(Element zElement,
                             String zParentTagName,
                             String zTagName,
                             ArrayList<String> zValues)

create an element with the given tag name and attach it to the given element If zValues is null, the method simply creates an element (i.e. ) If zValues is not null and not empty, the method creates subelements with child text node to hold the given values (i.e. zValue1...zValueN).

Parameters:

zParentTagName -

zTagName -

zValues -

Returns:

element

createElementCData

public Element createElementCData(Element zElement,
                                  String zTagName,
                                  String zText)

create an element with the given tag name and attach it to the given element If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child CDATA node to hold the given value (i.e. ![CDATA[zText]]).

Parameters:

zElement - the element

zTagName - the name of the tag

zText - the CDATA text to put between the tags. Use null if you don't want to create a child CDATA node (Please note that "" is valid and will result in the creation of a CDATA node)

Returns:

the element

createElement

public Element createElement(Element zElement,
                             String zTagName,
                             long zValue)
                      throws Exception

create an element with the given tag name and attach it to the given element. If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child text node to hold the given value (i.e. zText).

Parameters:

zElement - the element

zTagName - the name of the tag

zValue - the long value

Returns:

the element

Throws:

Exception

createElement

public Element createElement(Element zElement,
                             String zTagName,
                             float zValue)
                      throws Exception

create an element with the given tag name and attach it to the given element. If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child text node to hold the given value (i.e. zText).

Parameters:

zElement - the element

zTagName - the name of the tag

zValue - the float value

Returns:

the element

Throws:

Exception

createElement

public Element createElement(Element zElement,
                             String zTagName,
                             double zValue)
                      throws Exception

create an element with the given tag name and attach it to the given element. If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child text node to hold the given value (i.e. zText).

Parameters:

zElement - the element

zTagName - the name of the tag

zValue - the long value

Returns:

the element

Throws:

Exception

createElement

public Element createElement(Element zElement,
                             String zTagName,
                             int zValue)
                      throws Exception

create an element with the given tag name and attach it to the given element. If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child text node to hold the given value (i.e. zText).

Parameters:

zElement - the element

zTagName - the name of the tag

zValue - the integer value

Returns:

the element

Throws:

Exception

createElement

public Element createElement(Element zElement,
                             String zTagName,
                             boolean zValue)
                      throws Exception

create an element with the given tag name and attach it to the given element. If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child text node to hold the given value (i.e. zText).

Parameters:

zElement - the element

zTagName - the name of the tag

zValue - the boolean value

Returns:

the element

Throws:

Exception

createElementRoot

public Element createElementRoot(Document zDocument,
                                 String zTagName)

create a root element with the given tag name in the given document. If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child text node to hold the given value (i.e. zText).

Parameters:

zDocument - the document

zTagName - the name of the tag

Returns:

the element

createElementRoot

public Element createElementRoot(Document zDocument,
                                 String zTagName,
                                 String zText)

create a root element with the given tag name in the given document. If zText is null, the method simply creates an element (i.e. ) If zText is not null and not empty, the method creates an element and a child text node to hold the given value (i.e. zText).

Parameters:

zDocument - the document

zTagName - the name of the tag

zText - the text to put between the tags (use null if you don't want to create a child text node)

Returns:

the element

createElementRootWithAttribute

public Element createElementRootWithAttribute(Document zDocument,
                                              String zTagName,
                                              String zAttributeName,
                                              String zAttributeValue)

create a root element with an attribute i.e. the following:

Parameters:

zDocument - the document

zTagName - the name of the root tag

zAttributeName - the name of the attribute

zAttributeValue - the value of the attribute

Returns:

the element

getElement

public Element getElement(Document zDocument,
                          String zTagName)
                   throws Exception

Parameters:

zDocument - the document

zTagName - the tag name

Returns:

the first element that match the given tag name in the document (null otherwise)

Throws:

Exception

getElement

public Element getElement(Document zDocument,
                          String zParentTagName,
                          String zTagName)
                   throws Exception

Returns:

the first element that match the given tag names in the document (null otherwise)

Throws:

Exception

getElement

public Element getElement(Element zElement,
                          String zTagName)
                   throws Exception

Parameters:

zElement - the parent element

zTagName - the element tag name to search for (under the given element)

Returns:

the first element that match the given tag name in the Element (null otherwise)

Throws:

Exception

getElement

public Element getElement(Element zElement,
                          String zParentTagName,
                          String zTagName)
                   throws Exception

Returns:

the first element that match the given tag names in the element (null otherwise)

Throws:

Exception

getElements

public ArrayList<Element> getElements(Document zDocument,
                                      String zTagName)
                               throws Exception

Parameters:

zDocument - the DOM document

zTagName - the element tag name to search for

Returns:

an ArrayList that contains all the Element instances that match the given tag name in the Document (null otherwise)

Throws:

Exception

getElements

public ArrayList<Element> getElements(Element zElement,
                                      String zTagName)
                               throws Exception

Parameters:

zElement - the parent element

zTagName - the element tag name to search for (under the given element)

Returns:

an ArrayList that contains all the Element instances that match the given tag name in the Element (null otherwise)

Throws:

Exception

getElements

public ArrayList<Element> getElements(Element element)
                               throws Exception

Parameters:

zElement -

zTagName -

Returns:

all the children elements of the given element

Throws:

Exception

getElements

public ArrayList<Element> getElements(Document zDocument,
                                      String zParentTagName,
                                      String zTagName)
                               throws Exception

Returns:

an ArrayList that contains all the Element instances that match the given tag names in the Document (null otherwise)

Throws:

Exception

getElements

public ArrayList<Element> getElements(Element zElement,
                                      String zParentTagName,
                                      String zTagName)
                               throws Exception

Returns:

an ArrayList that contains all the Element instances that match the given tag names in the Element (null otherwise)

Throws:

Exception

getElementValue

public String getElementValue(Document zDocument,
                              String zTagName)
                       throws Exception

Parameters:

zDocument - the DOM document

zTagName - the element tag name to search for

Returns:

the value of the first element that match the given tag name in the Document (null otherwise)

Throws:

Exception

getElementValue

public String getElementValue(Element zElement,
                              String zTagName)
                       throws Exception

Returns:

the value of the first element that match the given tag name in the Element (null otherwise)

Throws:

Exception

getElementValue

public String getElementValue(Element zElement,
                              String zParentTagName,
                              String zTagName)
                       throws Exception

Returns:

the value of the first element that match the given tag names in the Element (null otherwise)

Throws:

Exception

getElementValue

public String getElementValue(Element zElement)
                       throws Exception

Returns:

the value of the element. If the Element is a text node (e.g. text), the method returns the text value (i.e. "text" if the element is text). If the element is not a text node, the method returns null.

Throws:

Exception

getElementCDataValue

public String getElementCDataValue(Document zDocument,
                                   String zTagName)
                            throws Exception

Parameters:

zDocument - the DOM document

zTagName - the element tag name to search for

Returns:

the CDATA value of the first element that match the given tag name in the Document (null otherwise)

Throws:

Exception

getElementCDataValue

public String getElementCDataValue(Element zElement,
                                   String zTagName)
                            throws Exception

Returns:

the CDATA value of the first element that match the given tag name in the Element (null otherwise)

Throws:

Exception

getElementCDataValue

public String getElementCDataValue(Element zElement,
                                   String zParentTagName,
                                   String zTagName)
                            throws Exception

Returns:

the CDATA value of the first element that match the given tag names in the Element (null otherwise)

Throws:

Exception

getElementCDataValue

public String getElementCDataValue(Element zElement)
                            throws Exception

Returns:

the CDATA value of the element. If the Element is a CDATA node (e.g. ), the method returns the CDATA value (i.e. "text" if the element is ). If the element is not a CDATA node, the method returns null.

Throws:

Exception

getElementValueAsInt

public int getElementValueAsInt(Document zDocument,
                                String zTagName)
                         throws Exception

Returns:

the value of the first element that match the given tag name in the Document (null otherwise)

Throws:

Exception

getElementValueAsInt

public int getElementValueAsInt(Element zElement,
                                String zTagName)
                         throws Exception

Returns:

the value of the first element that match the given tag name in the Element (null otherwise)

Throws:

Exception

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsInt

public int getElementValueAsInt(Element zElement,
                                String zParentTagName,
                                String zTagName)
                         throws Exception

Returns:

the value of the first element that match the given tag name in the Element (null otherwise)

Throws:

Exception

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsLong

public long getElementValueAsLong(Document zDocument,
                                  String zTagName)
                           throws Exception

Returns:

the value of the first element that match the given tag name in the Document (null otherwise)

Throws:

Exception

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsLong

public long getElementValueAsLong(Element zElement,
                                  String zTagName)
                           throws Exception

Returns:

the value of the first element that match the given tag name in the Element

Throws:

Exception - if the value is not found or could not be converted

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsLong

public long getElementValueAsLong(Element zElement,
                                  String zParentTagName,
                                  String zTagName)
                           throws Exception

Returns:

the value of the first element that match the given tag name in the Element

Throws:

Exception - if the value is not found or could not be converted

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsFloat

public float getElementValueAsFloat(Document zDocument,
                                    String zTagName)
                             throws Exception

Returns:

the value of the first element that match the given tag name in the Document (null otherwise)

Throws:

Exception

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsFloat

public float getElementValueAsFloat(Element zElement,
                                    String zTagName)
                             throws Exception

Returns:

the value of the first element that match the given tag name in the Element

Throws:

Exception - if the value is not found or could not be converted

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsFloat

public float getElementValueAsFloat(Element zElement,
                                    String zParentTagName,
                                    String zTagName)
                             throws Exception

Returns:

the value of the first element that match the given tag names in the Element

Throws:

Exception - if the value is not found or could not be converted

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsDouble

public double getElementValueAsDouble(Document zDocument,
                                      String zTagName)
                               throws Exception

Returns:

the value of the first element that match the given tag name in the Document (null otherwise)

Throws:

Exception

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsDouble

public double getElementValueAsDouble(Element zElement,
                                      String zTagName)
                               throws Exception

Returns:

the value of the first element that match the given tag name in the Element

Throws:

Exception - if the value is not found or could not be converted

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsDouble

public double getElementValueAsDouble(Element zElement,
                                      String zParentTagName,
                                      String zTagName)
                               throws Exception

Returns:

the value of the first element that match the given tag names in the Element

Throws:

Exception - if the value is not found or could not be converted

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsBool

public boolean getElementValueAsBool(Document zDocument,
                                     String zTagName)
                              throws Exception

Returns:

the value of the first element that match the given tag name in the Document (null otherwise)

Throws:

Exception

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsBool

public boolean getElementValueAsBool(Element zElement,
                                     String zTagName)
                              throws Exception

Returns:

the value of the first element that match the given tag name in the Element (null otherwise)

Throws:

Exception

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValueAsBool

public boolean getElementValueAsBool(Element zElement,
                                     String zParentTagName,
                                     String zTagName)
                              throws Exception

Returns:

the value of the first element that match the given tag names in the Element (null otherwise)

Throws:

Exception

See Also:

getElementValue(org.w3c.dom.Document, java.lang.String)

getElementValues

public ArrayList<String> getElementValues(Document zDocument,
                                          String zTagName)
                                   throws Exception

To retrieve the value of the text elements with the given tag name in the Document (i.e. the asumption is that the xml document is of the form: " ... zElementValue zElementValue ... ").

Parameters:

zTagName - the tag name of the element

Returns:

null if the element was not found, an ArrayList of the corresponding text values

Throws:

Exception

getElementValues

public ArrayList<String> getElementValues(Document zDocument,
                                          String zParentTagName,
                                          String zTagName)
                                   throws Exception

To retrieve the value of the text elements with the given parent tag name and tag name in the Document (i.e. the asumption is that the xml document is of the form: " ... ... zElementValue zElementValue ... ... ").

Parameters:

zParentTagName - the tag name of the parent element

zTagName - the tag name of the element

Returns:

null if the element was not found, an ArrayList of the corresponding text values

Throws:

Exception

getElementValues

public ArrayList<String> getElementValues(Element zElement,
                                          String zTagName)
                                   throws Exception

To retrieve the value of the text elements with the given tag name in the given Element (i.e. the asumption is that the xml document is of the form: " ... ... zElementValue zElementValue ... ... ").

Parameters:

zTagName - the tag name of the element

Returns:

null if the element was not found, an ArrayList of the corresponding text values

Throws:

Exception

getElementValues

public ArrayList<String> getElementValues(Element zElement,
                                          String zParentTagName,
                                          String zTagName)
                                   throws Exception

To retrieve the value of the text elements with the given parent tag name and tag name in the Element (i.e. the asumption is that the xml document is of the form: " ... ... zElementValue zElementValue ... ... ").

Parameters:

zParentTagName - the tag name of the parent element

zTagName - the tag name of the element

Returns:

null if the element was not found, an ArrayList of the corresponding text values

Throws:

Exception

getAttributeValue

public String getAttributeValue(Document zDocument,
                                String zTagName,
                                String zAttributeName)
                         throws Exception

To retrieve the value of an attribute of a given element (i.e. the asumption is that the xml document is of the form: "......"). If there is more than one matching element, the first element is chosen.

Parameters:

zTagName - the tag name of the element

zAttributeName - the attribute name

Returns:

null if the element or attribute was not found, the attribute value otherwise.

Throws:

Exception

getAttributeValueAsInt

public int getAttributeValueAsInt(Document zDocument,
                                  String zTagName,
                                  String zAttributeName)
                           throws Exception

Throws:

Exception

See Also:

getAttributeValue(org.w3c.dom.Document, java.lang.String, java.lang.String)

getAttributeValueAsLong

public long getAttributeValueAsLong(Document zDocument,
                                    String zTagName,
                                    String zAttributeName)
                             throws Exception

Returns:

the attribute value as a long

Throws:

Exception

See Also:

getAttributeValue(org.w3c.dom.Document, java.lang.String, java.lang.String)

getAttributeValueAsFloat

public float getAttributeValueAsFloat(Document zDocument,
                                      String zTagName,
                                      String zAttributeName)
                               throws Exception

Returns:

the attribute value as a int

Throws:

Exception

See Also:

getAttributeValue(org.w3c.dom.Document, java.lang.String, java.lang.String)

getAttributeValueAsDouble

public double getAttributeValueAsDouble(Document zDocument,
                                        String zTagName,
                                        String zAttributeName)
                                 throws Exception

Returns:

the attribute value as a double

Throws:

Exception

See Also:

getAttributeValue(org.w3c.dom.Document, java.lang.String, java.lang.String)

getAttributeValueAsBool

public boolean getAttributeValueAsBool(Document zDocument,
                                       String zTagName,
                                       String zAttributeName)
                                throws Exception

Returns:

the attribute value as a boolean

Throws:

Exception

See Also:

getAttributeValue(org.w3c.dom.Document, java.lang.String, java.lang.String)

getAttributeValue

public String getAttributeValue(Element zElement,
                                String zAttributeName)
                         throws Exception

To retrieve the value of an attribute of a given element (i.e. the asumption is that the xml document is of the form: "......"). If there is more than one matching element, the first element is chosen.

Parameters:

zElement - the element

zAttributeName - the attribute name

Returns:

null if the element or attribute was not found, the attribute value otherwise.

Throws:

Exception

getAttributeValueAsInt

public int getAttributeValueAsInt(Element zElement,
                                  String zAttributeName)
                           throws Exception

Returns:

the attribute value as an int

Throws:

Exception

See Also:

getAttributeValue(org.w3c.dom.Document, java.lang.String, java.lang.String)

getAttributeValueAsLong

public long getAttributeValueAsLong(Element zElement,
                                    String zAttributeName)
                             throws Exception

Returns:

the attribute value as a long

Throws:

Exception

See Also:

getAttributeValue(org.w3c.dom.Document, java.lang.String, java.lang.String)

getAttributeValueAsFloat

public float getAttributeValueAsFloat(Element zElement,
                                      String zAttributeName)
                               throws Exception

Returns:

the attribute value as a float

Throws:

Exception

See Also:

getAttributeValue(org.w3c.dom.Document, java.lang.String, java.lang.String)

getAttributeValueAsDouble

public double getAttributeValueAsDouble(Element zElement,
                                        String zAttributeName)
                                 throws Exception

Returns:

the attribute value as a double

Throws:

Exception

See Also:

getAttributeValue(org.w3c.dom.Document, java.lang.String, java.lang.String)

getAttributeValueAsBool

public boolean getAttributeValueAsBool(Element zElement,
                                       String zAttributeName)
                                throws Exception

Returns:

the attribute value as a boolean

Throws:

Exception

See Also:

getAttributeValue(org.w3c.dom.Document, java.lang.String, java.lang.String)

setAttributeValue

public void setAttributeValue(Element zElement,
                              String zAttrName,
                              String zAttrValue)
                       throws Exception

to set (including creation) the value of an attribute for a given element

Parameters:

zElement - the element

zAttrName - the name of the attribute (please note that there cannot be a space in the name)

zAttrValue - the value of the attribute

Throws:

Exception

setAttributeValue

public void setAttributeValue(Element zElement,
                              String zAttrName,
                              int zAttrValue)
                       throws Exception

to set (including creation) the value of an attribute for a given element

Parameters:

zElement - the element

zAttrName - the name of the attribute (please note that there cannot be a space in the name)

zAttrValue - the value of the attribute

Throws:

Exception

setAttributeValue

public void setAttributeValue(Element zElement,
                              String zAttrName,
                              long zAttrValue)
                       throws Exception

to set (including creation) the value of an attribute for a given element

Parameters:

zElement - the element

zAttrName - the name of the attribute (please note that there cannot be a space in the name)

zAttrValue - the value of the attribute

Throws:

Exception

setAttributeValue

public void setAttributeValue(Element zElement,
                              String zAttrName,
                              boolean zAttrValue)
                       throws Exception

to set (including creation) the value of an attribute for a given element

Parameters:

zElement - the element

zAttrName - the name of the attribute (please note that there cannot be a space in the name)

zAttrValue - the value of the attribute

Throws:

Exception

setAttributeValue

public void setAttributeValue(Element zElement,
                              String zAttrName,
                              float zAttrValue)
                       throws Exception

to set (including creation) the value of an attribute for a given element

Parameters:

zElement - the element

zAttrName - the name of the attribute (please note that there cannot be a space in the name)

zAttrValue - the value of the attribute

Throws:

Exception

setAttributeValue

public void setAttributeValue(Element zElement,
                              String zAttrName,
                              double zAttrValue)
                       throws Exception

to set (including creation) the value of an attribute for a given element

Parameters:

zElement - the element

zAttrName - the name of the attribute (please note that there cannot be a space in the name)

zAttrValue - the value of the attribute

Throws:

Exception

setElementValue

public void setElementValue(Document zDocument,
                            String zTagName,
                            String zElementValue)
                     throws Exception

To set the value of a given text element (i.e. the asumption is that the element is of the form: "zElementValue"). If there is more than one matching element, the value of the first matching element is set. If there is no matching element, the element is created.

Parameters:

zTagName - the tag name of the element

zElementValue - the value (can be empty but cannot be null)

Throws:

Exception

setElementValues

public void setElementValues(Document zDocument,
                             String zParentTagName,
                             String zChildTagName,
                             ArrayList<String> zElementValues)
                      throws Exception

To set the text values of a given element (i.e. the asumption is that the element is of the form: "zElementValue1 ...zElementValueN"). If there is more than one matching element, the value of the first matching element is set. If there is no matching element, the element is created.

Parameters:

zParentTagName - the tag name of the element

zChildTagName - the tag name of the child text element

zElementValues - the values

Throws:

Exception

setElementValue

public void setElementValue(Element zElement,
                            String zTagName,
                            String zElementValue)
                     throws Exception

To set the value of a given text element (i.e. the asumption is that the element is of the form: "zElementValue"). If there is more than one matching element, the value of the first matching element is set. If there is no matching element, the element is created.

Parameters:

zTagName - the tag name of the element

zElementValue - the value

Throws:

Exception

importDocument

public void importDocument(Document zDocument,
                           Element zParentElement,
                           Document zDocumentToImport)
                    throws Exception

import the given document as a child to the given parent element

Throws:

Exception - whenever an error occur

importElement

public void importElement(Element zParentElementFromDocument1,
                          Element zChildElementFromDocument2)
                   throws Exception

To import a DOM subtree from another document into a document. For instance:

//<?xml version="1.0" encoding="UTF-8"?>
//<root1>
//</root1>
Document doc1 = JbbDom.getInstance().createDocument();
Element root1 = JbbDom.getInstance().createElementRoot(doc1,"root1");

//<?xml version="1.0" encoding="UTF-8"?>
//<root2>
// <node2>hello2</node2>
//</root2>
Document doc2 = JbbDom.getInstance().createDocument();
Element root2 = JbbDom.getInstance().createElementRoot(doc2,"root2");
Element node2 = JbbDom.getInstance().createElement(root2,"node2","hello2");

// DESIRED RESULT:
//<?xml version="1.0" encoding="UTF-8"?>
//<root1>
// <node2>hello2</node2>
//<root1>
JbbDom.getInstance().importElement(root1,node2);

Parameters:

zParentElementFromDocument1 - an element in a document: this is the element in the document that will be extended with the imported subtree

zChildElementFromDocument2 - this is the element to import under the previous "zParentElementFromDocument1" element

Throws:

Exception

importElement

public void importElement(Document zDocument,
                          Element zParentElement,
                          Document zDocumentToImportFrom,
                          String zTag)
                   throws Exception

Parameters:

zDocument -

zParentElement -

zDocumentToImportFrom -

zTag -

Throws:

Exception

serialize

public String serialize(Element zElement)
                 throws Exception

serialize the given DOM subtree in a string

Parameters:

zElement - the element

Returns:

the serialized XML including the subtree

Throws:

Exception - whenever an error occur

serialize

public String serialize(Document zDoc)
                 throws Exception

serialize the given DOM subtree in a string

Parameters:

zElement - the element

Returns:

the serialized XML including the subtree

Throws:

Exception - whenever an error occur

serialize

public String serialize(Document doc,
                        String encoding)
                 throws Exception

serialize the given DOM document in a String with the given encoding

Parameters:

document - the document

encoding - encoding string e.g. "UTF-8", "UTF-16"...

Throws:

Exception - whenever an error occur

serializeToStream

public void serializeToStream(Document document,
                              OutputStream stream)
                       throws Exception

serialize the given DOM document in a stream with the default encoding

Parameters:

Documentt - the document

stream - the output stream to use

Throws:

Exception - whenever an error occur

serializeToStream

public void serializeToStream(Document document,
                              OutputStream stream,
                              String encoding)
                       throws Exception

serialize the given DOM document in a stream with given encoding

Parameters:

Documentt - the document

stream - the output stream to use

encoding - encoding string e.g. "UTF-8", "UTF-16"...

Throws:

Exception - whenever an error occur

serializeToStream

public void serializeToStream(Element zElement,
                              OutputStream zStream,
                              String encoding)
                       throws Exception

serialize the given DOM subtree in a stream with given encoding

Parameters:

zElement - the element

zStream - the output stream to use

encoding - encoding string e.g. "UTF-8", "UTF-16"...

Throws:

Exception - whenever an error occur

serialize

public String serialize(Element zElement,
                        String encoding)
                 throws Exception

serialize the given DOM subtree in a string with the given encoding

Parameters:

zElement - the element

encoding - encoding string

Returns:

the serialized XML including the subtree

Throws:

Exception - whenever an error occur

serializeToStream

public void serializeToStream(Element zElement,
                              OutputStream zStream)
                       throws Exception

serialize the given DOM subtree in a stream

Parameters:

zElement - the element

zStream - the output stream to use

Throws:

Exception - whenever an error occur

removeElement

public void removeElement(Element zElement)
                   throws Exception

remove the given element from its document

Parameters:

zElement - the element to remove

Throws:

Exception

areEqual

public boolean areEqual(Node node,
                        Node otherNode)

This tells you whether the two nodes are equal in characteristics. For example, if you create two empty element nodes named "foo" without any attributes, they are equal. Returns false if any of the arguments is null.

Parameters:

node -

otherNode -

Returns:

boolean value

areSame

public boolean areSame(Node node,
                       Node otherNode)

This tells you whether what you are looking at are proxies to the same object or objects that are actually different.Returns false if any of the arguments is null.

Parameters:

node -

otherNode -

Returns:

boolean value

comparePosition

public short comparePosition(Node node,
                             Node otherNode)

This method allows you to find out how two nodes are positioned with respect to each other in the document tree. Throws IllegalArgumentException if any of the arguments is null.

Parameters:

node -

otherNode -

Returns:

short

isDescendant

public boolean isDescendant(Node node,
                            Node otherNode)

will return true if otherNode is descendant node in the document.

Parameters:

node -

otherNode -

Returns:

boolean value

isAncestor

public boolean isAncestor(Node node,
                          Node otherNode)

will return true if otherNode is ancestor of node in the document.

Parameters:

node -

otherNode -

Returns:

boolean value

isFollowing

public boolean isFollowing(Node node,
                           Node otherNode)

will return true if otherNode is follows node in the document.

Parameters:

node -

otherNode -

Returns:

boolean value

isPreceding

public boolean isPreceding(Node node,
                           Node otherNode)

will return true if otherNode is precedes node in the document.

Parameters:

node -

otherNode -

Returns:

boolean value