org.springframework.shell.support.util
Class XmlUtils

java.lang.Object
  extended by org.springframework.shell.support.util.XmlUtils

public final class XmlUtils
extends Object

Utilities related to XML usage.

Since:
1.0

Method Summary
static void assertElementLegal(String element)
          Checks the presented element for illegal characters that could cause malformed XML.
static boolean compareNodes(Node node1, Node node2)
          Compares two DOM nodes by comparing the representations of the nodes as XML strings
static String convertId(String proposed)
          Converts a XHTML compliant id (used in jspx) to a CSS3 selector spec compliant id.
static Transformer createIndentingTransformer()
           
static Element createTextElement(Document document, String tagName, String text)
          Creates an Element containing the given text
static List<Element> findElements(String xPathExpression, Element root)
          Checks in under a given root element whether it can find a child elements which match the XPath expression supplied.
static Node findFirstAttribute(String xPathExpression, Element element)
          Checks for a given element whether it can find an attribute which matches the XPath expression supplied.
static Element findFirstElement(String xPathExpression, Node parent)
          Searches the given parent element for a child element matching the given XPath expression.
static Element findFirstElementByName(String name, Element root)
          Deprecated. use DomUtils.findFirstElementByName(String, Element) instead
static Node findNode(String xPathExpression, Node root)
          Checks in under a given root element whether it can find a child node which matches the XPath expression supplied.
static Element findRequiredElement(String xPathExpression, Element root)
          Checks in under a given root element whether it can find a child element which matches the XPath expression supplied.
static Element getConfiguration(Class<?> clazz)
          Returns the root element of an addon's configuration file.
static DocumentBuilder getDocumentBuilder()
           
static Element getRootElement(Class<?> clazz, String xmlFilePath)
          Returns the root element of the given XML file.
static String getTextContent(String path, Element parentElement)
           
static String getTextContent(String path, Element parentElement, String valueIfNull)
           
static String nodeToString(Node node)
          Converts a node to an XML string
static Document readXml(InputStream inputStream)
          Read an XML document from the supplied input stream and return a document.
static void removeTextNodes(Node node)
          Deprecated. use DomUtils.removeTextNodes(Node) instead
static Element stringToElement(String xml)
          Returns the given XML as the root Element of a new Document
static void writeFormattedXml(OutputStream outputStream, Document document)
          Write an XML document to the OutputStream provided.
static void writeXml(OutputStream outputStream, Document document)
          Write an XML document to the OutputStream provided.
static void writeXml(Transformer transformer, OutputStream outputStream, Document document)
          Write an XML document to the OutputStream provided.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

stringToElement

public static Element stringToElement(String xml)
Returns the given XML as the root Element of a new Document

Parameters:
xml - the XML to convert; can be blank
Returns:
null if the given XML is blank
Since:
1.2.0

createTextElement

public static Element createTextElement(Document document,
                                        String tagName,
                                        String text)
Creates an Element containing the given text

Parameters:
document - the document to contain the new element
tagName - the element's tag name (required)
text - the text to set; can be null for none
Returns:
a non-null element
Since:
1.2.0

readXml

public static Document readXml(InputStream inputStream)
Read an XML document from the supplied input stream and return a document.

Parameters:
inputStream - the input stream to read from (required). The stream is closed upon completion.
Returns:
a document.
Throws:
IllegalStateException - if the stream could not be read

writeXml

public static void writeXml(OutputStream outputStream,
                            Document document)
Write an XML document to the OutputStream provided. This will use the pre-configured Roo provided Transformer.

Parameters:
outputStream - the output stream to write to. The stream is closed upon completion.
document - the document to write.

writeXml

public static void writeXml(Transformer transformer,
                            OutputStream outputStream,
                            Document document)
Write an XML document to the OutputStream provided. This will use the provided Transformer.

Parameters:
transformer - the transformer (can be obtained from XmlUtils.createIndentingTransformer())
outputStream - the output stream to write to. The stream is closed upon completion.
document - the document to write.

writeFormattedXml

public static void writeFormattedXml(OutputStream outputStream,
                                     Document document)
Write an XML document to the OutputStream provided. This method will detect if the JDK supports the DOM Level 3 "format-pretty-print" configuration and make use of it. If not found it will fall back to using formatting offered by TrAX.

Parameters:
outputStream - the output stream to write to. The stream is closed upon completion.
document - the document to write.

compareNodes

public static boolean compareNodes(Node node1,
                                   Node node2)
Compares two DOM nodes by comparing the representations of the nodes as XML strings

