com.kuka.common
Class XmlUtil

java.lang.Object
  com.kuka.common.XmlUtil

public final class XmlUtil
extends Object

Merging algorithm for XML configuration files.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

Field Summary

static String	XMLATTR_MERGE Attribute name to use for defining the attributes to be set or replaced in XML files being merged.
static String	XMLNS_MERGE XML namespace for merge operations allowing to replace existing tags in XML files being merged.

Method Summary

static void	createAttribute(Node node, String name, String value) Creates an attributes for the given node.
static ParameterSet	createParameterSetFromNode(Node node) Creates and loads a parameter set out of a Xml node.
static Document	deleteXmlElements(Document original, Document elementsToBeDelete) Delete XML data listed in ElementsToBeDelete from the original document.
static Node	getChildNode(String childName, Node node) Gets a names child node.
static Node	getOptionalChildNode(String childName, Node node) Gets a named child node.
static Element	getSingleElement(Element parent, String elementName) gets the first element with the specified name.
static Document	getXmlDocument(File file) reads a XML file by its file.
static Document	getXmlDocument(InputStream input) reads XML data from an input stream.
static Document	getXmlDocument(String filename) reads a XML file by its filename.
static Document	getXmlDocument(URL url) imports the xml file into a document.
static Document	getXmlDocumentFromString(String input) Reads XML data from the given string.
static boolean	hasAttribute(String name, Node node) Checks if the given node has the specified attribute.
static Document	mergeXmlElements(Document original, Document template) Merges the XML data from template into the original document.
static DocumentBuilder	newBuilder() Returns the DocumentBuilder.
static Document	newDocument()
static String	optionalAttribute(String name, Node node, String defaultValue) Gets a attribute from a node.
static void	removeIgnorableWhitespace(Document doc) Removes all ignorable whitespace from the element, as defined per the XML spec.
static void	removeIgnorableWhitespace(Element e) Removes all ignorable whitespace from the element, as defined per the XML spec.
static Document	replaceVariablesAndParse(URL url) Loads the document from the given file and replaces contains VAR tags.
static String	requiredAttribute(String name, Node node) Gets a attribute from a node.
static void	validateXmlDocument(File xmlFile, URL schemaUrl) validates a XML file - based on the given XML schema the structure of the XML file will be validated.
static void	writeDocumentToXml(Document doc, File file) Writes the given document to the specified xml file.
static void	writeDocumentToXml(Document doc, String filename) Writes the given document to the specified xml file.
static void	writeXmlFile(Document doc, String filename) Deprecated. Use writeDocumentToXml(Document doc, String filename) instead

Methods inherited from class java.lang.Object

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

Field Detail

XMLNS_MERGE

public static final String XMLNS_MERGE

XML namespace for merge operations allowing to replace existing tags in XML files being merged.

See Also:

mergeXmlElements(Document, Document), Constant Field Values

XMLATTR_MERGE

public static final String XMLATTR_MERGE

Attribute name to use for defining the attributes to be set or replaced in XML files being merged. See XMLNS_MERGE.

See Also:

Constant Field Values

Method Detail

newBuilder

public static DocumentBuilder newBuilder()

Returns the DocumentBuilder.

Returns:

The DocumentBuilder

newDocument

public static Document newDocument()

Returns:

A new document.

getXmlDocument

public static Document getXmlDocument(File file)
                               throws SAXException,
                                      IOException

reads a XML file by its file.

Parameters:

file - file to read

Returns:

XML document

Throws:

SAXException - error parsing the XML document

IOException - error reading the XML document

getXmlDocument

public static Document getXmlDocument(String filename)
                               throws SAXException,
                                      IOException

reads a XML file by its filename.

Parameters:

filename - name of the XML file

Returns:

XML document

Throws:

SAXException - error parsing the XML document

IOException - error reading the XML document

getXmlDocument

public static Document getXmlDocument(InputStream input)
                               throws SAXException,
                                      IOException

