eu.semaine.util
Class XMLTool

java.lang.Object
  extended by eu.semaine.util.XMLTool

public class XMLTool
extends java.lang.Object

Utility methods for working wth XML documents.

Author:
marc

Constructor Summary
XMLTool()
           
 
Method Summary
static org.w3c.dom.Element appendChildElement(org.w3c.dom.Node node, java.lang.String childName)
          Create a child element with the given name and append it below node.
static org.w3c.dom.Element appendChildElement(org.w3c.dom.Node node, java.lang.String childName, java.lang.String childNamespace)
          Create a child element with the given name and namespace, and append it below node.
static org.w3c.dom.Element createElement(org.w3c.dom.Document doc, java.lang.String elementName)
          In the given document, create a new element of the given name, with the same namespace as the document element.
static org.w3c.dom.Element createElement(org.w3c.dom.Document doc, java.lang.String elementName, java.lang.String namespace)
          In the given document, create a new element with the given name and the given namespace.
static javax.xml.namespace.NamespaceContext createNamespaceContext(java.util.Map<java.lang.String,java.lang.String> prefixes2NamespaceURIs)
          Create a namespace context from the given mapping bewteen prefixes and namespace uris.
static org.w3c.dom.traversal.NodeIterator createNodeIterator(org.w3c.dom.Document doc, org.w3c.dom.Node root, java.lang.String namespaceURI, java.lang.String... localNames)
          Create a node iterator for the current document, which will provide exactly the elements below root in the given namespace whose local names are in localNames.
static java.lang.String document2String(org.w3c.dom.Document document)
          Document type to String format conversion
static java.lang.String getAttributeIfAvailable(org.w3c.dom.Element e, java.lang.String attributeName)
          For the given element, return the value of the given attribute if it exists, or null if it doesn't exist.
static org.w3c.dom.Element getChildElementByLocalNameNS(org.w3c.dom.Node node, java.lang.String childName, java.lang.String childNamespace)
          Get the direct child of node that is an element with the given local name and namespace.
static org.w3c.dom.Element getChildElementByTagNameNS(org.w3c.dom.Node node, java.lang.String childName, java.lang.String childNamespace)
          Get the direct child of node that is an element with the given tag name and namespace.
static java.util.List<org.w3c.dom.Element> getChildrenByLocalNameNS(org.w3c.dom.Node node, java.lang.String childName, java.lang.String childNamespace)
          Get a list of all direct children with the given local name and namespace.
static java.util.List<org.w3c.dom.Element> getChildrenByTagNameNS(org.w3c.dom.Node node, java.lang.String childName, java.lang.String childNamespace)
          Get a list of all direct children with the given tag name and namespace.
static javax.xml.namespace.NamespaceContext getDefaultNamespaceContext()
          Get a default namespace context.
static boolean isSameNamespace(java.lang.String namespaceA, java.lang.String namespaceB)
          Determine whether the two namespaces are the same.
static org.w3c.dom.Document mergeTwoXMLFiles(org.w3c.dom.Document xmlFileContent1, org.w3c.dom.Document xmlFileContent2, javax.xml.transform.Templates mergingStylesheet, java.lang.String refCodeName)
          Merge two XML files using XSLT
static java.lang.String mergeTwoXMLFiles(java.lang.String xmlFileContent1, java.lang.String xmlFileContent2, java.io.InputStream xmlStyleSheet, java.lang.String refCodeName)
          Merge two XML files using XSLT
static java.lang.String needAttribute(org.w3c.dom.Element e, java.lang.String attributeName)
          For the given element, return the value of the given attribute if it exists, or complain with a MessageFormatException if it doesn't exist.
static org.w3c.dom.Element needChildElementByLocalNameNS(org.w3c.dom.Node node, java.lang.String childName, java.lang.String childNamespace)
          Same as getChildElementByLocalNameNS(Node, String, String), but throw a MessageFormatException if there is no such child element.
static org.w3c.dom.Element needChildElementByTagNameNS(org.w3c.dom.Node node, java.lang.String childName, java.lang.String childNamespace)
          Same as getChildElementByTagNameNS(Node, String, String), but throw a MessageFormatException if there is no such child element.
static org.w3c.dom.Document newDocument(java.lang.String rootTagname, java.lang.String namespace)
          Create a new document with the given name and namespace for the root element.
static org.w3c.dom.Document newDocument(java.lang.String rootTagname, java.lang.String namespace, java.lang.String version)
          Create a new document with the given name and namespace for the root element, and set the 'version' attribute of the root element to the given value.
