com.tangosol.run.xml
Class XmlHelper

java.lang.Object
  com.tangosol.util.Base
      com.tangosol.run.xml.XmlHelper

public abstract class XmlHelper
extends Base

This abstract class contains XML manipulation methods.

Author:

cp/gg 2000.10.25

Nested Class Summary

static interface

XmlHelper.ParameterResolver An interface that describes a callback to resolve a substitutable parameter value.

Constructor Summary

XmlHelper()

Method Summary

static void	addElements(XmlElement xml, Iterator iter) Add the elements from the iterator to the passed XML.
static Object	convert(Object o, int nType) Convert the passed Object to the specified type.
static String	decodeAttribute(String sValue) Decode an attribute value that was quoted.
static String	decodeContent(String sValue) Decode an element's content value.
static String	decodeUri(String sUri) Decode a System Identifier as per the XML 1.0 Specification 2nd ed section 4.2.2.
static String	encodeAttribute(String sValue, char chQuote) Encode an attribute value so that it can be quoted and made part of a valid and well formed XML document.
static String	encodeContent(String sValue, boolean fPreferBlockEscape) Encode an element's content value so that it can be made part of a valid and well formed XML document.
static String	encodeUri(String sUri) Encode a System Identifier as per the XML 1.0 Specification second edition, section 4.2.2.
static XmlElement	ensureElement(XmlElement xml, String sPath) Ensure that a child element exists.
static void	ensureNamespace(XmlElement xml, String sPrefix, String sUri) Ensure the existence of the Namespace declaration attribute in a context of the specified XmlElement.
static boolean	equalsElement(XmlElement xml1, XmlElement xml2) Compare one XML element with another XML element for equality.
static boolean	equalsValue(XmlValue val1, XmlValue val2) Compare one XML value with another XML value for equality.
static XmlElement	findElement(XmlElement xml, String sPath) Find a child element of the specified element with the specified '/'-delimited path.
static XmlElement	findElement(XmlElement xml, String sPath, Object oValue) Find a child element of the specified element with the specified '/'-delimited path and the specified value.
static String	getAbsolutePath(XmlElement xml) Get the '/'-delimited path of the passed element starting from the root element.
static XmlValue	getAttribute(XmlElement xml, String sLocal, String sUri) Get an attribute of the specified XmlElement that matches to the specified local name and the specified Namespace URI.
static XmlElement	getElement(XmlElement xml, String sName) Get a child element for the specified element.
static XmlElement	getElement(XmlElement xml, String sLocal, String sUri) Get a child element of the specified XmlElement that matches to the specified local name and the specified Namespace URI.
static Iterator	getElements(XmlElement xml, String sLocal, String sUri) Get an iterator of child elements of the specified XmlElement that match to the specified local name and the specified Namespace URI.
static String	getNamespacePrefix(XmlElement xml, String sUri) Retrieve the Namespace prefix for a given URI in a context of the specified XmlElement.
static String	getNamespaceUri(XmlElement xml, String sPrefix) Retrieve the Namespace URI for a given prefix in a context of the specified XmlElement.
static String	getUniversalName(String sLocal, String sPrefix) Return a universal XML element name.
static int	hashElement(XmlElement xml) Provide a hash value for the XML element and all of its contained information.
static int	hashValue(XmlValue val) Provide a hash value for the XML value.
static boolean	isCommentValid(String sComment) Validate the passed comment.
static boolean	isElementMatch(XmlElement xml, String sLocal, String sUri) Check whether or not an element matches to the specified local name and Namespace URI.
static boolean	isEmpty(XmlElement xml) Check whether or not this element or any of its children elements have any content such as values or attributes.
static boolean	isEncodingValid(String sEncoding) Validate the passed encoding.
static boolean	isNameMatch(XmlElement xml, String sName, String sLocal, String sUri) Check whether or not a universal (composite) name matches to the specified local name and Namespace URI.
static boolean	isNameValid(String sName) Validate the passed name.
static boolean	isPublicIdentifierValid(String sName) Validate the passed public identifier.
static boolean	isSystemIdentifierValid(String sName) Validate the passed system identifier.
static boolean	isWhitespace(char ch) Test if the specified character is XML whitespace.
static XmlDocument	loadXml(Class clz) Load XML from a file for a class.
static XmlDocument	loadXml(Class clz, String sCharset) Load XML from a file for a class using a given charset.
static XmlDocument	loadXml(Class clz, String sName, String sCharset) Load XML from a file that is collocated with the specified class with a given charset.
static XmlDocument	loadXml(InputStream stream) Load XML from a stream.
static XmlDocument	loadXml(InputStream stream, String sCharset) Load XML from a stream using the specified charset.
static XmlDocument	loadXml(String sXml) Load XML from a string.
static void	loadXml(String sXml, XmlDocument xmlRoot) Load XML from a String into the specified XmlElement.
static void	overrideElement(XmlElement xmlBase, XmlElement xmlOverride) Override the values of the specified base element with values from the specified override element.
static Object[]	parseInitParams(XmlElement xmlParams) Parse the specified "init-params" element of the following structure:
static Object[]	parseInitParams(XmlElement xmlParams, XmlHelper.ParameterResolver resolver) Parse the specified "init-params" element of the following structure:
static void	purgeChildrenNamespace(XmlElement xml) For the children elements of the specified XmlElement purge the repetetive Namespace declarations.
static void	purgeNamespace(XmlElement xml) For the specified XmlElement purge the Namespace declarations that are declared somewhere up the xml tree.
static String	quote(String s) XML quote the passed string.
static int	removeElement(XmlElement xml, String sName) Remove all immediate child elements with the given name
static boolean	replaceElement(XmlElement xmlParent, XmlElement xmlReplace) Replace a child element with the same name as the specified element.
static void	replaceSystemProperties(XmlElement xml, String sPropertyAttribute) Replace the values of the XmlElement and all its children that contain the specified attribute with the values returned by the System.getProperty() call.
static String	toString(XmlSerializable xml) Return the XML of an XmlSerializable object as a String.
static void	transformInitParams(XmlElement xmlParent, XmlElement xmlParams) Transform the specified "init-params" element of the following structure:
static String	trim(String s) Trim XML whitespace.
static String	trimb(String s) Trim trailing XML whitespace.
static String	trimf(String s) Trim leading XML whitespace.

