net.sf.mmm.util.xml.base
Class DomUtilImpl

java.lang.Object
  net.sf.mmm.util.component.base.AbstractComponent
      net.sf.mmm.util.component.base.AbstractLoggableComponent
          net.sf.mmm.util.xml.base.DomUtilImpl

All Implemented Interfaces:

DomUtil

@Singleton
@Named
public final class DomUtilImpl
extends AbstractLoggableComponent
implements DomUtil

This utility class contains methods that help to deal with the DOM API.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

private BasicUtil	basicUtil
private DocumentBuilderFactory	documentBuilderFactory the document builder factory used to read and parse XML
private static DomUtil	instance
private TransformerFactory	transformerFactory the transformer factory used to transform or write XML

Constructor Summary

DomUtilImpl()
The constructor.

Method Summary

Document	createDocument() This method creates a new empty XML DOM document.
private DocumentBuilder	createDocumentBuilder() This method creates a new document builder.
private Transformer	createTransformer(boolean indent) This method creates a new transformer.
protected void	doInitialize() This method performs the actual initialization.
boolean	getAttributeAsBoolean(Element element, String attribute, boolean defaultValue) This method gets the value of the attribute from the given element as a boolean value.
protected BasicUtil	getBasicUtil() This method gets the BasicUtil.
protected DocumentBuilderFactory	getDocumentBuilderFactory() This method gets the DocumentBuilderFactory.
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.
static DomUtil	getInstance() This method gets the singleton instance of this DomUtilImpl.
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.
protected TransformerFactory	getTransformerFactory() This method gets the TransformerFactory.
protected boolean	isEqual(CharIterator charIterator1, CharIterator charIterator2, XmlCompareMode mode) This method determines if the given CharSequences are equal.
protected boolean	isEqual(Element element1, Element element2, XmlCompareMode mode) This method determines if the given elements are equal.
protected boolean	isEqual(NodeList nodeList1, NodeList nodeList2, XmlCompareMode mode) This method determines if the given NodeLists are equal.
boolean	isEqual(Node node1, Node node2, XmlCompareMode mode) This method determines if two XML-nodes represent the same XML.
private boolean	isEqualName(Node node1, Node node2) This method determines if the given nodes have the same name and namespace.
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	setBasicUtil(BasicUtil basicUtil) This method sets the BasicUtil.
void	setDocumentBuilderFactory(DocumentBuilderFactory documentBuilderFactory) This method sets the documentBuilderFactory.
void	setTransformerFactory(TransformerFactory transformerFactory) This method sets the transformerFactory.
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.

Methods inherited from class net.sf.mmm.util.component.base.AbstractLoggableComponent

getLogger, setLogger

Methods inherited from class net.sf.mmm.util.component.base.AbstractComponent

doInitialized, getInitializationState, initialize

Methods inherited from class java.lang.Object

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

Field Detail

instance

private static DomUtil instance

See Also:

getInstance()

documentBuilderFactory

private DocumentBuilderFactory documentBuilderFactory

the document builder factory used to read and parse XML

transformerFactory

private TransformerFactory transformerFactory

the transformer factory used to transform or write XML

basicUtil

private BasicUtil basicUtil

See Also:

getBasicUtil()

Constructor Detail

DomUtilImpl

public DomUtilImpl()

The constructor.

Method Detail

getDocumentBuilderFactory

protected DocumentBuilderFactory getDocumentBuilderFactory()

This method gets the DocumentBuilderFactory.

Returns:

the DocumentBuilderFactory to use.

setDocumentBuilderFactory

public void setDocumentBuilderFactory(DocumentBuilderFactory documentBuilderFactory)

This method sets the documentBuilderFactory.

Parameters:

documentBuilderFactory - is the documentBuilderFactory to set.

getTransformerFactory

protected TransformerFactory getTransformerFactory()

This method gets the TransformerFactory.

Returns:

the TransformerFactory to use.

setTransformerFactory

public void setTransformerFactory(TransformerFactory transformerFactory)

This method sets the transformerFactory.

Parameters:

transformerFactory - is the transformerFactory to set

getBasicUtil

protected BasicUtil getBasicUtil()

This method gets the BasicUtil.

Returns:

the BasicUtil to use.

setBasicUtil

@Inject
public void setBasicUtil(BasicUtil basicUtil)

This method sets the BasicUtil.

Parameters:

basicUtil - is the BasicUtil to set

getInstance

public static DomUtil getInstance()

This method gets the singleton instance of this DomUtilImpl.
This design is the best compromise between easy access (via this indirection you have direct, static access to all offered functionality) and IoC-style design which allows extension and customization.
For IoC usage, simply ignore all static getInstance() methods and construct new instances via the container-framework of your choice (like plexus, pico, springframework, etc.). To wire up the dependent components everything is properly annotated using common-annotations (JSR-250). If your container does NOT support this, you should consider using a better one.