static org.w3c.dom.Document parse(java.io.File file)
           
static org.w3c.dom.Document parse(java.io.InputStream in)
           
static java.lang.String[][] splitXPathIntoParts(java.lang.String expr)
          The given string is interpreted as a limited subset of XPath expressions and split into parts.
static org.w3c.dom.Document string2Document(java.lang.String stringRepresentationOfDocument)
           
static org.w3c.dom.Document xpath2doc(java.lang.String xpathExpression, java.lang.String value, javax.xml.namespace.NamespaceContext namespaceContext, org.w3c.dom.Document document)
          Create an XML document from the given XPath expression.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XMLTool

public XMLTool()
Method Detail

string2Document

public static org.w3c.dom.Document string2Document(java.lang.String stringRepresentationOfDocument)
                                            throws org.xml.sax.SAXException,
                                                   java.io.IOException
Throws:
org.xml.sax.SAXException
java.io.IOException

parse

public static org.w3c.dom.Document parse(java.io.File file)
                                  throws org.xml.sax.SAXException,
                                         java.io.IOException
Throws:
org.xml.sax.SAXException
java.io.IOException

parse

public static org.w3c.dom.Document parse(java.io.InputStream in)
                                  throws org.xml.sax.SAXException,
                                         java.io.IOException
Throws:
org.xml.sax.SAXException
java.io.IOException

newDocument

public static org.w3c.dom.Document newDocument(java.lang.String rootTagname,
                                               java.lang.String namespace)
Create a new document with the given name and namespace for the root element.

Parameters:
rootTagname -
namespace - the namespace URI, e.g. http://www.w3.org/2003/04/emma, or null if no namespace is to be associated with the new element.
Returns:

newDocument

public static org.w3c.dom.Document newDocument(java.lang.String rootTagname,
                                               java.lang.String namespace,
                                               java.lang.String version)
Create a new document with the given name and namespace for the root element, and set the 'version' attribute of the root element to the given value.

Parameters:
rootTagname -
namespace - the namespace URI, e.g. http://www.w3.org/2003/04/emma, or null if no namespace is to be associated with the new element.
version - a value to add to the 'version' attribute of the root element
Returns:

createElement

public static org.w3c.dom.Element createElement(org.w3c.dom.Document doc,
                                                java.lang.String elementName)
In the given document, create a new element of the given name, with the same namespace as the document element.

Parameters:
doc - a document
elementName - the name of the new element
Returns:
an element which is not yet included in the tree hierarchy of the document.
Throws:
java.lang.NullPointerException - if doc or elementName is null.

createElement

public static org.w3c.dom.Element createElement(org.w3c.dom.Document doc,
                                                java.lang.String elementName,
                                                java.lang.String namespace)
In the given document, create a new element with the given name and the given namespace.

Parameters:
doc -
elementName -
namespace - the namespace URI, e.g. http://www.w3.org/2003/04/emma, or null if no namespace is to be associated with the new element.
Returns:
an element which is not yet included in the tree hierarchy of the document.
Throws:
java.lang.NullPointerException - if doc or elementName is null.

appendChildElement

public static org.w3c.dom.Element appendChildElement(org.w3c.dom.Node node,
                                                     java.lang.String childName)
Create a child element with the given name and append it below node. The new element will have the same namespace as node. If node has a namespace prefix, the new element will also use that namespace prefix.

Parameters:
node -
childName -
Returns:
the child element

appendChildElement

public static org.w3c.dom.Element appendChildElement(org.w3c.dom.Node node,
                                                     java.lang.String childName,
                                                     java.lang.String childNamespace)
Create a child element with the given name and namespace, and append it below node.

Parameters:
node -
childName -
childNamespace - the namespace of the child, or null if no namespace is desired.
Returns:
the child element

getChildElementByTagNameNS

public static org.w3c.dom.Element getChildElementByTagNameNS(org.w3c.dom.Node node,
                                                             java.lang.String childName,
                                                             java.lang.String childNamespace)
Get the direct child of node that is an element with the given tag name and namespace.

Parameters:
node -
childName -
childNamespace -
Returns:
the child element, or null if there is no such child.

getChildElementByLocalNameNS

public static org.w3c.dom.Element getChildElementByLocalNameNS(org.w3c.dom.Node node,
                                                               java.lang.String childName,
                                                               java.lang.String childNamespace)
Get the direct child of node that is an element with the given local name and namespace.