Constructor Detail

XmlHelper

public XmlHelper()

Method Detail

loadXml

public static XmlDocument loadXml(Class clz)

Load XML from a file for a class.

Parameters:

clz - the class for which to load the XML

Returns:

the XML content or null

loadXml

public static XmlDocument loadXml(Class clz,
                                  String sCharset)

Load XML from a file for a class using a given charset.

Parameters:

clz - the class for which to load the XML

sCharset - the charset name; pass null to use the default charset

Returns:

the XML content or null

loadXml

public static XmlDocument loadXml(Class clz,
                                  String sName,
                                  String sCharset)

Load XML from a file that is collocated with the specified class with a given charset.

Parameters:

clz - the class for which to load the XML

sName - the XML file name (including extension if any) that exists in the package from which the class was loaded

sCharset - the charset name; pass null to use the default charset

Returns:

the XML content or null

loadXml

public static XmlDocument loadXml(InputStream stream)

Load XML from a stream.

Parameters:

stream - the InputStream object

Returns:

the XML content

loadXml

public static XmlDocument loadXml(InputStream stream,
                                  String sCharset)

Load XML from a stream using the specified charset.

Parameters:

stream - the InputStream object

sCharset - the charset name

Returns:

the XML content

loadXml

public static XmlDocument loadXml(String sXml)

Load XML from a string.

Parameters:

sXml - the string containing an XML

Returns:

the XML content

loadXml

public static void loadXml(String sXml,
                           XmlDocument xmlRoot)

Load XML from a String into the specified XmlElement.

Parameters:

sXml - the string containing an XML

xmlRoot - the root XmlElement to parse the string into

isEncodingValid

public static boolean isEncodingValid(String sEncoding)

Validate the passed encoding. Encodings are lating strings defined as: [A-Za-z] ([A-Za-z0-9._] | '-')*

Parameters:

sEncoding - the document encoding

