XMLUtils

Class FQN: it.greenvulcano.util.xml.XMLUtils

The methods described can be used in OGNL expressions. For example the parsing for an input of type String, you can use the expression:

1. doc = @it.greenvulcano.util.xml.XMLUtils@parseDOM(input)

To extract a value from a document through an xpath expression:

1. value = @it.greenvulcano.util.xml.XMLUtils@get_S(#doc)

Following the Class public static methods

• Parsing

/**
* Returns a DOM parsed from the given XML string.
*
* @param xmlString
*        A String containing an XML document
* @param isValidating
* @param isNamespaceAware
* @return The corresponding DOM
* @throws XMLUtilsException
*         when errors occur
*/
public static Document parseDOM_S(String xmlString) throws XMLUtilsException

/**
* Returns a DOM parsed from the given XML string.
*
* @param xmlString
*        A String containing an XML document
* @param isValidating
* @param isNamespaceAware
* @return The corresponding DOM
* @throws XMLUtilsException
*         when errors occur
*/
public static Document parseDOM_S(String xmlString, boolean isValidating, boolean isNamespaceAware) throws XMLUtilsException

/**
* Returns a DOM parsed from the given XML input stream.
*
* @param xmlStream
*        input document
* @param isValidating
*        if true try to validating the XML
* @param isNamespaceAware
*        if true ability to resolver namespace
* @return a DOM parsed from the given XML input stream.
* @throws XMLUtilsException
*/
public static Document parseDOM_S(InputStream xmlStream, boolean isValidating, boolean isNamespaceAware) throws XMLUtilsException

/**
* Returns a DOM parsed from the given byte array.
*
* @param xml
*        A byte array containing an XML document
* @param isValidating
* @param isNamespaceAware
* @return The corresponding DOM
* @throws XMLUtilsException
*         when errors occur
*/
public static Document parseDOM_S(byte[] xml, boolean isValidating, boolean isNamespaceAware) throws XMLUtilsException

/**
* Returns a DOM parsed from the given input object.
*
* @param object
*        input object (Document, Node, String serialized XML, byte[] serialized XML, InputStream)
* @param isValidating
*        if true try to validating the XML
* @param isNamespaceAware
*        if true ability to resolver namespace
* @return a DOM parsed from the given input object.
* @throws XMLUtilsException
*/
public static Document parseObject_S(Object input, boolean isValidating, boolean isNamespaceAware) throws XMLUtilsException

/**
* Parses the DOM document and validates it.
*
* @param type
* @param docStream
*        the XML document do parse
* @param gvEntityResolver
* @param gvErrorHandler
* @return the document parsed
*
* @throws XMLUtilsException
*/
public static Document parseDOMValidating(String type, InputStream docStream, EntityResolver gvEntityResolver, ErrorHandler gvErrorHandler) throws XMLUtilsException

• Serialization

/**
* Serialize a given DOM to an XML string, using default character encoding
* UTF-8, use as default omit_xml_decl property false, use as default indent
* property false.
*
* @param doc
*        The input DOM
* @return the serialized document (as a String encoded using
*         default character encoding UTF-8)
* @throws XMLUtilsException
*         on errors
*/
public static String serializeDOM_S(Node doc) throws XMLUtilsException

/**
* Serialize a given DOM to an XML string, using a specified character
* encoding for the output XML string. If the specified encoding is not
* supported or is null, defaults on UTF-8. Use as default omit_xml_decl
* property false, use as default indent property falseIt.
*
* @param doc
*        The input DOM
* @param encoding
*        The desiderd character encoding for the output XML string
* @return the serialized document (as a String encoded using the
*         specified character encoding)
* @throws XMLUtilsException
*         on errors
*/
public static String serializeDOM_S(Node doc, String encoding) throws XMLUtilsException

/**
* Serialize a given DOM to a byte array containing an XML string, using
* default character encoding UTF-8.
*
* @param doc
*        The input DOM
* @return the serialized document (as a byte array)
* @throws XMLUtilsException
*         on errors
*/
public static byte[] serializeDOMToByteArray_S(Node doc) throws XMLUtilsException

/**
* Serialize a given DOM to a byte array containing an XML string, using a
* specified character encoding for the output XML buffer. If the specified
* encoding is not supported or is null, defaults on UTF-8.
*
* @param doc
*        The input DOM
* @param encoding
*        The desired character encoding for the output XML buffer
* @return the serialized document (as a byte array)
* @throws XMLUtilsException
*         on errors
*/
public static byte[] serializeDOMToByteArray_S(Document doc, String encoding) throws XMLUtilsException

• XPath

/**
* Gets the node matching the XPath on the given node.
*
* @param theNode
*        The input DOM node.
* @param xPath
*        The XPath to evaluate.
* @return the node matching the XPath on the given node.
* @throws XMLUtilsException
*         when errors occurs.
*/
public static Node selectSingleNode_S(Node theNode, String xPath) throws XMLUtilsException

/**
* Gets the node matching the XPath on the given xml.
*
* @param xmlString
*        The input XML as string.
* @param xPath
*        The XPath to evaluate.
* @return the node matching the XPath on the given node.
* @throws XMLUtilsException
*         when errors occurs.
*/
public static Node selectSingleNode_S(String xmlString, String xPath) throws XMLUtilsException

/**
* Gets the list of nodes matching the XPath on the given node.
*
* @param theNode
*        The input DOM node.
* @param xPath
*        The XPath to evaluate.
* @return the list of nodes matching the XPath on the given node.
* @throws XMLUtilsException
*         when errors occurs.
*/
public static NodeList selectNodeList_S(Node theNode, String xPath) throws XMLUtilsException

/**
* Static helper method the get the string representation of the node
* content selected from XPath.
*
* @param theNode
*        The input DOM node.
* @param xPath
*        The XPath to evaluate.
* @param defaultValue
*        The value returned if XPath does not select any node.
* @return the string representation of the node content selected from
*         XPath.
* @throws XMLUtilsException
*         when errors occurs.
*
* @see #get(Node, String, String)
*/
public static String get_S(Node theNode, String xPath, String defaultValue) throws XMLUtilsException

/**
* Static helper method the get the string representation of the node
* content selected from XPath.
*
* @param theNode
*        The input DOM node.
* @param xPath
*        The XPath to evaluate.
* @return the string representation of the node content selected from
*         XPath.
* @throws XMLUtilsException
*         when errors occurs.
*
* @see #get(Node, String)
*/
public static String get_S(Node theNode, String xPath) throws XMLUtilsException

• Utility

/**
* Replaces XML invalid chars within input String with the
* corresponding entities.
*
* @param input
*        the input String.
* @return the input string, with XML invalid chars replaced by the
*         corresponding entities.
*/
public static String replaceXMLInvalidChars(String input)

/**
* Replaces XML entities within input String with the corresponding
* invalid characters.
*
* @param input
*        the input String.
* @return the input string, with XML entities replaced by the corresponding
*         invalid chars.
*/
public static String replaceXMLEntities(String input)

/**
* Sets a user-defined EntityResolver for the validating parser.
*
* @param er
*        an object implementing the EntityResolverinterface
*/
public static void setDefaultEntityResolver(EntityResolver er)

Following the Class public instance methods

• Gettin&Using instance

XMLUtils parser = null;
try {
    parser = XMLUtils.getParserInstance();
    .....
    parser.someMethod(someParam);
    .....
}
finally {
    XMLUtils.releaseParserInstance(parser);
}

/**
* Gets an instance of XMLUtilsfrom the private stack. If an
* instance is not available, a new instance will be created.
*
* @return the XMLUtils parser instance
* @throws XMLUtilsException
*/
public static synchronized XMLUtils getParserInstance() throws XMLUtilsException

/**
* Release an instance of XMLUtils</tt>.
*
* @param theInstance
*/
public static synchronized void releaseParserInstance(XMLUtils theInstance)

• Parsing

/**
* Returns a DOM parsed from the given XML string.
*
* @param xmlString
*        A String containing an XML document
* @return The corresponding DOM
* @throws XMLUtilsException
*         when errors occur
*/
public Document parseDOM(String xmlString) throws XMLUtilsException

/**
* Returns a DOM parsed from the given byte[].
*
* @param xml
*        A byte[] containing an XML document
* @return The corresponding DOM
* @throws XMLUtilsException
*         when errors occur
*/
public Document parseDOM(byte[] xml) throws XMLUtilsException

/**
* Returns a DOM parsed from the given XML input stream.
*
* @param xmlStream
*        An InputStream containing an XML document
* @return The corresponding DOM
* @throws XMLUtilsException
*/
public Document parseDOM(InputStream xmlStream) throws XMLUtilsException

/**
* Returns a DOM parsed from the given XML string.
*
* @param xmlString
*        A String containing an XML document
* @param isValidating
* @param isNamespaceAware
* @return The corresponding DOM
* @throws XMLUtilsException
*         when errors occur
*/
public Document parseDOM(String xmlString, boolean isValidating, boolean isNamespaceAware) throws XMLUtilsException

/**
* Returns a DOM parsed from the given XML string.
*
* @param xml
*        A byte array containing an XML document
* @param isValidating
* @param isNamespaceAware
* @return The corresponding DOM
* @throws XMLUtilsException
*         when errors occur
*/
public Document parseDOM(byte[] xml, boolean isValidating, boolean isNamespaceAware) throws XMLUtilsException

/**
* Returns a DOM parsed from the given XML input stream.
*
* @param xmlStream
*        input document
* @param isValidating
*        if true try to validating the XML
* @param isNamespaceAware
*        if true ability to resolver namespace
* @return a DOM parsed from the given XML input stream.
* @throws XMLUtilsException
*/
public Document parseDOM(InputStream xmlStream, boolean isValidating, boolean isNamespaceAware) throws XMLUtilsException

/**
* Returns a DOM parsed from the given input object.
*
* @param object
*        input object (Document, Node, String serialized XML, byte[] serialized XML, InputStream)
* @param isValidating
*        if true try to validating the XML
* @param isNamespaceAware
*        if true ability to resolver namespace
* @return a DOM parsed from the given input object.
* @throws XMLUtilsException
*/
public Document parseObject(Object input, boolean isValidating, boolean isNamespaceAware) throws XMLUtilsException

/**
* Returns a DOM parsed from the given XML string. Note: This method
* validates the document by using as DTD the document path specified within
* the SYSTEM directive of the XML document.
*
* @param xmlString
*        A String containing an XML document
* @return The corresponding DOM
* @throws XMLUtilsException
*         when errors occur
*/
public Document parseDOMValidating(String xmlString) throws XMLUtilsException

/**
* Returns a DOM parsed from the given XML input stream.
*
* @param xmlStream
*        An InputStream containing an XML document
* @return The corresponding DOM
* @throws XMLUtilsException
*/
public Document parseDOMValidating(InputStream xmlStream) throws XMLUtilsException

• Serialization

/**
* Serialize a given DOM to an XML string, using default character encoding
* UTF-8, as default omit_xml_decl property false, as default indent
* property false. It uses JAXP XSL APIs.
*
* @param doc
*        The input DOM
* @return the serialized document (as a Stringencoded using
*         default character encoding UTF-8)
* @throws XMLUtilsException
*         on errors
*/
public String serializeDOM(Node doc) throws XMLUtilsException

/**
* Serialize a given DOM to an XML string, using default character encoding
* UTF-8.
*
* @param doc
*        The input DOM
* @return the serialized document (as a Stringencoded using
*         default character encoding UTF-8)
* @throws XMLUtilsException
*         on errors
*/
public String serializeDOM(Document doc) throws XMLUtilsException

/**
* Serialize a given DOM to an XML string, using a specified character
* encoding for the output XML string. If the specified encoding is not
* supported or is null, defaults on UTF-8. Use as default omit_xml_decl
* property false, as default indent property falseIt.
*
* @param doc
*        The input DOM
* @param encoding
*        The desiderd character encoding for the output XML string
* @return the serialized document (as a Stringencoded using the
*         specified character encoding)
* @throws XMLUtilsException
*         on errors
*/
public String serializeDOM(Node doc, String encoding) throws XMLUtilsException

/**
* Serialize a given DOM to an XML string, using a specified character
* encoding for the output XML string. If the specified encoding is not
* supported or is null, defaults on UTF-8.
*
* @param doc
*        The input DOM
* @param encoding
*        The desired character encoding for the output XML string
* @return the serialized document (as a Stringencoded using the
*         specified character encoding)
* @throws XMLUtilsException
*         on errors
*/
public String serializeDOM(Document doc, String encoding) throws XMLUtilsException

/**
* Serialize a given DOM to an XML string, using default character encoding
* UTF-8.
*
* @param doc
*        The input DOM
* @param omit_xml_decl
* @param indent
* @return the serialized document (as a Stringencoded using
*         default character encoding UTF-8)
* @throws XMLUtilsException
*         on errors
*/
public String serializeDOM(Node doc, boolean omit_xml_decl, boolean indent) throws XMLUtilsException

/**
* Serialize a given DOM to an XML string, using a specified character
* encoding for the output XML string. If the specified encoding is not
* supported or is null, defaults on UTF-8.
*
* @param doc
*        The input DOM
* @param encoding
*        The desired character encoding for the output XML string
* @param omit_xml_decl
* @param indent
* @return the serialized document (as a Stringencoded using the
*         specified character encoding)
* @throws XMLUtilsException
*         on errors
*/
public String serializeDOM(Node doc, String encoding, boolean omit_xml_decl, boolean indent) throws XMLUtilsException

/**
* Serialize a given DOM to a byte array containing an XML string, using
* default character encoding UTF-8.
*
* @param doc
*        The input DOM
* @return the serialized document (as a bytearray)
* @throws XMLUtilsException
*         on errors
*/
public byte[] serializeDOMToByteArray(Node doc) throws XMLUtilsException

/**
* Serialize a given DOM to a byte array containing an XML string, using
* default character encoding UTF-8.
*
* @param doc
*        The input DOM
* @param omit_xml_decl
* @param indent
* @return the serialized document (as a bytearray)
* @throws XMLUtilsException
*         on errors
*/
public byte[] serializeDOMToByteArray(Node doc, boolean omit_xml_decl, boolean indent) throws XMLUtilsException

/**
* Serialize a given DOM to a byte array containing an XML string, using a
* specified character encoding for the output XML buffer. If the specified
* encoding is not supported or is null, defaults on UTF-8.
* Not Use omit_xml_decl property and indent property
*
* @param doc
*        The input DOM
* @param encoding
*        The desiderd character encoding for the output XML buffer
* @return the serialized document (as a bytearray)
* @throws XMLUtilsException
*         on errors
*/
public byte[] serializeDOMToByteArray(Node doc, String encoding) throws XMLUtilsException

/**
* Serialize a given DOM to a byte array containing an XML string, using a
* specified character encoding for the output XML buffer. If the specified
* encoding is not supported or is null, defaults on UTF-8. 
*
* @param doc
*        The input DOM
* @param encoding
*        The desired character encoding for the output XML buffer
* @return the serialized document (as a bytearray)
* @throws XMLUtilsException
*         on errors
*/
public byte[] serializeDOMToByteArray(Document doc, String encoding) throws XMLUtilsException

/**
* Serialize a given DOM to a byte array containing an XML string, using a
* specified character encoding for the output XML buffer. If the specified
* encoding is not supported or is null, defaults on UTF-8.
*
* @param doc
*        The input DOM
* @param encoding
*        The desired character encoding for the output XML buffer
* @param omit_xml_decl
* @param indent
* @return the serialized document (as a bytearray)
* @throws XMLUtilsException
*         on errors
*/
public byte[] serializeDOMToByteArray(Node doc, String encoding, boolean omit_xml_decl, boolean indent) throws XMLUtilsException

• XPath

/**
* Gets the content of the given node. If the node has complex content (e.g
* it is an Element node or a Document node), its serialization to XML
* string is returned.
*
* @param theNode
*        The input DOM node.
* @return its content as a string (as an XML string in case of complex
*         content).
* @throws XMLUtilsException
*         when errors occur
*/
public String getNodeContent(Node theNode) throws XMLUtilsException

/**
* Detects if there's at least one node matching the XPath on the given
* node.
*
* @param theNode
*        The input DOM node.
* @param xPath
*        The XPath to evaluate.
* @return <code>true</code> if at least one node matching the XPath on the
*         given node is found, <code>false</code> otherwise.
* @throws XMLUtilsException
*         when errors occurs.
*/
public boolean existNode(Node theNode, String xPath) throws XMLUtilsException

/**
* Gets the node matching the XPath on the given node.
*
* @param theNode
*        The input DOM node.
* @param xPath
*        The XPath to evaluate.
* @return the node matching the XPath on the given node.
* @throws XMLUtilsException
*         when errors occurs.
*/
public Node selectSingleNode(Node theNode, String xPath) throws XMLUtilsException

/**
* Gets the list of nodes matching the XPath on the given node.
*
* @param theNode
*        The input DOM node.
* @param xPath
*        The XPath to evaluate.
* @return the list of nodes matching the XPath on the given node.
* @throws XMLUtilsException
*         when errors occurs.
*/
public NodeList selectNodeList(Node theNode, String xPath) throws XMLUtilsException

/**
* @param theNode
* @param xPath
* @return the iterator to the list of nodes matching the XPath on the given
*         node.
* @throws XMLUtilsException
*/
public NodeIterator selectNodeIterator(Node theNode, String xPath) throws XMLUtilsException

/**
* Gets the string representation of the node content selected from XPath.
*
* @param theNode
*        The input DOM node.
* @param xPath
*        The XPath to evaluate.
* @return the string representation of the node content selected from
*         XPath.
* @throws XMLUtilsException
*         when errors occurs.
*/
public String get(Node theNode, String xPath) throws XMLUtilsException

/**
* Gets the string representation of the node content selected from XPath.
*
* @param theNode
*        The input DOM node.
* @param xPath
*        The XPath to evaluate.
* @param defaultValue
*        The value returned if XPath does not select any node.
* @return the string representation of the node content selected from
*         XPath.
* @throws XMLUtilsException
*         when errors occurs.
*/
public String get(Node theNode, String xPath, String defaultValue) throws XMLUtilsException

• Document manipulation

/**
* Sets a user-defined EntityResolverfor the parser.
*
* @param er
*        an object implementing the EntityResolverinterface
*/
public void setEntityResolver(EntityResolver er)

/**
* Create a new document without a name.
*
* @return the new document created.
*/
public Document newDocument()

/**
* Create a new document with a root element name.
*
* @param rootName
*        the name of the root element.
* @return the new document created.
*/
public Document newDocument(String rootName)

/**
* Create a new document with a root element name and a namespace.
*
* @param rootName
*        the name of the root element.
* @param namespace
*        the namespace URI.
* @return the new document created.
*/
public Document newDocument(String rootName, String namespace)

/**
* Create a new document with prefix:name and a namespace.
*
* @param rootName
*        the name of the root element.
* @param prefix
*        the prefix of named root element.
* @param namespace
*        the namespace URI.
* @return the new document created.
*/
public Document newDocument(String rootName, String prefix, String namespace)

/**
* @param doc
* @param name
* @return the created element
* @see org.w3c.dom.Document#createElement(String)
*/
public Element createElement(Document doc, String name)

/**
* @param parent
* @param name
* @return the inserted element
* @throws XMLUtilsException
*/
public Element insertElement(Element parent, String name) throws XMLUtilsException

/**
* @param parent
* @param name
* @return the parent element
* @throws XMLUtilsException
*/
public Element insertText(Element parent, String value) throws XMLUtilsException

/**
* @param parent
* @param name
* @return the parent element
* @throws XMLUtilsException
*/
public Element insertCDATA(Element parent, String value) throws XMLUtilsException

/**
* @param parent
* @param name
* @param value
*/
public void setAttribute(Element parent, String name, String value)

/**
* Creates a new validating, or non-validating, DocumentBuilder
*
* @param isValidating
*        true if we want a validating DOM Parser
* @param nameSpaceAware
* @param forceCrimson
* @return DocumentBuilder
* @throws ParserConfigurationException
*         on errors
*/
public DocumentBuilder getDocumentBuilder(boolean isValidating, boolean nameSpaceAware, boolean forceCrimson) throws ParserConfigurationException