org.vizzini.util.xml
Class XMLUtilities

java.lang.Object
  extended by org.vizzini.util.xml.XMLUtilities

public class XMLUtilities
extends Object

Provides convenience methods for XML document handling.

Since:
v0.3
Version:
v0.3
Author:
Jeffrey M. Thompson

Nested Class Summary
(package private)  class XMLUtilities.XMLErrorHandler
          Provides an error handler for parsing an XML string.
 
Field Summary
static String XML_HEADER
          XML header.
 
Method Summary
protected  void appendAttributes(StringBuffer sb, Node node)
          Append the node's attributes.
protected  boolean appendCommentNode(StringBuffer sb, Comment commentNode, boolean convertSpecialContent)
          Append the comment node.
protected  boolean appendTextNode(StringBuffer sb, Text textNode, boolean convertSpecialContent)
          Append the text node.
 String convertAttributesToString(NamedNodeMap attributes)
          Append the node's attributes.
 String convertSpecialContent(String data)
          Convert special contents into the HTML/XML equivalent entity reference.
 String convertToHTML(Node parent)
           
 String convertToString(Node parent)
           
 String convertToString(Node parent, boolean isFormatted, boolean convertSpecialContent)
           
protected  boolean convertToStringProcessNode(StringBuffer sb, Node parent, boolean isFormatted, boolean convertSpecialContent, int level)
          Process the given node in the asString() flow.
 String createNamespacePredicate(String namespace, String nodeName)
           
 String format(String tagName, boolean value)
          Format the given XML tag and value.
 String format(String tagName, Date value)
          Format the given XML tag and value.
 String format(String tagName, double value)
          Format the given XML tag and value.
 String format(String tagName, double value, int numDigits)
          Format the given XML tag and value.
 String format(String tagName, int value)
          Format the given XML tag and value.
 String format(String tagName, String value)
          Format the given XML tag and value.
 String formatDate(Calendar calendar)
           
 String formatDate(Date date)
           
 String formatDate(int year, int month, int day)
           
 String formatDecimal(double number, int numDigits)
          Round the given number to the desired number of digits to the right of the decimal point.
 Attr getAttribute(Node node, String attributeName)
          Return the attribute of the given name at the given path location below the given node.
 Attr getAttribute(Node parent, String path, String attributeName)
          Return the attribute of the given name at the given path location below the given node.
 String getAttributeValue(Node node, String attributeName)
          Return the value of the attribute of the given name at the given path location below the given node.
 String getAttributeValue(Node parent, String path, String attributeName)
          Return the value of the attribute of the given name at the given path location below the given node.
 Node getFirstChildNamed(Node parent, String name)
          Return the first child with the given tag name.
static XMLUtilities getInstance()
          Return the singleton instance.
 Node getNode(Node parent, String path)
          Return the node at the given path location below the given node.
 NodeList getNodeList(Node parent, String path)
          Return the nodes at the given path location below the given node.
 String getNodeValue(Node parent, String path)
          Return the value of the node at the given path location below the given parent.
 Date parseDate(String value)
          Return a Date parsed from the given XML formatted string.
 Document parseDocument(File file)
          Return a validated and parsed XML document from the given file.
 Document parseDocument(File file, boolean isNamespaceAware, boolean isValidating)
          Return an XML document from the given file.
 Document parseDocument(Reader reader)
          Return a validated and parsed XML document from the given reader.
 Document parseDocument(Reader reader, boolean isNamespaceAware, boolean isValidating)
          Return an XML document from the given reader.
 Document parseDocument(String xml)
          Return a validated and parsed XML document from the given reader.
 Document parseDocument(String xml, boolean isNamespaceAware, boolean isValidating)
          Return an XML document from the given reader.
protected  void prepareNextLine(StringBuffer sb, int level)
          Prepare the next line of the formatted XML string.
 void setNodeValue(Node parent, String path, String value)
          Set the value of the first node at the given path location below the given node.
 void setNodeValue(Node parent, String path, String value, boolean convertSpecialContent)
          Set the value of the first node at the given path location below the given node.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

XML_HEADER

public static final String XML_HEADER
XML header.

See Also:
Constant Field Values
Method Detail

getInstance

public static XMLUtilities getInstance()
Return the singleton instance.

Since:
v0.3

convertAttributesToString

