com.ail.core
Class XMLString

java.lang.Object
  com.ail.core.XMLString

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public class XMLString
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

This class is designed to do most of the kinds of jobs you are likely to need to do with a string of XML. It doesn't attempt to be a complete replacement for using javax.xml directly, it just takes some of the pain out of the most common usages.

Version:

$Revision: 1.5 $

See Also:

Serialized Form

Constructor Summary

XMLString(java.io.File file)
Constructor that builds an XMLString based the contents of the specified file.

XMLString(java.io.InputStream inputStream)
Constructor that builds an XMLString based the docuemnt read from the specified input stream.

XMLString(java.lang.String string)
Constructor that builds an XMLString based upon the specified String.

XMLString(java.net.URL url)
Constructor that builds an XMLString based the contents of the document pointed to by a URL.

Method Summary

java.lang.Object	clone() Clone this XMLString object.
boolean	equals(java.lang.String xml)
boolean	equals(XMLString xml)
java.lang.String	eval(java.lang.String xpath) Apply the specified xpath expression to the current XMLString.
java.lang.String	eval(XMLString xpath) Apply the specified xpath expression to the current XMLString.
java.lang.String	evalCommand(java.lang.String xpath) Apply the specified xpath expression to the current XMLString.
java.lang.String	evalCommand(XMLString xpath) Apply the specified xpath expression to the current XMLString.
void	evalInline(java.lang.String xpath) Apply the specified xpath expression to the current XMLString, and replace the current contents of the XMLString with the result.
void	evalInline(XMLString xpath) Apply the specified xpath expression to the current XMLString, and replace the current contents of the XMLString with the result.
java.lang.String	evalToText(java.lang.String xpath) Evaluate an xpath expression to a text value.
java.lang.String	evalToText(XMLString xpath) Evaluate an xpath expression to a text value.
java.lang.Class	getType() Determine the type represented by the xmlString.
org.w3c.dom.Document	getXmlDocument() Return the Document object representing this XMLString.
java.lang.String	getXsiType() Fetch the root elements xsi:type value if there is one, or null if none is present.
void	setXMLString(java.io.File file) Replace the current XMLString with the contents of the specified file.
void	setXMLString(java.io.InputStream inputStream) Replace the current XMLString with the contents of the document read from the specified input stream.
void	setXMLString(java.lang.String string) Replace the current XMLString with the string specified.
void	setXMLString(java.lang.StringBuffer sb) Replace the current XMLString with the string specified.
void	setXMLString(java.net.URL url) Replace the current XMLString with the contents of the document loaded for the specified URL.
java.lang.String	toString() Return the current XML document as a string
java.lang.String	toStringWithEntityReferences(boolean excludeBraces) Similar to toString() but with entity references expanded.
java.lang.String	toStringWithoutEntityReferences() This method does the reverse of toStringWithEntityReferences(boolean).
java.lang.String	transform(java.lang.String source) Apply the specified XSLT to the contents of this XMLString.
java.lang.String	transform(XMLString source) Apply the specified XSLT to the contents of this XMLString.
void	transformInline(java.lang.String source) Apply the specified XSLT to the contents of this XMLString, and replace the XMLString with the result of the transformation.
void	transformInline(XMLString source) Apply the specified XSLT to the contents of this XMLString, and replace the XMLString with the result of the transformation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XMLString

public XMLString(java.lang.String string)

Constructor that builds an XMLString based upon the specified String.

Parameters:

string - String in XML format

XMLString

public XMLString(java.net.URL url)
          throws java.io.IOException

Constructor that builds an XMLString based the contents of the document pointed to by a URL.

Parameters:

url - URL to read document from.

Throws:

java.io.IOException - if the URL cannot be read.

XMLString

public XMLString(java.io.File file)
          throws java.io.FileNotFoundException,
                 java.io.IOException

Constructor that builds an XMLString based the contents of the specified file.

Parameters:

file - The file to read document from.

Throws:

java.io.FileNotFoundException - if the specified file cannot be found.

java.io.IOException - if the file cannot be read.

XMLString

public XMLString(java.io.InputStream inputStream)
          throws java.io.IOException

Constructor that builds an XMLString based the docuemnt read from the specified input stream.

Parameters:

inputStream - Stream to read document from.

Throws:

java.io.IOException - if the input stream cannot be read.

Method Detail

getXmlDocument

