org.dlese.dpc.xml
Class Dom4jUtils

java.lang.Object
  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