DLESE Tools
v1.6.0

org.dlese.dpc.xml
Class Dom4jUtils

java.lang.Object
  extended by org.dlese.dpc.xml.Dom4jUtils

public class Dom4jUtils
extends Object

Utility methods for working with dom4j Documents.

Version:
$Id: Dom4jUtils.java,v 1.17 2010/07/14 22:41:16 jweather Exp $
Author:
John Weatherley


Constructor Summary
Dom4jUtils()
           
 
Method Summary
static String delocalizeDocStr(String s, String rootElementName, String nameSpaceInfo)
          Insert nameSpaceInformation into the root element to make validation possible.
static Document delocalizeXml(Document doc, String rootElementName, String nameSpaceInfo)
          Insert nameSpaceInformation into the root element
static Object dom4j2JavaBean(Node javaObjectXmlNode)
          Takes a dom4j Node that contains an XML serialized JavaBean and returns a JavaBean Object.
protected static String getDateStamp()
          Return a string for the current time and date, sutiable for display in log files and output to standout:
static Transformer getLocalizingTransformer()
          Gets the localizingTransformer attribute of the Dom4jUtils class
static String getNameSpaceInfo(Document doc, String rootElementName)
          Gets the nameSpaceInfo associated with the root element of a Document.
static Document getXmlDocument(File file)
          Load an XML file into a dom4j Document.
static Document getXmlDocument(File file, String encoding)
          Load an XML file into a dom4j Document using the given character encoding.
static Document getXmlDocument(String s)
          Load XML into a dom4j Document.
static Document getXmlDocument(String url, int timoutMs)
          Load XML into a dom4j Document, specifying a max time to wait for resopnse.
static Document getXmlDocument(URL url)
          Load XML into a dom4j Document.
static Document getXmlDocument(URL url, int timoutMs)
          Load XML into a dom4j Document, specifying a max time to wait for resopnse.
static Document getXmlDocumentLocalized(String xml)
          Load XML into a dom4j Document and localize the XML by removing all namespaces from it.
static Document getXmlDocumentPostData(URL url, String postData, int timoutMs)
          Post data to a URL and load the response XML into a dom4j Document, specifying a max time to wait for resopnse.
static XMLWriter getXMLWriter()
          Gets an XMLWriter object
static boolean isEmpty(Element e)
          Gets the empty attribute of the Dom4jUtils class
static boolean isEmpty(Element e, boolean ignoreWhiteSpace)
          isEmpty returns true if neither the element, or any children recursively, have textual content or have a non-empty attribute.
static Document localizeXml(Document doc)
          Localizes a Dom4j Document by removing all namespaces from it.
static Document localizeXml(Document doc, String rootElementName)
          Remove nameSpaceInformation from the root element (as well as any attributes!) to facilitate xpath access
static Element localizeXml(Element element)
          Localizes a Dom4j Element by removing all namespaces from it.
static Document localizeXml(Node node)
          Localizes a Dom4j Node, Document, Branch or Element by removing all namespaces from it, returning a Document.
static String localizeXml(String xml)
          Localizes an XML String by removing all namespaces from it.
static String localizeXml(String xml, String elementName)
          Strips all attributes (including namespace information) from a particular element within a string representation of an XML element (having arbitrary content and subelements), then removes all namespace prefixes throughout the xml using a trnasformer.
 void log(String msg)
          Logger hook
static String prettyPrint(Node node)
          Formats an Node as a printable string
protected static void prtln(String s)
          Output a line of text to standard out, with datestamp, if debug is set to true.
protected static void prtlnErr(String s)
          Output a line of text to error out, with datestamp.
static void setDebug(boolean db)
          Sets the debug attribute of the object
static void writeDocToFile(Document doc, File out)
          Writes Document to File
static void writeDocToFile(Document doc, File out, OutputFormat format)
          Write XML Document to disk using specified OutputFormat
static void writePrettyDocToFile(Document doc, File out)
          write formated xml to file to faciliate human-readibility
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Dom4jUtils

public Dom4jUtils()
Method Detail

getXmlDocument

public static Document getXmlDocument(File file)
                               throws DocumentException,
                                      MalformedURLException
Load an XML file into a dom4j Document. If error, return null. No validation is performed.

Parameters:
file - An XML file
Returns:
An XML Document containing the dom4j DOM, or null if unable to process the file.
Throws:
DocumentException - If dom4j error
MalformedURLException - If error in file name

getXmlDocument

public static Document getXmlDocument(File file,
                                      String encoding)
                               throws DocumentException,
                                      MalformedURLException,
                                      IOException
Load an XML file into a dom4j Document using the given character encoding. If error, return null. No validation is performed.

Parameters:
file - An XML file
encoding - The character encoding to use, for example 'UTF-8'
Returns:
An XML Document containing the dom4j DOM, or null if unable to process the file.
Throws:
DocumentException - If dom4j error
MalformedURLException - If error in file name
IOException - If IO error

