net.sf.mmm.util.xml.api
Interface DomUtil

All Known Implementing Classes:

DomUtilImpl

@ComponentSpecification
public interface DomUtil

This is the interface for a collection of utility functions that help to deal with the DOM API.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Document	createDocument() This method creates a new empty XML DOM document.
boolean	getAttributeAsBoolean(Element element, String attribute, boolean defaultValue) This method gets the value of the attribute from the given element as a boolean value.
Element	getFirstChildElement(Element element, String tagName) This method gets the first child-element of the given element with the specified tagName.
Element	getFirstElement(NodeList nodeList) This method gets the first element of the given node-list.
Element	getFirstElement(NodeList nodeList, String tagName) This method gets the first element of the given node-list with the specified tag-name.
String	getLocalName(Node node) This method gets the local name of a given element.
String	getNodeText(Node node) This method gets the text of the given node excluding the text of child elements (depth=0).
void	getNodeText(Node node, Appendable buffer, int depth) This method appends the text of the given node to the string buffer.
String	getNodeText(Node node, int depth) This method gets the text of the given node as string.
boolean	isEqual(Node node1, Node node2, XmlCompareMode mode) This method determines if two XML-nodes represent the same XML.
Document	parseDocument(InputSource inputSource) This method parses an XML document into an DOM document.
Document	parseDocument(InputStream inputStream) This method parses an XML document from a given input stream.
Document	parseDocument(Reader reader) This method parses an XML document from a given reader.
void	removeChildren(Element node) This method removes all child nodes of the given node.
Element	requireFirstChildElement(Element element, String tagName) This method requires the first child-element of the given element with the specified tagName.
void	transformXml(Source source, Result result, boolean indent) This method transforms the given XML source to the given result without structural modifications.
void	writeXml(Node xmlNode, OutputStream outputStream, boolean indent) This method writes the XML DOM tree given as node to the given output stream.
void	writeXml(Node xmlNode, Writer writer, boolean indent) This method writes the XML DOM tree given as node to the given writer.

Method Detail

createDocument

Document createDocument()

This method creates a new empty XML DOM document.

Returns:

the new document.

parseDocument

Document parseDocument(InputStream inputStream)
                       throws XmlException,
                              IOException

This method parses an XML document from a given input stream.

Parameters:

inputStream - is the input stream to the XML data. If will be closed at the end of this method (on success as well as in an exceptional state).

Returns:

the parsed XML DOM document.

Throws:

XmlException - if the XML is invalid and could NOT be parsed.

IOException - if the input stream produced an error while reading.

parseDocument

Document parseDocument(Reader reader)
                       throws XmlException

This method parses an XML document from a given reader.

Parameters:

reader - is the reader to the XML data.

Returns:

the parsed XML DOM document.

Throws:

XmlException - if the input stream produced an IOException or the XML is invalid.

parseDocument

Document parseDocument(InputSource inputSource)
                       throws XmlException

This method parses an XML document into an DOM document.

Parameters:

inputSource - is the input source to the XML data.

Returns:

the parsed XML DOM document.

Throws:

XmlException - if the XML is invalid.

writeXml

void writeXml(Node xmlNode,
              OutputStream outputStream,
              boolean indent)
              throws XmlException

This method writes the XML DOM tree given as node to the given output stream.

Parameters:

xmlNode - is the "root" node of the XML tree to write (e.g. the Document or just a single Element).

outputStream - is where the serialized XML is written to.

indent - - true if the XML should be indented (automatically add line-breaks before opening tags), false otherwise.

Throws:

XmlException - if XML is inconsistent.

writeXml

void writeXml(Node xmlNode,
              Writer writer,
              boolean indent)
              throws XmlException

This method writes the XML DOM tree given as node to the given writer.

Parameters:

xmlNode - is the "root" node of the XML tree to write (e.g. the Document or just a single Element).

writer - is where the serialized XML is written to.

indent - - true if the XML should be indented (automatically add line-breaks before opening tags), false otherwise.

Throws:

XmlException - if XML is inconsistent.

transformXml

void transformXml(Source source,
                  Result result,
                  boolean indent)
                  throws XmlException

This method transforms the given XML source to the given result without structural modifications.

Parameters:

source - is a source (e.g. DomSource, etc.)

result - is a result (e.g. DomResult, StreamResult, etc.)

indent - - true if the XML should be indented (automatically add line-breaks before opening tags), false otherwise.

Throws:

XmlException - if the transformation failed (e.g. invalid XML).

getLocalName