reads XML data from an input stream.

Parameters:

input - stream with XML data

Returns:

XML document

Throws:

SAXException - error parsing the XML document

IOException - error reading the XML document

getXmlDocument

public static Document getXmlDocument(URL url)
                               throws SAXException,
                                      IOException

imports the xml file into a document.

Parameters:

url - The url where the xml file can be found

Returns:

the successful opened xml file as a document

Throws:

SAXException - error parsing the XML document

IOException - error reading the XML document

getXmlDocumentFromString

public static Document getXmlDocumentFromString(String input)
                                         throws SAXException,
                                                IOException

Reads XML data from the given string.

Parameters:

input - string containing an XML document.

Returns:

XML document from the specified string.

Throws:

SAXException - if XML is not correct.

IOException - if string can't be read correctly.

validateXmlDocument

public static void validateXmlDocument(File xmlFile,
                                       URL schemaUrl)
                                throws SAXException,
                                       IOException

validates a XML file - based on the given XML schema the structure of the XML file will be validated.

Parameters:

xmlFile - XML file to validate

schemaUrl - XML schema file, which is used for the validation

Throws:

SAXException - the validation process has detected an error in the XML file or a general parser error has been occurred (either within the XML file or the XML schema file)

IOException - error reading the XML document or the XML schema

writeXmlFile

@Deprecated
public static void writeXmlFile(Document doc,
                                           String filename)
                         throws TransformerException

Deprecated. Use writeDocumentToXml(Document doc, String filename) instead

writes a XML file to the file system.

Parameters:

doc - XML document

filename - name of the XML file to write

Throws:

TransformerException - error transforming XML data

writeDocumentToXml

public static void writeDocumentToXml(Document doc,
                                      File file)

Writes the given document to the specified xml file.

Parameters:

doc - The document to be written.

file - The file to which the document writes it's contents.

writeDocumentToXml

public static void writeDocumentToXml(Document doc,
                                      String filename)

Writes the given document to the specified xml file.

Parameters:

doc - The document to be written.

filename - The filename to which the document writes it's contents.

deleteXmlElements

public static Document deleteXmlElements(Document original,
                                         Document elementsToBeDelete)

Delete XML data listed in ElementsToBeDelete from the original document.

Parameters:

original - the original document where XML element should be removed

elementsToBeDelete - the XML elements that should be remove from the original document

Returns:

the merged document

mergeXmlElements

public static Document mergeXmlElements(Document original,
                                        Document template)

Merges the XML data from template into the original document. Each element and attribute in template is matched against existing elements and attributes in original. The merge mechanism recursively works as follows:

• For each element in template, all elements of original with the same name and the same hierarchical position will match if all attributes given in the template element are present with the same value in the original element.
• For matching elements attributes can be set as described below, and matching continues recursively with the child elements.
• If elements match by name but have conflicting attribute values, a new element will be created as a sibling of the existing element.

