Package 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

    Constructors
    Constructor
    Description
    Dom4jUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    delocalizeDocStr(String s, String rootElementName, String nameSpaceInfo)
    Insert nameSpaceInformation into the root element to make validation possible.
    static org.dom4j.Document
    delocalizeXml(org.dom4j.Document doc, String rootElementName, String nameSpaceInfo)
    Insert nameSpaceInformation into the root element
    static Object
    dom4j2JavaBean(org.dom4j.Node javaObjectXmlNode)
    Takes a dom4j Node that contains an XML serialized JavaBean and returns a JavaBean Object.
    protected static final String
    getDateStamp()
    Return a string for the current time and date, sutiable for display in log files and output to standout:
    static final Transformer
    getLocalizingTransformer()
    Gets the localizingTransformer attribute of the Dom4jUtils class
    static String
    getNameSpaceInfo(org.dom4j.Document doc, String rootElementName)
    Gets the nameSpaceInfo associated with the root element of a Document.
    static org.dom4j.Document
    getXmlDocument(File file)
    Load an XML file into a dom4j Document.
    static org.dom4j.Document
    getXmlDocument(File file, String encoding)
    Load an XML file into a dom4j Document using the given character encoding.
    static org.dom4j.Document
    getXmlDocument(String s)
    Load XML into a dom4j Document.
    static org.dom4j.Document
    getXmlDocument(String url, int timoutMs)
    Load XML into a dom4j Document, specifying a max time to wait for resopnse.
    static org.dom4j.Document
    getXmlDocument(URL url)
    Load XML into a dom4j Document.
    static org.dom4j.Document
    getXmlDocument(URL url, int timoutMs)
    Load XML into a dom4j Document, specifying a max time to wait for resopnse.
    static org.dom4j.Document
    getXmlDocumentLocalized(String xml)
    Load XML into a dom4j Document and localize the XML by removing all namespaces from it.
    static org.dom4j.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 org.dom4j.io.XMLWriter
    getXMLWriter()
    Gets an XMLWriter object
    static boolean
    isEmpty(org.dom4j.Element e)
    Gets the empty attribute of the Dom4jUtils class
    static boolean
    isEmpty(org.dom4j.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 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.
    static org.dom4j.Document
    localizeXml(org.dom4j.Document doc)
    Localizes a Dom4j Document by removing all namespaces from it.
    static org.dom4j.Document
    localizeXml(org.dom4j.Document doc, String rootElementName)
    Remove nameSpaceInformation from the root element (as well as any attributes!) to facilitate xpath access
    static org.dom4j.Element
    localizeXml(org.dom4j.Element element)
    Localizes a Dom4j Element by removing all namespaces from it.
    static org.dom4j.Document
    localizeXml(org.dom4j.Node node)
    Localizes a Dom4j Node, Document, Branch or Element by removing all namespaces from it, returning a Document.
    void
    log(String msg)
    Logger hook
    static String
    prettyPrint(org.dom4j.Node node)
    Formats an Node as a printable string
    protected static final void
    prtln(String s)
    Output a line of text to standard out, with datestamp, if debug is set to true.
    protected static final 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(org.dom4j.Document doc, File out)
    Writes Document to File
    static void
    writeDocToFile(org.dom4j.Document doc, File out, org.dom4j.io.OutputFormat format)
    Write XML Document to disk using specified OutputFormat
    static void
    writePrettyDocToFile(org.dom4j.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 Details

    • Dom4jUtils

      public Dom4jUtils()

  • Method Details

    • getXmlDocument

      public static org.dom4j.Document getXmlDocument(File file) throws org.dom4j.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:
      org.dom4j.DocumentException - If dom4j error
      MalformedURLException - If error in file name

    • getXmlDocument

      public static org.dom4j.Document getXmlDocument(File file, String encoding) throws org.dom4j.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:
      org.dom4j.DocumentException - If dom4j error
      MalformedURLException - If error in file name
      IOException - If IO error

    • getXmlDocument

      public static org.dom4j.Document getXmlDocument(URL url) throws org.dom4j.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:
      org.dom4j.DocumentException - If dom4j error
      MalformedURLException - If error in the URL

    • getXmlDocument

      public static org.dom4j.Document getXmlDocument(URL url, int timoutMs) throws org.dom4j.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:
      org.dom4j.DocumentException - If dom4j error
      MalformedURLException - If error in the URL
      IOException - If IO error
      URLConnectionTimedOutException - If no response before reaching timoutMs

    • getXmlDocument

      public static org.dom4j.Document getXmlDocument(String url, int timoutMs) throws org.dom4j.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:
      org.dom4j.DocumentException - If dom4j error
      MalformedURLException - If error in the URL
      IOException - If IO error
      URLConnectionTimedOutException - If no response before reaching timoutMs

    • getXmlDocumentPostData

      public static org.dom4j.Document getXmlDocumentPostData(URL url, String postData, int timoutMs) throws org.dom4j.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
      postData - Data to post in the request of the form parm1=value1&param2=value2
      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:
      org.dom4j.DocumentException - If dom4j error
      MalformedURLException - If error in the URL
      IOException - If IO error
      URLConnectionTimedOutException - If no response before reaching timoutMs

    • getXmlDocument

      public static org.dom4j.Document getXmlDocument(String s) throws org.dom4j.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:
      org.dom4j.DocumentException - If dom4j error

    • getXmlDocumentLocalized

      public static org.dom4j.Document getXmlDocumentLocalized(String xml) throws org.dom4j.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:
      org.dom4j.DocumentException - If dom4j error

    • dom4j2JavaBean

      public static Object dom4j2JavaBean(org.dom4j.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(org.dom4j.Element e)
      Gets the empty attribute of the Dom4jUtils class
      Parameters:
      e - NOT YET DOCUMENTED
      Returns:
      The empty value

    • isEmpty

      public static boolean isEmpty(org.dom4j.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 org.dom4j.Document localizeXml(org.dom4j.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 org.dom4j.Document localizeXml(org.dom4j.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 org.dom4j.Element localizeXml(org.dom4j.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 org.dom4j.Document localizeXml(org.dom4j.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 org.dom4j.Document delocalizeXml(org.dom4j.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(org.dom4j.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(org.dom4j.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(org.dom4j.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(org.dom4j.Document doc, File out, org.dom4j.io.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 org.dom4j.io.XMLWriter getXMLWriter()
      Gets an XMLWriter object
      Returns:
      The xMLWriter value

    • prettyPrint

      public static String prettyPrint(org.dom4j.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