Returns:

true if the encoding is valid, false otherwise

isSystemIdentifierValid

public static boolean isSystemIdentifierValid(String sName)

Validate the passed system identifier.

Parameters:

sName - the system identifier of the XML document

Returns:

true if the identifier is valid, false otherwise

isPublicIdentifierValid

public static boolean isPublicIdentifierValid(String sName)

Validate the passed public identifier.

Parameters:

sName - the public identifier of the XML document

Returns:

true if the identifier is valid, false otherwise

isCommentValid

public static boolean isCommentValid(String sComment)

Validate the passed comment. Comments may not contain "--". See the XML specification 1.0 2ed section 2.5.

Parameters:

sComment - the XML comment

Returns:

true if the comment is valid, false otherwise

isNameValid

public static boolean isNameValid(String sName)

Validate the passed name. Currently, this does not allow the "CombiningChar" or "Extender" characters that are allowed by the XML specification 1.0 2ed section 2.3 [4].

Parameters:

sName - the XML name to validate

Returns:

true if the name is valid, false otherwise

isWhitespace

public static boolean isWhitespace(char ch)

Test if the specified character is XML whitespace.

Parameters:

ch - a character

Returns:

true if the passed character is XML whitespace

trim

public static String trim(String s)

Trim XML whitespace. See XML 1.0 2ed section 2.3.

Parameters:

s - the original String

Returns:

the passed String minus any leading or trailing whitespace

trimf

public static String trimf(String s)

Trim leading XML whitespace. See XML 1.0 2ed section 2.3.

Parameters:

s - the original String

Returns:

the passed String minus any leading whitespace

trimb

public static String trimb(String s)

Trim trailing XML whitespace. See XML 1.0 2ed section 2.3.

Parameters:

s - the original String

Returns:

the passed String minus any trailing whitespace

encodeAttribute

public static String encodeAttribute(String sValue,
                                     char chQuote)

Encode an attribute value so that it can be quoted and made part of a valid and well formed XML document.

Parameters:

sValue - the attribute value to encode

chQuote - the character that will be used to quote the attribute

Returns:

the attribute value in its encoded form (but not quoted)

decodeAttribute

public static String decodeAttribute(String sValue)

Decode an attribute value that was quoted.

Parameters:

sValue - the attribute value to decode

Returns:

the attribute value in its decoded form

encodeContent

public static String encodeContent(String sValue,
                                   boolean fPreferBlockEscape)

Encode an element's content value so that it can be made part of a valid and well formed XML document.

Parameters:

sValue - the content value to encode

fPreferBlockEscape - pass true to use the CDATA escape if two conditions are met: that escaping is required, and that the value does not contain the string "]]>"

Returns:

the attribute value in its encoded form (but not quoted)

decodeContent

public static String decodeContent(String sValue)

Decode an element's content value.

Parameters:

sValue - the content value to decode

Returns:

the attribute value in its decoded form

encodeUri

public static String encodeUri(String sUri)

Encode a System Identifier as per the XML 1.0 Specification second edition, section 4.2.2.

Parameters:

sUri - the URI to encode

Returns:

the encoded URI

decodeUri

public static String decodeUri(String sUri)

Decode a System Identifier as per the XML 1.0 Specification 2nd ed section 4.2.2.

Parameters:

sUri - the URI to decode

Returns:

the decoded URI

quote

public static String quote(String s)

XML quote the passed string.

Parameters:

s - the string to quote

Returns:

the quoted string

getAbsolutePath

public static String getAbsolutePath(XmlElement xml)

Get the '/'-delimited path of the passed element starting from the root element.

Parameters:

xml - an XML element

Returns:

the path to the passed element in "absolute" format

isEmpty

public static boolean isEmpty(XmlElement xml)

Check whether or not this element or any of its children elements have any content such as values or attributes.

Parameters:

xml - an XmlElement

Returns:

true iff the element itself and all of its children have neither values nor attributes

getElement

public static XmlElement getElement(XmlElement xml,
                                    String sName)

Get a child element for the specified element. If multiple child elements exist that have the specified name, then the behavior of this method is undefined, and it is permitted to return any one of the matching elements, to return null, or to throw an arbitrary runtime exception.