getXmlDocument

public static Document getXmlDocument(URL url)
                               throws DocumentException,
                                      MalformedURLException
Load XML into a dom4j Document. If error, return null. No validation is performed.

Parameters:
url - A URL to an XML document
Returns:
An XML Document containing the dom4j DOM, or null if unable to process the file.
Throws:
DocumentException - If dom4j error
MalformedURLException - If error in the URL

getXmlDocument

public static Document getXmlDocument(URL url,
                                      int timoutMs)
                               throws DocumentException,
                                      MalformedURLException,
                                      IOException,
                                      URLConnectionTimedOutException
Load XML into a dom4j Document, specifying a max time to wait for resopnse. Supports gzip transfer of the response. If error, returns null. No validation is performed.

Parameters:
url - A URL to an XML document
timoutMs - Number of milliseconds to wait before timming out, use 0 for infinity
Returns:
An XML Document containing the dom4j DOM, or null if unable to process the file.
Throws:
DocumentException - If dom4j error
MalformedURLException - If error in the URL
IOException - If IO error
URLConnectionTimedOutException - If no response before reaching timoutMs

getXmlDocument

public static Document getXmlDocument(String url,
                                      int timoutMs)
                               throws DocumentException,
                                      MalformedURLException,
                                      IOException,
                                      URLConnectionTimedOutException
Load XML into a dom4j Document, specifying a max time to wait for resopnse. Supports gzip transfer of the response. If error, returns null. No validation is performed.

Parameters:
url - A URL to an XML document
timoutMs - Number of milliseconds to wait before timming out, use 0 for infinity
Returns:
An XML Document containing the dom4j DOM, or null if unable to process the file.
Throws:
DocumentException - If dom4j error
MalformedURLException - If error in the URL
IOException - If IO error
URLConnectionTimedOutException - If no response before reaching timoutMs

getXmlDocumentPostData

public static Document getXmlDocumentPostData(URL url,
                                              String postData,
                                              int timoutMs)
                                       throws DocumentException,
                                              MalformedURLException,
                                              IOException,
                                              URLConnectionTimedOutException
Post data to a URL and load the response XML into a dom4j Document, specifying a max time to wait for resopnse. Supports gzip transfer of the response. If error, returns null. No validation is performed.

Parameters:
url - A base URL to the service with no http params
timoutMs - Number of milliseconds to wait before timming out, use 0 for infinity
postData - Data to post in the request of the form parm1=value1&param2=value2
Returns:
An XML Document containing the dom4j DOM, or null if unable to process the file.
Throws:
DocumentException - If dom4j error
MalformedURLException - If error in the URL
IOException - If IO error
URLConnectionTimedOutException - If no response before reaching timoutMs

getXmlDocument

public static Document getXmlDocument(String s)
                               throws DocumentException
Load XML into a dom4j Document. If error, return null. No validation is performed.

Parameters:
s - A string representation of an XML document
Returns:
An XML Document containing the dom4j DOM, or null if unable to process the string.
Throws:
DocumentException - If dom4j error

getXmlDocumentLocalized

public static Document getXmlDocumentLocalized(String xml)
                                        throws DocumentException
Load XML into a dom4j Document and localize the XML by removing all namespaces from it. If error, return null. No validation is performed.

Parameters:
xml - A string representation of an XML document
Returns:
An XML Document containing the localized dom4j DOM, or null if unable to process the string.
Throws:
DocumentException - If dom4j error

dom4j2JavaBean

public static Object dom4j2JavaBean(Node javaObjectXmlNode)
                             throws Exception
Takes a dom4j Node that contains an XML serialized JavaBean and returns a JavaBean Object.

Parameters:
javaObjectXmlNode - Dom4j Node
Returns:
JavaBean
Throws:
Exception - If error

isEmpty

public static boolean isEmpty(Element e)
Gets the empty attribute of the Dom4jUtils class

Parameters:
e - NOT YET DOCUMENTED
Returns:
The empty value

isEmpty

public static boolean isEmpty(Element e,
                              boolean ignoreWhiteSpace)
isEmpty returns true if neither the element, or any children recursively, have textual content or have a non-empty attribute.

Parameters:
e - an Element to test
ignoreWhiteSpace - determines whether whitespace is considered as textual content .
Returns:
true if Element and all children recursively are empty

localizeXml

public static String localizeXml(String xml,
                                 String elementName)
Strips all attributes (including namespace information) from a particular element within a string representation of an XML element (having arbitrary content and subelements), then removes all namespace prefixes throughout the xml using a trnasformer. Textually remove all namespace (and all other attributes) from the first occurance of an element of elementName in the input string. This is done using a regex pattern replace.

NOTE: this method is DANGEROUS because it not only strips namespace information, but all attributes from the element.

Parameters:
xml - Description of the Parameter
elementName - Description of the Parameter
Returns:
Description of the Return Value

getLocalizingTransformer