Returns:

the singleton instance.

doInitialize

protected void doInitialize()

This method performs the actual initialization. It is called when AbstractComponent.initialize() is invoked for the first time.
ATTENTION:
When you override this method from a sub-class you need to do a super.AbstractComponent.doInitialize().

Overrides:

doInitialize in class AbstractLoggableComponent

createDocumentBuilder

private DocumentBuilder createDocumentBuilder()

This method creates a new document builder.

Returns:

the new document builder instance.

createTransformer

private Transformer createTransformer(boolean indent)

This method creates a new transformer.

Parameters:

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

Returns:

the new transformer.

getFirstElement

public Element getFirstElement(NodeList nodeList)

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

Specified by:

getFirstElement in interface DomUtil

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:

DomUtil.getFirstElement(NodeList, String)

getFirstElement

public Element getFirstElement(NodeList nodeList,
                               String tagName)

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

Specified by:

getFirstElement in interface DomUtil

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

public Element getFirstChildElement(Element element,
                                    String tagName)

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

Specified by:

getFirstChildElement in interface DomUtil

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.

requireFirstChildElement

public Element requireFirstChildElement(Element element,
                                        String tagName)
                                 throws IllegalArgumentException

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

Specified by:

requireFirstChildElement in interface DomUtil

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.

getAttributeAsBoolean

public 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.

Specified by:

getAttributeAsBoolean in interface DomUtil

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

public String getNodeText(Node node)

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

Specified by:

getNodeText in interface DomUtil

Parameters:

node - is the xml node containing the text.

Returns:

the text of the node.

See Also:

DomUtil.getNodeText(Node, Appendable, int)

getNodeText

public String getNodeText(Node node,
                          int depth)

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

Specified by:

getNodeText in interface DomUtil

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:

DomUtil.getNodeText(Node, Appendable, int)

getNodeText

public 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"

Specified by:

getNodeText in interface DomUtil

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.

removeChildren

public void removeChildren(Element node)

This method removes all child nodes of the given node.

Specified by:

removeChildren in interface DomUtil

Parameters:

node - is the node to clean of children.

createDocument

public Document createDocument()

This method creates a new empty XML DOM document.

Specified by:

createDocument in interface DomUtil

Returns:

the new document.

parseDocument

public Document parseDocument(InputStream inputStream)
                       throws XmlException,
                              IOException

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

Specified by:

parseDocument in interface DomUtil

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

public Document parseDocument(Reader reader)
                       throws XmlException

This method parses an XML document from a given reader.

Specified by:

parseDocument in interface DomUtil

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

public Document parseDocument(InputSource inputSource)
                       throws XmlException

This method parses an XML document into an DOM document.

Specified by:

parseDocument in interface DomUtil

Parameters:

inputSource - is the input source to the XML data.

Returns:

the parsed XML DOM document.

Throws:

XmlException - if the XML is invalid.

writeXml

public 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.

Specified by:

writeXml in interface DomUtil

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

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

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

Specified by:

writeXml in interface DomUtil

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

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

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

Specified by:

transformXml in interface DomUtil

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

public 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.

Specified by:

getLocalName in interface DomUtil

Parameters:

node - the Node to get the local name from.

Returns:

the local name of the given element.

isEqualName

private boolean isEqualName(Node node1,
                            Node node2)

This method determines if the given nodes have the same name and namespace.

Parameters:

node1 - is the first node.

node2 - is the second node.

Returns:

true if both nodes have equal name and namespace.

isEqual

public 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.

Specified by:

isEqual in interface DomUtil

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.

isEqual

protected boolean isEqual(CharIterator charIterator1,
                          CharIterator charIterator2,
                          XmlCompareMode mode)

This method determines if the given CharSequences are equal.

Parameters:

charIterator1 - is the first CharIterator.

charIterator2 - is the second CharIterator.

mode - is the mode of comparison.

Returns:

true if equal, false otherwise.

See Also:

isEqual(Node, Node, XmlCompareMode)

isEqual

protected boolean isEqual(Element element1,
                          Element element2,
                          XmlCompareMode mode)

This method determines if the given elements are equal.

Parameters:

element1 - is the first Element.

element2 - is the second Element.

mode - is the mode of comparison.

Returns:

true if equal, false otherwise.

See Also:

isEqual(Node, Node, XmlCompareMode)

isEqual

protected boolean isEqual(NodeList nodeList1,
                          NodeList nodeList2,
                          XmlCompareMode mode)

This method determines if the given NodeLists are equal.

Parameters:

nodeList1 - is the first NodeList.

nodeList2 - is the second NodeList.

mode - is the mode of comparison.

Returns:

true if equal, false otherwise.