Parameters:

xml - an XML element

sName - the name of the desired child element

Returns:

the specified element as an object implementing XmlElement, or null if the specified child element does not exist

findElement

public static XmlElement findElement(XmlElement xml,
                                     String sPath)

Find a child element of the specified element with the specified '/'-delimited path. The path format is based on a subset of the XPath specification, supporting:

• Leading '/' to specify root
• Use of '/' as a path delimiter
• Use of '..' to specify parent

If multiple child elements exist that have the specified name, then the behavior of this method is undefined, and it is permitted to return any one of the matching elements, to return null, or to throw an arbitrary runtime exception.

Parameters:

xml - an XML element

sPath - the path to follow to find the desired XML element

Returns:

the child element with the specified path or null if such a child element does not exist

findElement

public static XmlElement findElement(XmlElement xml,
                                     String sPath,
                                     Object oValue)

Find a child element of the specified element with the specified '/'-delimited path and the specified value. The path format is based on a subset of the XPath specification, supporting:

• Leading '/' to specify root
• Use of '/' as a path delimiter
• Use of '..' to specify parent

If multiple child elements exist that have the specified name and value, then this method returns any one of the matching elements

Parameters:

xml - an XML element

sPath - the path to follow to find the desired XML element

oValue - the value to match

Returns:

the child element with the specified path and value or null if the such a child element does not exist

ensureElement

public static XmlElement ensureElement(XmlElement xml,
                                       String sPath)

Ensure that a child element exists. If any part of the path does not exist create new child elements to match the path.

Parameters:

xml - and XmlElement

sPath - element path

Returns:

the existing or new XmlElement object

Throws:

IllegalArgumentException - if the name is null or if any part of the path is not a legal XML tag name

UnsupportedOperationException - if any element in the path is immutable or otherwise can not add a child element

See Also:

findElement(XmlElement, String)

addElements

public static void addElements(XmlElement xml,
                               Iterator iter)

Add the elements from the iterator to the passed XML.

Parameters:

xml - an XmlElement object to add to

iter - an Iterator of zero or more XmlElement objects to add

removeElement

public static int removeElement(XmlElement xml,
                                String sName)

Remove all immediate child elements with the given name

Parameters:

xml - an XmlElement

sName - child element name

Returns:

the number of removed child elements

Throws:

UnsupportedOperationException - if the element is immutable or otherwise cannot remove a child element

replaceElement

public static boolean replaceElement(XmlElement xmlParent,
                                     XmlElement xmlReplace)

Replace a child element with the same name as the specified element. If the child element does not exist the specified element is just added.

Parameters:

xmlParent - parent XmlElement

xmlReplace - element to replace with

Returns:

true if matching child element has been found and replaced; false otherwise

Throws:

UnsupportedOperationException - if the parent element is immutable or otherwise cannot remove a child element

overrideElement

public static void overrideElement(XmlElement xmlBase,
                                   XmlElement xmlOverride)

Override the values of the specified base element with values from the specified override element.

The values are only overriden if there is an exact match between the element paths and attribute values. Empty override values are ignored. Override elements that do not match any of the base elements are just copied over. No ambiguity is allowed.

For example, if the base element has more then one child with the same name and attributes then the override is not allowed.

Parameters:

xmlBase - base XmlElement

xmlOverride - override XmlElement

Throws:

UnsupportedOperationException - if the base element is immutable or there is ambiguity between the override and base elements

replaceSystemProperties

public static void replaceSystemProperties(XmlElement xml,
                                           String sPropertyAttribute)

Replace the values of the XmlElement and all its children that contain the specified attribute with the values returned by the System.getProperty() call.

This method iterates the specified XmlElement tree and for each element that contains the attribute with the specified name replaces its value with the value of the corresponding system property (if exists).

Parameters:

xml - the XmlElement to process

sPropertyAttribute - the name of the attribute that supplies the corresponding system property name

getNamespaceUri

public static String getNamespaceUri(XmlElement xml,
                                     String sPrefix)

Retrieve the Namespace URI for a given prefix in a context of the specified XmlElement.