public static final Transformer getLocalizingTransformer()
                                                  throws TransformerConfigurationException,
                                                         FileNotFoundException
Gets the localizingTransformer attribute of the Dom4jUtils class

Returns:
The localizingTransformer value
Throws:
TransformerConfigurationException - NOT YET DOCUMENTED
FileNotFoundException - NOT YET DOCUMENTED

localizeXml

public static Document localizeXml(Document doc,
                                   String rootElementName)
Remove nameSpaceInformation from the root element (as well as any attributes!) to facilitate xpath access

Parameters:
doc - Description of the Parameter
rootElementName - Description of the Parameter
Returns:
Description of the Return Value

localizeXml

public static String localizeXml(String xml)
Localizes an XML String by removing all namespaces from it. I think this is a SAFE way to localize, since it doesn't strip attributes from the root (except those that define namespaces). Obviously, this is good because it preserves non-namespace-defining attributes in the root node (except the schema-instance namespace (e.g., xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"). But because that particular xmlns:xsi attribute is hanging around, we have to test for its presense when we "delocalize" (see MetaDataFramework.getWritableRecord()).

Parameters:
xml - XML as a String
Returns:
XML without namespaces

localizeXml

public static Document localizeXml(Document doc)
Localizes a Dom4j Document by removing all namespaces from it. With namespaces removed, the XPath syntax necessary to work with the document is greatly simplified.

Parameters:
doc - The Document to localize
Returns:
A localized Document, or null if fail

localizeXml

public static Element localizeXml(Element element)
Localizes a Dom4j Element by removing all namespaces from it. With namespaces removed, the XPath syntax necessary to work with the document is greatly simplified.

Parameters:
element - The Element to localize
Returns:
A localized Element, or null if fail

localizeXml

public static Document localizeXml(Node node)
Localizes a Dom4j Node, Document, Branch or Element by removing all namespaces from it, returning a Document. With namespaces removed, the XPath syntax necessary to work with the document is greatly simplified.

Parameters:
node - The Node to localize
Returns:
A localized Document, or null if fail

delocalizeDocStr

public static String delocalizeDocStr(String s,
                                      String rootElementName,
                                      String nameSpaceInfo)
Insert nameSpaceInformation into the root element to make validation possible.

NOTE: only delocalizes if the rootElement is empty.

Parameters:
s - Description of the Parameter
rootElementName - Description of the Parameter
nameSpaceInfo - Description of the Parameter
Returns:
Description of the Return Value

delocalizeXml

public static Document delocalizeXml(Document doc,
                                     String rootElementName,
                                     String nameSpaceInfo)
Insert nameSpaceInformation into the root element

Parameters:
doc - Description of the Parameter
rootElementName - Description of the Parameter
nameSpaceInfo - Description of the Parameter
Returns:
Description of the Return Value

getNameSpaceInfo

public static String getNameSpaceInfo(Document doc,
                                      String rootElementName)
Gets the nameSpaceInfo associated with the root element of a Document. Returns all contents of the root Element except the element name.

Parameters:
doc - Description of the Parameter
rootElementName - Description of the Parameter
Returns:
The nameSpaceInfo value

writeDocToFile

public static void writeDocToFile(Document doc,
                                  File out)
                           throws Exception
Writes Document to File

Parameters:
doc - Description of the Parameter
out - Description of the Parameter
Throws:
Exception - Description of the Exception

writePrettyDocToFile

public static void writePrettyDocToFile(Document doc,
                                        File out)
                                 throws Exception
write formated xml to file to faciliate human-readibility

Parameters:
doc - Description of the Parameter
out - Description of the Parameter
Throws:
Exception - Description of the Exception

writeDocToFile

public static void writeDocToFile(Document doc,
                                  File out,
                                  OutputFormat format)
                           throws Exception
Write XML Document to disk using specified OutputFormat

Parameters:
doc - Description of the Parameter
out - Description of the Parameter
format - Description of the Parameter
Throws:
Exception - Description of the Exception

getXMLWriter

public static XMLWriter getXMLWriter()
Gets an XMLWriter object

Returns:
The xMLWriter value

prettyPrint

public static String prettyPrint(Node node)
Formats an Node as a printable string

Parameters:
node - the Node to display
Returns:
a nicley-formatted String representation of the Node.

log

public void log(String msg)
Logger hook

Parameters:
msg - Message to be logged.

getDateStamp

protected static final String getDateStamp()
Return a string for the current time and date, sutiable for display in log files and output to standout:

Returns:
The dateStamp value

prtlnErr

protected static final void prtlnErr(String s)
Output a line of text to error out, with datestamp.

Parameters:
s - The text that will be output to error out.

prtln

protected static final void prtln(String s)
Output a line of text to standard out, with datestamp, if debug is set to true.

Parameters:
s - The String that will be output.

setDebug

public static void setDebug(boolean db)
Sets the debug attribute of the object

Parameters:
db - The new debug value

DLESE Tools
v1.6.0