String getLocalName(Node node)

This method gets the local name of a given element. This is the name of the element without any namespace prefix.
The method Node.getLocalName() will return null if the Node has no namespace. Therefore this method makes your life a little easier.

Parameters:

node - the Node to get the local name from.

Returns:

the local name of the given element.

isEqual

boolean isEqual(Node node1,
                Node node2,
                XmlCompareMode mode)

This method determines if two XML-nodes represent the same XML. This is quite a complex operation since the two given nodes may have different segmentations of the text they contain and one might use Text while the other may use a CDATASection.

Parameters:

node1 - is the first Node to compare.

node2 - is the second Node to compare.

mode - is the mode that determines how to do the comparison.

Returns:

true if the XML fragment represented by the given nodes equals, false otherwise.

getFirstElement

Element getFirstElement(NodeList nodeList)

This method gets the first element of the given node-list.

Parameters:

nodeList - is the node-list (potentially) containing the requested element.

Returns:

the first element in the node-list or null, if the node-list contains NO element.

See Also:

getFirstElement(NodeList, String)

getFirstElement

Element getFirstElement(NodeList nodeList,
                        String tagName)

This method gets the first element of the given node-list with the specified tag-name.

Parameters:

nodeList - is the node-list (potentially) containing the requested element.

tagName - is the tag-name of the requested element or null if any element is acceptable.

Returns:

the first element in the node-list with the given tag-name (or at all if tag-name is null). If no such element exists in the node-list, null is returned.

getFirstChildElement

Element getFirstChildElement(Element element,
                             String tagName)

This method gets the first child-element of the given element with the specified tagName.

Parameters:

element - is the element (potentially) containing the requested child-element.

tagName - is the tag-name of the requested element or null if any element is acceptable.

Returns:

the first element in the node-list with the given tag-name (or at all if tag-name is null). If no such element exists in the node-list, null is returned.

getAttributeAsBoolean

boolean getAttributeAsBoolean(Element element,
                              String attribute,
                              boolean defaultValue)
                              throws IllegalArgumentException

This method gets the value of the attribute from the given element as a boolean value.

Parameters:

element - is the element potentially containing the requested boolean attribute.

attribute - is the name of the requested attribute.

defaultValue - is the default returned if the attribute is NOT present.

Returns:

the value of the specified attribute or the defaultValue if the attribute is NOT present.

Throws:

IllegalArgumentException - if the value of the specified attribute does NOT represent a boolean value.

getNodeText

String getNodeText(Node node)

This method gets the text of the given node excluding the text of child elements (depth=0).

Parameters:

node - is the xml node containing the text.

Returns:

the text of the node.

See Also:

getNodeText(Node, Appendable, int)

getNodeText

String getNodeText(Node node,
                   int depth)

This method gets the text of the given node as string.

Parameters:

node - is the xml node containing the text.

depth - specifies how deep to step into child elements. If less than 1, the text of child elements is ignored.

Returns:

the text of the node including child nodes down to the specified depth.

See Also:

getNodeText(Node, Appendable, int)

getNodeText

void getNodeText(Node node,
                 Appendable buffer,
                 int depth)

This method appends the text of the given node to the string buffer. Text means the plain characters between the opening and the closing tag of the element including the text of CDATA sections. The text of child elements is only appended according to the given depth. If the depth is less than 1, child elements are ignored, if equal to 1, the text of child elements is included without their child elements. For an infinite depth use Integer.MAX_VALUE. E.g. for the a element a in

 <a>123<b/>4<c>5<d>6</d></c><![CDATA[7]]>8</a>
 

the call of getNodeText(a, buffer, depth) will append the following text to the buffer according to the given depth.

0. "123478"
1. "1234578"
2. "12345678"

Parameters:

node - is the xml node containing the text.

buffer - is the where to append the text to.

depth - specifies how deep to step into child elements. If less than 1, the text of child elements is ignored.

requireFirstChildElement

Element requireFirstChildElement(Element element,
                                 String tagName)
                                 throws IllegalArgumentException

This method requires the first child-element of the given element with the specified tagName.

Parameters:

element - is the element (potentially) containing the requested child-element.

tagName - is the tag-name of the requested element or null if any element is acceptable.

Returns:

the first element in the node-list with the given tag-name (or at all if tag-name is null).

Throws:

IllegalArgumentException - if the requested child element does NOT exist.

removeChildren

void removeChildren(Element node)

This method removes all child nodes of the given node.

Parameters:

node - is the node to clean of children.