Parameters:

xml - the XmlElement

sPrefix - the Namespace prefix

Returns:

the Namespace URI corresponding to the prefix

getNamespacePrefix

public static String getNamespacePrefix(XmlElement xml,
                                        String sUri)

Retrieve the Namespace prefix for a given URI in a context of the specified XmlElement.

Parameters:

xml - the XmlElement

sUri - the Namespace URI

Returns:

the Namespace prefix corresponding to the URI

ensureNamespace

public static void ensureNamespace(XmlElement xml,
                                   String sPrefix,
                                   String sUri)

Ensure the existence of the Namespace declaration attribute in a context of the specified XmlElement.

Parameters:

xml - the XmlElement

sPrefix - the Namespace prefix

sUri - the Namespace URI

getUniversalName

public static String getUniversalName(String sLocal,
                                      String sPrefix)

Return a universal XML element name.

Parameters:

sLocal - the local XML element name

sPrefix - the Namespace prefix

Returns:

the universal XML element name.

See Also:

XML Namespaces

isNameMatch

public static boolean isNameMatch(XmlElement xml,
                                  String sName,
                                  String sLocal,
                                  String sUri)

Check whether or not a universal (composite) name matches to the specified local name and Namespace URI.

Parameters:

xml - the (context) XmlElement

sName - the universal name

sLocal - the local xml name

sUri - the Namespace URI

Returns:

true if the specified element matches to the specified local name and the specified Namespace URI.

isElementMatch

public static boolean isElementMatch(XmlElement xml,
                                     String sLocal,
                                     String sUri)

Check whether or not an element matches to the specified local name and Namespace URI.

Parameters:

xml - the XmlElement

sLocal - the local xml name

sUri - the Namespace URI

Returns:

true if the specified element matches to the specified local name and the specified Namespace URI.

getElement

public static XmlElement getElement(XmlElement xml,
                                    String sLocal,
                                    String sUri)

Get a child element of the specified XmlElement that matches to the specified local name and the specified Namespace URI.

Parameters:

xml - the parent XmlElement

sLocal - the local xml name

sUri - the Namespace URI

Returns:

an element that matches to the specified local name and the specified Namespace URI.

getAttribute

public static XmlValue getAttribute(XmlElement xml,
                                    String sLocal,
                                    String sUri)

Get an attribute of the specified XmlElement that matches to the specified local name and the specified Namespace URI.

Parameters:

xml - the XmlElement

sLocal - the local attribute name

sUri - the Namespace URI

Returns:

an XmlValue that matches to the specified local name and the specified Namespace URI.

getElements

public static Iterator getElements(XmlElement xml,
                                   String sLocal,
                                   String sUri)

Get an iterator of child elements of the specified XmlElement that match to the specified local name and the specified Namespace URI.

Parameters:

xml - the parent XmlElement

sLocal - the local xml name

sUri - the Namespace URI

Returns:

an iterator containing all matching child elements.

purgeNamespace

public static void purgeNamespace(XmlElement xml)

For the specified XmlElement purge the Namespace declarations that are declared somewhere up the xml tree.

Parameters:

xml - the XmlElement

purgeChildrenNamespace

public static void purgeChildrenNamespace(XmlElement xml)

For the children elements of the specified XmlElement purge the repetetive Namespace declarations.

Parameters:

xml - the XmlElement

parseInitParams

public static Object[] parseInitParams(XmlElement xmlParams)

Parse the specified "init-params" element of the following structure:

 [!ELEMENT init-params (init-param*)]
 [!ELEMENT init-param ((param-name | param-type), param-value, description?)]
 

into an object array.

For the purpose of this method only the parameters that have the "param-type" element specified are processed. The following types are supported:

• string (a.k.a. java.lang.String)
• boolean (a.k.a. java.lang.Boolean)
• int (a.k.a. java.lang.Integer)
• long (a.k.a. java.lang.Long)
• double (a.k.a. java.lang.Double)
• decimal (a.k.a. java.math.BigDecimal)
• file (a.k.a. java.io.File)
• date (a.k.a. java.sql.Date)
• time (a.k.a. java.sql.Time)
• datetime (a.k.a. java.sql.Timestamp)
• xml (a.k.a. com.tangosol.run.xml.XmlElement)