To set or replace existing attributes on an element you have to list the elements in the value of the attrs attribute in the xmlns="http://www.kuka.com/sunrise/xml/merge" namespace. The value must be a comma-delimited list of name=value pairs, with no whitespace or quotes ("\", "," and "=" must be escaped as "\\", "\," and "\=" inside an attribute value, respectively). For example:
<myelement m:attrs="name=James Bond,occupation=Spy"/>
will result in attributes
<myelement name="James Bond" occupation="Spy"/>

Example usage

Original document to merge:

 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <TestXML>
     <Knoten attrib="1" value="on"/>
     <Knoten attrib="2" value="on">
         <Element id="1"/>
         <Element id="2"/>
     </Knoten>
     <Knoten attrib="3" value="on">
         <Element id="1"/>
         <Element id="2"/>
     </Knoten>
     <Knoten other="other">
         <Element id="1"/>
         <Element id="5"/>
     </Knoten>
 </TestXML>
 

Template document to be merged into the first document:

 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <TestXML xmlns:m="http://www.kuka.com/sunrise/xml/merge">
     <Knoten attrib="4" value="on"/>
     <Knoten>
         <Element id="3"/>
     </Knoten>
     <Knoten attrib="5" value="on"/>
     <Knoten attrib="2" m:attrs="value=off"/>
     <Knoten attrib="3">
         <Element id="2" m:attrs="id=-1,comment=Hello World"/>
     </Knoten>
 </TestXML>
 

Resulting document:

 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <TestXML>
     <Knoten attrib="1" value="on">
         <Element id="3"/>
     </Knoten>
     <Knoten attrib="2" value="off">
         <Element id="1"/>
         <Element id="2"/>
         <Element id="3"/>
     </Knoten>
     <Knoten attrib="3" value="on">
         <Element id="1"/>
         <Element id="-1" comment="Hello World"/>
         <Element id="3"/>
     </Knoten>
     <Knoten other="other">
         <Element id="1"/>
         <Element id="5"/>
         <Element id="3"/>
     </Knoten>
     <Knoten attrib="4" value="on"/>
     <Knoten attrib="5" value="on"/>
 </TestXML>
 

Parameters:

original - the original document where new XML element should be added

template - the document with the new XML elements that should be merged into the original document. The document must have been parsed with XML namespace support.

Returns:

the merged document

replaceVariablesAndParse

public static Document replaceVariablesAndParse(URL url)

Loads the document from the given file and replaces contains VAR tags.

Parameters:

url - The url to load.

Returns:

The parsed document.

hasAttribute

public static boolean hasAttribute(String name,
                                   Node node)

Checks if the given node has the specified attribute.

Parameters:

name - The name of the attribute.

node - The node.

Returns:

True of the given node has the attribute.

requiredAttribute

public static String requiredAttribute(String name,
                                       Node node)

Gets a attribute from a node. Fails if attribute is not found.

Parameters:

name - The name of the attribute.

node - The node from which we read out the attribute.

Returns:

The value of the attribute.

optionalAttribute

public static String optionalAttribute(String name,
                                       Node node,
                                       String defaultValue)

Gets a attribute from a node. Returns the default value if the attribute is not found.

Parameters:

name - The name of the attribute.

node - The node from which we read out the attribute.

defaultValue - The default value.

Returns:

The attribute value or the default value if the attribute was not found.

getChildNode

public static Node getChildNode(String childName,
                                Node node)

Gets a names child node. Fails if node was not found.

Parameters:

childName - The child node name.

node - The parent node.

Returns:

The child node.

getOptionalChildNode

public static Node getOptionalChildNode(String childName,
                                        Node node)

Gets a named child node. Returns null if node was not found.

Parameters:

childName - The child node name.

node - The parent node.

Returns:

The child node.

getSingleElement

public static Element getSingleElement(Element parent,
                                       String elementName)

gets the first element with the specified name.

Parameters:

parent - the parent to search

elementName - name of the Tag

Returns:

XML element with the specified name

createParameterSetFromNode

public static ParameterSet createParameterSetFromNode(Node node)

Creates and loads a parameter set out of a Xml node.

Parameters:

node - The node.

Returns:

The parameter set with the attributes of the node as values.

createAttribute

public static void createAttribute(Node node,
                                   String name,
                                   String value)

Creates an attributes for the given node.

Parameters:

node - The node.

name - The name of the attribute.

value - The value of the attribute.

removeIgnorableWhitespace

public static void removeIgnorableWhitespace(Document doc)

Removes all ignorable whitespace from the element, as defined per the XML spec.

Parameters:

doc - the document which will recursively be stripped of whitespace

removeIgnorableWhitespace

public static void removeIgnorableWhitespace(Element e)

Removes all ignorable whitespace from the element, as defined per the XML spec.

Parameters:

e - the element which will recursively be stripped of whitespace