public org.w3c.dom.Document getXmlDocument()
                                    throws org.xml.sax.SAXException

Return the Document object representing this XMLString. The value returned is a copy, changes made to it will not appear in the String and changes to the String will not appear in the Document.

Returns:

The Document object.

Throws:

org.xml.sax.SAXException

setXMLString

public void setXMLString(java.lang.StringBuffer sb)

Replace the current XMLString with the string specified.

Parameters:

string - String to replace the current string.

setXMLString

public void setXMLString(java.lang.String string)

Replace the current XMLString with the string specified.

Parameters:

string - String to replace the current string.

setXMLString

public void setXMLString(java.net.URL url)
                  throws java.io.IOException

Replace the current XMLString with the contents of the document loaded for the specified URL.

Parameters:

url - URL to load XMLString from.

Throws:

java.io.IOException - If the URL cannot be read.

setXMLString

public void setXMLString(java.io.File file)
                  throws java.io.FileNotFoundException,
                         java.io.IOException

Replace the current XMLString with the contents of the specified file.

Parameters:

file - File to read new string from.

Throws:

java.io.FileNotFoundException - If file cannot be opened.

java.io.IOException - If an error occurs while reading the file.

setXMLString

public void setXMLString(java.io.InputStream inputStream)
                  throws java.io.IOException

Replace the current XMLString with the contents of the document read from the specified input stream.

Parameters:

inputStream - Stream to read the new document from.

Throws:

java.io.IOException - If an error occurs while reading from the stream.

toString

public java.lang.String toString()

Return the current XML document as a string

Overrides:

toString in class java.lang.Object

Returns:

The current document.

transform

public java.lang.String transform(java.lang.String source)
                           throws javax.xml.transform.TransformerException

Apply the specified XSLT to the contents of this XMLString.

Parameters:

source - A string representing the XSLT to apply.

Returns:

The result of the transformation.

Throws:

javax.xml.transform.TransformerException - If an error occurs during transformation.

transform

public java.lang.String transform(XMLString source)
                           throws javax.xml.transform.TransformerException

Apply the specified XSLT to the contents of this XMLString.

Parameters:

source - An XMLString representing the XSLT to apply.

Returns:

The result of the transformation.

Throws:

javax.xml.transform.TransformerException - If an error occurs during transformation.

transformInline

public void transformInline(java.lang.String source)
                     throws javax.xml.transform.TransformerException

Apply the specified XSLT to the contents of this XMLString, and replace the XMLString with the result of the transformation.

Parameters:

source - A string representing the XSLT to apply.

Throws:

javax.xml.transform.TransformerException - If an error occurs during transformation.

transformInline

public void transformInline(XMLString source)
                     throws javax.xml.transform.TransformerException

Apply the specified XSLT to the contents of this XMLString, and replace the XMLString with the result of the transformation.

Parameters:

source - An XMLString representing the XSLT to apply.

Throws:

javax.xml.transform.TransformerException - If an error occurs during transformation.

eval

public java.lang.String eval(java.lang.String xpath)
                      throws org.xml.sax.SAXException,
                             javax.xml.transform.TransformerException

Apply the specified xpath expression to the current XMLString.

Parameters:

xpath - The query.

Returns:

The result of the query.

Throws:

org.xml.sax.SAXException

javax.xml.transform.TransformerException

eval

public java.lang.String eval(XMLString xpath)
                      throws org.xml.sax.SAXException,
                             javax.xml.transform.TransformerException

Apply the specified xpath expression to the current XMLString.

Parameters:

xpath - XMLString representing the query

Returns:

The result of the query.

Throws:

org.xml.sax.SAXException

javax.xml.transform.TransformerException

evalCommand

public java.lang.String evalCommand(java.lang.String xpath)
                             throws org.xml.sax.SAXException,
                                    javax.xml.transform.TransformerException

Apply the specified xpath expression to the current XMLString. The expression may include xpath commands (e.g. count()). This method is likely to be slower than eval(String) or eval(XMLString) but supports commands - which the other methods do not.

Parameters:

xpath - The query.

Returns:

The result of the query.

Throws:

org.xml.sax.SAXException

javax.xml.transform.TransformerException

evalCommand

public java.lang.String evalCommand(XMLString xpath)
                             throws org.xml.sax.SAXException,
                                    javax.xml.transform.TransformerException