Parameters:
node1 - the first node
node2 - the second node
Returns:
true if the XML representation node1 is the same as the XML representation of node2, otherwise false

nodeToString

public static String nodeToString(Node node)
Converts a node to an XML string

Parameters:
node - the first element
Returns:
the XML String representation of the node, never null

findFirstElement

public static Element findFirstElement(String xPathExpression,
                                       Node parent)
Searches the given parent element for a child element matching the given XPath expression. Please note that the XPath parser used is NOT namespace aware. So if you want to find an element <beans><sec:http>, you need to use the following XPath expression '/beans/http'.

Parameters:
xPathExpression - the xPathExpression (required)
parent - the parent DOM element (required)
Returns:
the Element if discovered (null if no such Element found)

findNode

public static Node findNode(String xPathExpression,
                            Node root)
Checks in under a given root element whether it can find a child node which matches the XPath expression supplied. Returns Node if exists. Please note that the XPath parser used is NOT namespace aware. So if you want to find a element <beans><sec:http>, you need to use the XPath expression '/beans/http'.

Parameters:
xPathExpression - the XPath expression (required)
root - the parent DOM element (required)
Returns:
the Node if discovered (null if not found)

findRequiredElement

public static Element findRequiredElement(String xPathExpression,
                                          Element root)
Checks in under a given root element whether it can find a child element which matches the XPath expression supplied. The Element must exist. Returns Element if exists. Please note that the XPath parser used is NOT namespace aware. So if you want to find a element you need to use the following XPath expression '/beans/http'.

Parameters:
xPathExpression - the XPath expression (required)
root - the parent DOM element (required)
Returns:
the Element if discovered (never null; an exception is thrown if cannot be found)

findElements

public static List<Element> findElements(String xPathExpression,
                                         Element root)
Checks in under a given root element whether it can find a child elements which match the XPath expression supplied. Returns a List of Element if they exist. Please note that the XPath parser used is NOT namespace aware. So if you want to find a element you need to use the following XPath expression '/beans/http'.

Parameters:
xPathExpression - the xPathExpression
root - the parent DOM element
Returns:
a List of type Element if discovered, otherwise an empty list (never null)

findFirstAttribute

public static Node findFirstAttribute(String xPathExpression,
                                      Element element)
Checks for a given element whether it can find an attribute which matches the XPath expression supplied. Returns Node if exists.

Parameters:
xPathExpression - the xPathExpression (required)
element - (required)
Returns:
the Node if discovered (null if not found)

createIndentingTransformer

public static Transformer createIndentingTransformer()
Returns:
a transformer that indents entries by 4 characters (never null)

getDocumentBuilder

public static DocumentBuilder getDocumentBuilder()
Returns:
a new document builder (never null)

getRootElement

public static Element getRootElement(Class<?> clazz,
                                     String xmlFilePath)
Returns the root element of the given XML file.

Parameters:
clazz - the class from whose package to open the file (required)
xmlFilePath - the path of the XML file relative to the given class' package (required)
Returns:
a non-null element
See Also:
Document.getDocumentElement()

getConfiguration

public static Element getConfiguration(Class<?> clazz)
Returns the root element of an addon's configuration file.

Parameters:
clazz - which owns the configuration
Returns:
the configuration root element

convertId

public static String convertId(String proposed)
Converts a XHTML compliant id (used in jspx) to a CSS3 selector spec compliant id. In that it will replace all '.,:,-' to '_'

Parameters:
proposed - Id
Returns:
cleaned up Id

assertElementLegal

public static void assertElementLegal(String element)
Checks the presented element for illegal characters that could cause malformed XML.

Parameters:
element - the content of the XML element
Throws:
IllegalArgumentException - if the element is null, has no text or contains illegal characters

getTextContent

public static String getTextContent(String path,
                                    Element parentElement)

getTextContent

public static String getTextContent(String path,
                                    Element parentElement,
                                    String valueIfNull)

findFirstElementByName

@Deprecated
public static Element findFirstElementByName(String name,
                                                        Element root)
Deprecated. use DomUtils.findFirstElementByName(String, Element) instead

Checks in under a given root element whether it can find a child element which matches the name supplied. Returns Element if exists.

Parameters:
name - the Element name (required)
root - the parent DOM element (required)
Returns:
the Element if discovered

removeTextNodes

@Deprecated
public static void removeTextNodes(Node node)
Deprecated. use DomUtils.removeTextNodes(Node) instead

Removes empty text nodes from the specified node

Parameters:
node - the element where empty text nodes will be removed