Difference between revisions of "XMLUtils"
| Line 285: | Line 285: | ||
/** | /** | ||
| − | * | + | * Uses the default entity resolver to resolve entities into the |
| + | * configuration files. The default entity resolver does not resolve | ||
| + | * anything. | ||
* | * | ||
| − | |||
| − | |||
*/ | */ | ||
public static void setDefaultEntityResolver(EntityResolver er) | public static void setDefaultEntityResolver(EntityResolver er) | ||
| Line 726: | Line 726: | ||
<syntaxhighlight lang="java5"> | <syntaxhighlight lang="java5"> | ||
/** | /** | ||
| − | * Sets | + | * Sets the entity resolver used to resolve entities into the configuration |
| − | * | + | * files. |
| − | * @param | + | * |
| − | * | + | * @param entityResolver |
| + | * EntityResolver to use in order to resolve entity. If | ||
| + | * <code>null</code> is specified then the default XML mechanism is | ||
| + | * used. | ||
*/ | */ | ||
| − | public void setEntityResolver(EntityResolver | + | public static synchronized void setEntityResolver(EntityResolver entityResolver) |
/** | /** | ||
Revision as of 13:07, 18 December 2012
Class FQN: it.greenvulcano.util.xml.XMLUtils
Following the XMLUtils 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 Document/Node 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 Document/Node parsed from the given input object.
* @throws XMLUtilsException
*/
public static Node 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
/**
* Aggregate an array of documents or elements.
*
* @param aggrRootElement
* aggregate document root element name
* @param aggrNamespace
* namespace URI of the aggregate document root, can be null
* @param docs
* an array of Document, Node, String, byte[] to be aggregated
* @return an aggregate Document
* @throws XMLUtilsException
*/
public static Document aggregateXML_S(String aggrRootElement, String aggrNamespace, Object[] docs) throws XMLUtilsException
/**
* Facility to aggregate two documents or elements.
*
* @param aggrRootElement
* aggregate document root element name
* @param aggrNamespace
* namespace URI of the aggregate document root, can be null
* @param docA
* a Document, Node, String, byte[] to be aggregated
* @param docB
* a Document, Node, String, byte[] to be aggregated
* @return an aggregate Document
* @throws XMLUtilsException
*/
public static Document aggregateXML_S(String aggrRootElement, String aggrNamespace, Object docA, Object docB) 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)
/**
* Uses the default entity resolver to resolve entities into the
* configuration files. The default entity resolver does not resolve
* anything.
*
*/
public static void setDefaultEntityResolver(EntityResolver er)
Following the XMLUtils public instance methods
- Getting&Using instance
XMLUtils parser = null;
try {
parser = XMLUtils.getParserInstance();
.....
parser.someMethod(someParam);
.....
}
finally {
XMLUtils.releaseParserInstance(parser);
}
/**
* Gets an instance of XMLUtils from the pool. 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.
*
* @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 Document/Node 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 Document/Node parsed from the given input object.
* @throws XMLUtilsException
*/
public Node 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
/**
* Aggregate documents or elements.
*
* @param aggrRootElement
* aggregate document root element name
* @param aggrNamespace
* namespace URI of the aggregate document root, can be null
* @param docs
* an array of Document, Node, String, byte[] to be aggregated
* @return an aggregate Document
* @throws XMLUtilsException
*/
public Document aggregateXML(String aggrRootElement, String aggrNamespace, Object[] docs) 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 the entity resolver used to resolve entities into the configuration
* files.
*
* @param entityResolver
* EntityResolver to use in order to resolve entity. If
* <code>null</code> is specified then the default XML mechanism is
* used.
*/
public static synchronized void setEntityResolver(EntityResolver entityResolver)
/**
* 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
The methods described can be used in OGNL expressions. For example the parsing for an input of type String, you can use the expression:
#doc = @it.greenvulcano.util.xml.XMLUtils@parseDOM(input)
To extract a value from a document through an xpath expression:
#value = @it.greenvulcano.util.xml.XMLUtils@get_S(#doc, "/doc/elem/@attr")