Apply the specified xpath expression to the current XMLString. The expression may include xpath commands (e.g. count()). This method is likely to be slower than eval(String) or eval(XMLString) but supports commands - which the other methods do not.

Parameters:

xpath - XMLString representing the query

Returns:

The result of the query.

Throws:

org.xml.sax.SAXException

javax.xml.transform.TransformerException

evalToText

public java.lang.String evalToText(java.lang.String xpath)
                            throws org.xml.sax.SAXException,
                                   javax.xml.transform.TransformerException

Evaluate an xpath expression to a text value. If the xpath specified points to an attribute this method will return the value of that attribute, if it points to an element then the element is assumed to be a text element an its value is returned.

Parameters:

xpath - The xpath expression

Returns:

The value of the text element or attribute.

Throws:

org.xml.sax.SAXException

javax.xml.transform.TransformerException

See Also:

evalToText(com.ail.core.XMLString)

evalToText

public java.lang.String evalToText(XMLString xpath)
                            throws org.xml.sax.SAXException,
                                   javax.xml.transform.TransformerException

Evaluate an xpath expression to a text value. In addition to processing normal xpath expressions, this method has handles two special cases to simplify xpath use.

Firstly, if the xpath specified points to an attribute this method will return the value of that attribute, if it points to an element then the element is assumed to be a text element an its value is returned.

For example, an xpath expression of /policy/policy-holder/@forname this method would return the value of the forname attribute (as eval() would), but given the xpath /policy/policy-number it would actually evaulate /policy/policy-number/text() returning the text of the element.

Secondly, this method has special handling for multi-node matches, consider the following xml source doc:

<doc>
<person forename="fred" surname="clucknasty"/>
<person forename="wilma" surname="clucknasty"/>
</doc>

An xpath expression to get both of the forename nodes like this:

/doc/person/@forename

would return 'fredwilma' - which isn't especially useful. This method offers special handling, which allows the following xpath expression:

/doc/person[]/@forname

to return the string 'fred|wilma'.

Parameters:

xpath - The xpath expression

Returns:

The value of the text element or attribute.

Throws:

org.xml.sax.SAXException

javax.xml.transform.TransformerException

evalInline

public void evalInline(java.lang.String xpath)
                throws org.xml.sax.SAXException,
                       javax.xml.transform.TransformerException

Apply the specified xpath expression to the current XMLString, and replace the current contents of the XMLString with the result.

Parameters:

xpath - A string representing the query to apply.

Throws:

org.xml.sax.SAXException

javax.xml.transform.TransformerException

evalInline

public void evalInline(XMLString xpath)
                throws org.xml.sax.SAXException,
                       javax.xml.transform.TransformerException

Apply the specified xpath expression to the current XMLString, and replace the current contents of the XMLString with the result.

Parameters:

xpath - An XMLString representing the query to apply.

Throws:

org.xml.sax.SAXException

javax.xml.transform.TransformerException

equals

public boolean equals(java.lang.String xml)

getXsiType

public java.lang.String getXsiType()

Fetch the root elements xsi:type value if there is one, or null if none is present. Note: This method assumes that the namespace being used is "xsi".

Returns:

The value of xsi:type, without the java: prefix.

getType

public java.lang.Class getType()
                        throws java.lang.ClassNotFoundException

Determine the type represented by the xmlString. This assumes that the type can be determined by an xsi:type attribute on the root element.

Returns:

the Class represented by the string, or null.

Throws:

java.lang.ClassNotFoundException

equals

public boolean equals(XMLString xml)

clone

public java.lang.Object clone()

Clone this XMLString object.

Overrides:

clone in class java.lang.Object

Returns:

A clone of this object, or null if the cloning process fails.

toStringWithEntityReferences

public java.lang.String toStringWithEntityReferences(boolean excludeBraces)

Similar to toString() but with entity references expanded. This simply means that any characters in the XMLString which have corresponding entity references will be replaced with them; so if the string contains "<name>Johnson's<name>" this method will return "<name>Johnson&apos;s<name>"

Parameters:

excludeBraces - If false "<" & ">" are replaced with "&lt;" and "&gt;"; otherwise they are left as is.

Returns:

The value of this XMLString with references expanded.

toStringWithoutEntityReferences

public java.lang.String toStringWithoutEntityReferences()

This method does the reverse of toStringWithEntityReferences(boolean).

Returns:

Content of the string with entity references replaced with their literal values.