public String convertAttributesToString(NamedNodeMap attributes)
Append the node's attributes.

Parameters:
attributes - Attributes to convert.
Returns:
string representation of a nodes attributes
Since:
v0.3

convertSpecialContent

public String convertSpecialContent(String data)
Convert special contents into the HTML/XML equivalent entity reference.

Parameters:
data - the data to encode
Returns:
encoded special XML characters
Since:
v0.3

convertToHTML

public String convertToHTML(Node parent)
Parameters:
parent - Parent node (or document).
Returns:
an HTML representation of the given node. This method formats, then converts brackets, newlines, spaces, and ampersands to their HTML equivalents.
Since:
v0.3

convertToString

public String convertToString(Node parent)
Parameters:
parent - Parent node (or document).
Returns:
a string representation of the given node. This method does not format, and does convert brackets to their HTML equivalents.

convertToString

public String convertToString(Node parent,
                              boolean isFormatted,
                              boolean convertSpecialContent)
Parameters:
parent - Parent node (or document).
isFormatted - Flag indicating if the return string should be formatted.
convertSpecialContent - Flag indicating whether special content (&,',&aquot;,<,>) in Comment nodes should be converted to HTML.
Returns:
a string representation of the given node.
Since:
v0.3

createNamespacePredicate

public String createNamespacePredicate(String namespace,
                                       String nodeName)
Parameters:
namespace - Namespace string.
nodeName - A node name.
Returns:
the namespace predicate for the given parameters.
Since:
v0.3

format

public String format(String tagName,
                     int value)
Format the given XML tag and value.

Parameters:
tagName - Tag name.
value - Node value.
Returns:
a formatted XML node as a string.
Since:
v0.3

format

public String format(String tagName,
                     double value)
Format the given XML tag and value.

Parameters:
tagName - Tag name.
value - Node value.
Returns:
a formatted XML node as a string.
Since:
v0.3

format

public String format(String tagName,
                     boolean value)
Format the given XML tag and value.

Parameters:
tagName - Tag name.
value - Node value.
Returns:
a formatted XML node as a string.
Since:
v0.3

format

public String format(String tagName,
                     String value)
Format the given XML tag and value.

Parameters:
tagName - Tag name.
value - Node value.
Returns:
a formatted XML node as a string.
Since:
v0.3

format

public String format(String tagName,
                     Date value)
Format the given XML tag and value.

Parameters:
tagName - Tag name.
value - Value.
Returns:
a formatted XML node as a string.
Since:
v0.3

format

public String format(String tagName,
                     double value,
                     int numDigits)
Format the given XML tag and value.

Parameters:
tagName - Tag name.
value - Node value.
numDigits -
Returns:
a formatted XML node as a string.
Since:
v0.3

formatDate

public String formatDate(Date date)
Parameters:
date - Date object, typically representing now.
Returns:
a properly formatted XML date string.
Since:
v0.3

formatDate

public String formatDate(Calendar calendar)
Parameters:
calendar - Calendar object, typically representing now.
Returns:
a properly formatted XML date string.
Since:
v0.3

formatDate

public String formatDate(int year,
                         int month,
                         int day)
Parameters:
year - Four digit year.
month - Month number in [1,12].
day - Day of month in [1,28],[1,30] or [1,31] depending on the month.
Returns:
a properly formatted XML date string.
Since:
v0.3

formatDecimal

public String formatDecimal(double number,
                            int numDigits)
Round the given number to the desired number of digits to the right of the decimal point.

Parameters:
number - Number to be formatted.
numDigits - Number of digits in the fraction portion of a number (zero or more).
Returns:
a string representation of the given number.
Since:
v0.3

getAttribute

public Attr getAttribute(Node node,
                         String attributeName)
Return the attribute of the given name at the given path location below the given node. For example, the call
getNode( node, "TransactionType")
returns the node's transaction type attribute.

Parameters:
node - Node (or document).
attributeName - Attribute name.
Returns:
the requested attribute, or null if none was found.
Since:
v0.3

getAttribute

public Attr getAttribute(Node parent,
                         String path,
                         String attributeName)
Return the attribute of the given name at the given path location below the given node. For example, the call
getNode( parent, "/Response/Transaction", "TransactionType")
returns the transaction node's transaction type attribute.

Parameters:
parent - Parent node (or document).
path - Path to the node of interest; separator is /.
attributeName - Attribute name.
Returns:
the requested attribute, or null if none was found.
Since:
v0.3

getAttributeValue

public String getAttributeValue(Node node,
                                String attributeName)
Return the value of the attribute of the given name at the given path location below the given node. For example, the call
getNode( node, "TransactionType")
returns the node's transaction type attribute.

Parameters:
node - Node (or document).
attributeName - Attribute name.
Returns:
the requested attribute value, or null if none was found.
Since:
v0.3

getAttributeValue

public String getAttributeValue(Node parent,
                                String path,
                                String attributeName)
Return the value of the attribute of the given name at the given path location below the given node. For example, the call
getNode( parent, "/Response/Transaction", "TransactionType")
returns the transaction node's transaction type attribute.

Parameters:
parent - Parent node (or document).
path - Path to the node of interest; separator is /.
attributeName - Attribute name.
Returns:
the requested attribute value, or null if none was found.
Since:
v0.3

getFirstChildNamed

public Node getFirstChildNamed(Node parent,
                               String name)
Return the first child with the given tag name.

Parameters:
parent - Parent node (or document).
name - Tag name of the node of interest.
Returns:
the requested node, or null if none was found.
Since:
v0.3

getNode

public Node getNode(Node parent,
                    String path)
Return the node at the given path location below the given node. For example, the call
getNode( parent, "/Response/Transaction")
returns the transaction node.

Parameters:
parent - Parent node (or document).
path - XPath to the node of interest.
Returns:
the requested node, or null if none was found.
Since:
v0.3

getNodeList

public NodeList getNodeList(Node parent,
                            String path)
Return the nodes at the given path location below the given node. For example, the call
getNodeList( parent, "./Response/Transaction")
returns the transaction nodes.

Parameters:
parent - Parent node (or document).
path - XPath to the node of interest.
Returns:
the requested node, or null if none was found.
Since:
v0.3

getNodeValue

public String getNodeValue(Node parent,
                           String path)
Return the value of the node at the given path location below the given parent. For example, the call
getNodeValue( parent, "/Response/Transaction")
returns the content of the transaction node.

Parameters:
parent - Parent node (or document).
path - Path relative to the parent to the node of interest; separator is /.
Returns:
the content of the requested node, or null if none was found or the node was not a leaf node. An empty node causes an empty string return value.
Since:
v0.3

parseDate

public Date parseDate(String value)
               throws ParseException
Return a Date parsed from the given XML formatted string.

Parameters:
value -
Returns:
the date.
Throws:
ParseException
Since:
v0.3

parseDocument

public Document parseDocument(String xml)
                       throws ParserConfigurationException,
                              IOException,
                              SAXException
Return a validated and parsed XML document from the given reader. Overloading is safe because String, File, and Reader do not extend a class common to all.

Parameters:
xml - XML source string.
Returns:
the XML document.
Throws:
MalformedXMLException
InvalidXMLException
ParserConfigurationException
IOException
SAXException
Since:
v0.3

parseDocument

public Document parseDocument(File file)
                       throws ParserConfigurationException,
                              IOException,
                              SAXException
Return a validated and parsed XML document from the given file. Overloading is safe because String, File, and Reader do not extend a class common to all.

Parameters:
file - XML source file.
Returns:
the XML document.
Throws:
MalformedXMLException
InvalidXMLException
ParserConfigurationException
IOException
SAXException
Since:
v0.3

parseDocument

public Document parseDocument(Reader reader)
                       throws ParserConfigurationException,
                              IOException,
                              SAXException
Return a validated and parsed XML document from the given reader. Overloading is safe because String, File, and Reader do not extend a class common to all.

Parameters:
reader - Reader.
Returns:
the XML document.
Throws:
MalformedXMLException
InvalidXMLException
ParserConfigurationException
IOException
SAXException
Since:
v0.3

parseDocument

public Document parseDocument(String xml,
                              boolean isNamespaceAware,
                              boolean isValidating)
                       throws ParserConfigurationException,
                              IOException,
                              SAXException
Return an XML document from the given reader. Overloading is safe because String, File, and Reader do not extend a class common to all.

Parameters:
xml - XML source string.
isNamespaceAware - Flag indicating if the parser is namespace aware.
isValidating - Flag indicating if the parser should validate.
Returns:
the XML document.
Throws:
MalformedXMLException
InvalidXMLException
ParserConfigurationException
IOException
SAXException
Since:
v0.3

parseDocument

public Document parseDocument(File file,
                              boolean isNamespaceAware,
                              boolean isValidating)
                       throws ParserConfigurationException,
                              IOException,
                              SAXException
Return an XML document from the given file. Overloading is safe because String, File, and Reader do not extend a class common to all.

Parameters:
file - XML source file.
isNamespaceAware - Flag indicating if the parser is namespace aware.
isValidating - Flag indicating if the parser should validate.
Returns:
the XML document.
Throws:
MalformedXMLException
InvalidXMLException
ParserConfigurationException
IOException
SAXException
Since:
v0.3

parseDocument

public Document parseDocument(Reader reader,
                              boolean isNamespaceAware,
                              boolean isValidating)
                       throws ParserConfigurationException,
                              IOException,
                              SAXException
Return an XML document from the given reader. Overloading is safe because String, File, and Reader do not extend a class common to all.

Parameters:
reader - Reader.
isNamespaceAware - Flag indicating if the parser is namespace aware.
isValidating - Flag indicating if the parser should validate.
Returns:
the XML document.
Throws:
MalformedXMLException
InvalidXMLException
ParserConfigurationException
IOException
SAXException
Since:
v0.3

setNodeValue

public void setNodeValue(Node parent,
                         String path,
                         String value)
Set the value of the first node at the given path location below the given node. For example, the call
setNodeValue( parent, "/root/data", "new data")
sets the value of the data node to "new data".
This method converts brackets to their HTML equivalents.

Parameters:
parent - Parent node.
path - Path relative to the parent to the node of interest; separator is /.
value - Value to set.
Since:
v0.3

setNodeValue

public void setNodeValue(Node parent,
                         String path,
                         String value,
                         boolean convertSpecialContent)
Set the value of the first node at the given path location below the given node. For example, the call
setNodeValue( parent, "/root/data", "new data", false)
sets the value of the data node to "new data".

Parameters:
parent - Parent node.
path - Path relative to the parent to the node of interest; separator is /.
value - Value to set.
convertSpecialContent - Flag indicating whether special content (&,',&aquot;,<,>) in Comment nodes should be converted to HTML.
Since:
v0.3

appendAttributes

protected void appendAttributes(StringBuffer sb,
                                Node node)
Append the node's attributes.

Parameters:
sb - String buffer which holds the string being built.
node - Node being processed.
Since:
v0.3

appendCommentNode

protected boolean appendCommentNode(StringBuffer sb,
                                    Comment commentNode,
                                    boolean convertSpecialContent)
Append the comment node.

Parameters:
sb - String buffer which holds the string being built.
commentNode - Comment node to append.
convertSpecialContent - Flag indicating whether special content (&,',&aquot;,<,>) in Comment nodes should be converted to HTML.
Returns:
true if the data appended as a text node
Since:
v0.3

appendTextNode

protected boolean appendTextNode(StringBuffer sb,
                                 Text textNode,
                                 boolean convertSpecialContent)
Append the text node.

Parameters:
sb - String buffer which holds the string being built.
textNode - Text node to append.
convertSpecialContent - Flag indicating whether special content (&,',&aquot;,<,>) in Comment nodes should be converted to HTML.
Returns:
true if the data appended as a text node
Since:
v0.3

convertToStringProcessNode

protected boolean convertToStringProcessNode(StringBuffer sb,
                                             Node parent,
                                             boolean isFormatted,
                                             boolean convertSpecialContent,
                                             int level)
Process the given node in the asString() flow.

Parameters:
sb - String buffer which holds the string being built.
parent - Parent node being processed.
isFormatted - Flag indicating if the return string should be formatted.
convertSpecialContent - Flag indicating whether special content (&,',&aquot;,<,>) in Comment nodes should be converted to HTML.
level - Level in the node hierarchy.
Returns:
true if the data appended as a text node
Since:
v0.3

prepareNextLine

protected void prepareNextLine(StringBuffer sb,
                               int level)
Prepare the next line of the formatted XML string.

Parameters:
sb - String buffer which holds the string being built.
level - Level in the node hierarchy.
Since:
v0.3


Copyright 2007 Vizzini.org. All Rights Reserved. 2007.12.25.03.00.02