Parameters:
node -
childName - the child's local name, without a namespace prefix.
childNamespace -
Returns:
the child element, or null if there is no such child.

needChildElementByTagNameNS

public static org.w3c.dom.Element needChildElementByTagNameNS(org.w3c.dom.Node node,
                                                              java.lang.String childName,
                                                              java.lang.String childNamespace)
                                                       throws MessageFormatException
Same as getChildElementByTagNameNS(Node, String, String), but throw a MessageFormatException if there is no such child element.

Parameters:
node -
childName -
childNamespace -
Returns:
a non-null child element
Throws:
MessageFormatException - if there is no such child, i.e. when getChildElementByTagNameNS() would return null.

needChildElementByLocalNameNS

public static org.w3c.dom.Element needChildElementByLocalNameNS(org.w3c.dom.Node node,
                                                                java.lang.String childName,
                                                                java.lang.String childNamespace)
                                                         throws MessageFormatException
Same as getChildElementByLocalNameNS(Node, String, String), but throw a MessageFormatException if there is no such child element.

Parameters:
node -
childName -
childNamespace -
Returns:
a non-null child element
Throws:
MessageFormatException - if there is no such child, i.e. when getChildElementByTagNameNS() would return null.

needAttribute

public static java.lang.String needAttribute(org.w3c.dom.Element e,
                                             java.lang.String attributeName)
                                      throws MessageFormatException
For the given element, return the value of the given attribute if it exists, or complain with a MessageFormatException if it doesn't exist.

Parameters:
e - the element whose attribute to return
attributeName - the name of the attribute to look up.
Returns:
the String value of the attribute if it exists
Throws:
MessageFormatException - if the attribute doesn't exist.

getAttributeIfAvailable

public static java.lang.String getAttributeIfAvailable(org.w3c.dom.Element e,
                                                       java.lang.String attributeName)
For the given element, return the value of the given attribute if it exists, or null if it doesn't exist. Note that this is different from calling e.getAttribute(), which will return the empty string both if the attribute doesn't exist and if it exists and has the empty value.

Parameters:
e -
attributeName -
Returns:
the String value of the attribute if it exists, or null

getChildrenByTagNameNS

public static java.util.List<org.w3c.dom.Element> getChildrenByTagNameNS(org.w3c.dom.Node node,
                                                                         java.lang.String childName,
                                                                         java.lang.String childNamespace)
Get a list of all direct children with the given tag name and namespace. Whereas getChildElementByTagNameNS() returns the single first child, this method returns all the children that match.

Parameters:
node -
childName -
childNamespace -
Returns:
a list containing the children that match, or an empty list if none match.
Throws:
MessageFormatException

getChildrenByLocalNameNS

public static java.util.List<org.w3c.dom.Element> getChildrenByLocalNameNS(org.w3c.dom.Node node,
                                                                           java.lang.String childName,
                                                                           java.lang.String childNamespace)
Get a list of all direct children with the given local name and namespace. Whereas getChildElementByTagNameNS() returns the single first child, this method returns all the children that match.

Parameters:
node -
childName - the child's local name
childNamespace -
Returns:
a list containing the children that match, or an empty list if none match.
Throws:
MessageFormatException

isSameNamespace

public static boolean isSameNamespace(java.lang.String namespaceA,
                                      java.lang.String namespaceB)
Determine whether the two namespaces are the same.

Parameters:
namespaceA - a string representing a namespace, or null
namespaceB - a string representing a namespace, or null
Returns:
true if both are null or both are the same string, false otherwise.

mergeTwoXMLFiles

public static java.lang.String mergeTwoXMLFiles(java.lang.String xmlFileContent1,
                                                java.lang.String xmlFileContent2,
                                                java.io.InputStream xmlStyleSheet,
                                                java.lang.String refCodeName)
                                         throws java.lang.Exception,
                                                java.io.FileNotFoundException
Merge two XML files using XSLT

Parameters:
xmlFileContent1, - first XML file content
xmlFileContent2, - second XML file content
xmlStyleSheet, - XSL style sheet as a inputstream
refCodeName, - code name used in xsl sheet to refer xmlFile2 (example: semaine.mary.intonation )
Returns:
output of merged xml file
Throws:
java.lang.Exception
java.io.FileNotFoundException

mergeTwoXMLFiles

public static org.w3c.dom.Document mergeTwoXMLFiles(org.w3c.dom.Document xmlFileContent1,
                                                    org.w3c.dom.Document xmlFileContent2,
                                                    javax.xml.transform.Templates mergingStylesheet,
                                                    java.lang.String refCodeName)
                                             throws java.lang.Exception,
                                                    java.io.FileNotFoundException