For any other [explicitly specified] types the corresponding "init-param" XmlElement itself is placed into the returned array.

Parameters:

xmlParams - the "init-params" XmlElement to parse

Returns:

an array of parameters

parseInitParams

public static Object[] parseInitParams(XmlElement xmlParams,
                                       XmlHelper.ParameterResolver resolver)

Parse the specified "init-params" element of the following structure:

 [!ELEMENT init-params (init-param*)]
 [!ELEMENT init-param ((param-name | param-type), param-value, description?)]
 

into an object array.

For the purpose of this method only the parameters that have the "param-type" element specified are processed. The following types are supported:

• string (a.k.a. java.lang.String)
• boolean (a.k.a. java.lang.Boolean)
• int (a.k.a. java.lang.Integer)
• long (a.k.a. java.lang.Long)
• double (a.k.a. java.lang.Double)
• decimal (a.k.a. java.math.BigDecimal)
• file (a.k.a. java.io.File)
• date (a.k.a. java.sql.Date)
• time (a.k.a. java.sql.Time)
• datetime (a.k.a. java.sql.Timestamp)
• xml (a.k.a. com.tangosol.run.xml.XmlElement)

For any other [explicitly specified] types the corresponding "init-param" XmlElement itself is placed into the returned array.

Parameters:

xmlParams - the "init-params" XmlElement to parse

resolver - an optional ParameterResolver

Returns:

an array of parameters

transformInitParams

public static void transformInitParams(XmlElement xmlParent,
                                       XmlElement xmlParams)

Transform the specified "init-params" element of the following structure:

 [!ELEMENT init-params (init-param*)]
 [!ELEMENT init-param ((param-name | param-type), param-value, description?)]
 

into an XML element composed of the corrsponding names. For example, the the "init-params" element of the following structure:

   <init-param>
      <param-name>NameOne</param-name>
      <param-value>ValueOne</param-value>
   </init-param>
   <init-param>
      <param-name>NameTwo</param-name>
      <param-value>ValueTwo</param-value>
   </init-param>
 

will transform into

   <NameOne>ValueOne</NameOne>
   <NameTwo>ValueTwo</NameTwo>
 

For the purpose of this method only the parameters that have the "param-name" element specified are processed.

Parameters:

xmlParent - the XML element to insert the transformed elements into

xmlParams - the "init-params" XmlElement to parse

hashElement

public static int hashElement(XmlElement xml)

Provide a hash value for the XML element and all of its contained information. The hash value is defined as a xor of the following:

• the hashCode from the element's value (i.e. super.hashCode())
• the hashCode from each attribute name
• the hashCode from each attribute value
• the hashCode from each sub-element

Parameters:

xml - the XML element

Returns:

the hash value for the XML element

hashValue

public static int hashValue(XmlValue val)

Provide a hash value for the XML value. The hash value is defined as one of the following:

1. 0 if getValue() returns null
2. otherwise the hash value is the hashCode() of the string representation of the value

Parameters:

val - the XML value

Returns:

the hash value for the XML value

equalsElement

public static boolean equalsElement(XmlElement xml1,
                                    XmlElement xml2)

Compare one XML element with another XML element for equality.

Parameters:

xml1 - a non-null XmlElement object

xml2 - a non-null XmlElement object

Returns:

true if the elements are equal, false otherwise

equalsValue

public static boolean equalsValue(XmlValue val1,
                                  XmlValue val2)

Compare one XML value with another XML value for equality.

Parameters:

val1 - a non-null XmlValue object

val2 - a non-null XmlValue object

Returns:

true if the values are equal, false otherwise

toString

public static String toString(XmlSerializable xml)

Return the XML of an XmlSerializable object as a String.

Parameters:

xml - an object that can serialize itself into XML

Returns:

a String description of the object

convert

public static Object convert(Object o,
                             int nType)

Convert the passed Object to the specified type.

Parameters:

o - the object value or null

nType - the enumerated type to convert to

Returns:

an object of the specified type