Merge two XML files using XSLT

Parameters:
xmlFileContent1, - first XML file content
xmlFileContent2, - second XML file content
mergingStylesheet, - the XSLT style sheet merging xml2 into xml1.
refCodeName, - code name used in xsl sheet to refer xmlFile2 (example: semaine.mary.intonation )
Returns:
output of merged xml file
Throws:
java.lang.Exception
java.io.FileNotFoundException

document2String

public static java.lang.String document2String(org.w3c.dom.Document document)
                                        throws SystemConfigurationException
Document type to String format conversion

Parameters:
document -
Returns:
Throws:
java.lang.Exception
java.io.FileNotFoundException
SystemConfigurationException

createNodeIterator

public static org.w3c.dom.traversal.NodeIterator createNodeIterator(org.w3c.dom.Document doc,
                                                                    org.w3c.dom.Node root,
                                                                    java.lang.String namespaceURI,
                                                                    java.lang.String... localNames)
Create a node iterator for the current document, which will provide exactly the elements below root in the given namespace whose local names are in localNames. This is independent of any namespace prefixes.

Parameters:
doc -
root -
namespaceURI -
localNames - the array of local names to be accepted.
Returns:

xpath2doc

public static org.w3c.dom.Document xpath2doc(java.lang.String xpathExpression,
                                             java.lang.String value,
                                             javax.xml.namespace.NamespaceContext namespaceContext,
                                             org.w3c.dom.Document document)
                                      throws java.lang.NullPointerException,
                                             java.lang.IllegalArgumentException
Create an XML document from the given XPath expression. The given string is interpreted as a limited subset of XPath expressions and split into parts. Each part except the last one is expected to follow precisely the following form: "/" ( prefix ":" ) ? localname ( "[" "@" attName "=" "'" attValue "'" "]" ) ? The last part must be either "/" "text()" or "/" "@" attributeName .

Parameters:
xpathExpression - an xpath expression from which the given document can be created. must not be null.
value - the value to insert at the location identified by the xpath expression. if this is null, the empty string is added.
namespaceContext - the namespace context to use for resolving namespace prefixes. If this is null, the namespace context returned by getDefaultNamespaceContext() will be used.
document - if not null, the xpath expression + value pair will be added to the document. If null, a new document will be created from the xpathExpression and value pair.
Returns:
a document containing the given information
Throws:
java.lang.NullPointerException - if xpathExpression is null.
java.lang.IllegalArgumentException - if the xpath expression is not valid, or if the xpath expression is incompatible with the given document (e.g., different root node)

splitXPathIntoParts

public static java.lang.String[][] splitXPathIntoParts(java.lang.String expr)
                                                throws java.lang.IllegalArgumentException
The given string is interpreted as a limited subset of XPath expressions and split into parts. Each part except the last one is expected to follow precisely the following form: "/" ( prefix ":" ) ? localname ( "[" "@" attName "=" "'" attValue "'" "]" ) ? The last part must be either "/" "text()" or "/" "@" attributeName .

Parameters:
expr - the string to be split as an xpath expression
Returns:
an array of string arrays. All except the last entry in this array is guaranteed to have four elements, with the meaning:
  • [0]: prefix (can be null)
  • [1]: localname (guaranteed not to be null)
  • [2]: attributeName (can be null)
  • [3]: attributeValue (is guaranteed to be null when attributeName is null; when attributeName is non-null, and attributeValue is null, then the attribute must be present but there are no constraints about its value)
The last element in the returned array has either length 1 or length 0. If it is of length 0, then the XPath expression ended in "text()", i.e. the value to be referenced is the text content of the enclosing Element; if it is of length 1, the String contained is guaranteed to be non-null and represents the name of the attribute to be referenced on the enclosing Element.
Throws:
java.lang.IllegalArgumentException - if expr does not match the expected format.

createNamespaceContext

public static javax.xml.namespace.NamespaceContext createNamespaceContext(java.util.Map<java.lang.String,java.lang.String> prefixes2NamespaceURIs)
Create a namespace context from the given mapping bewteen prefixes and namespace uris.

Parameters:
prefixes2NamespaceURIs -
Returns:
a namespace context

getDefaultNamespaceContext

public static javax.xml.namespace.NamespaceContext getDefaultNamespaceContext()
Get a default namespace context. Its namespace definitions include at least the prefixes "semaine", "emma" and "emotion".

Returns: