Nux 1.0

nux.xom.pool
Class XOMUtil

java.lang.Object
  extended bynux.xom.pool.XOMUtil

public class XOMUtil
extends Object

Various utilities avoiding redundant code in several classes.

Author:
whoschek.AT.lbl.DOT.gov, $Author: hoschek3 $

Method Summary
static DOMImplementation getDOMImplementation()
          Returns a DOMImplementation via the default JAXP lookup mechanism.
static NodeFactory getIgnoreWhitespaceOnlyTextNodeFactory()
          Returns a node factory that removes each Text node that is empty or consists of whitespace characters only.
static NodeFactory getNullNodeFactory()
          Returns a node factory for pure document validation.
static NodeFactory getTextTrimmingNodeFactory()
          Returns a node factory that removes leading and trailing whitespaces in each Text node, altogether removing a Text node that becomes empty after said trimming.
static Document jaxbMarshal(Marshaller marshaller, Object jaxbObj)
          Marshals (serializes) the given JAXB object via the given marshaller into a new XOM Document (convenience method).
static Object jaxbUnmarshal(Unmarshaller unmarshaller, ParentNode node)
          Unmarshals (deserializes) the given XOM node via the given unmarshaller into a new JAXB object (convenience method).
static byte[] toByteArray(InputStream input)
          Reads until end-of-stream and returns all read bytes, finally closes the stream.
static byte[] toCanonicalXML(Document doc)
          Returns the W3C Canonical XML representation of the given document.
static String toPrettyXML(Node node)
          Returns a pretty-printed String representation of the given node (subtree).
static String toString(InputStream input, Charset charset)
          Reads until end-of-stream and returns all read bytes as a string, finally closes the stream, converting the data with the given charset encoding, or the system's default platform encoding if charset == null.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getDOMImplementation

public static DOMImplementation getDOMImplementation()
Returns a DOMImplementation via the default JAXP lookup mechanism.


toByteArray

public static byte[] toByteArray(InputStream input)
                          throws IOException
Reads until end-of-stream and returns all read bytes, finally closes the stream.

Parameters:
input - the input stream
Throws:
IOException - if an I/O error occurs while reading the stream

toString

public static String toString(InputStream input,
                              Charset charset)
                       throws IOException
Reads until end-of-stream and returns all read bytes as a string, finally closes the stream, converting the data with the given charset encoding, or the system's default platform encoding if charset == null.

Parameters:
input - the input stream
charset - the charset to convert with, e.g. Charset.forName("UTF-8")
Throws:
IOException - if an I/O error occurs while reading the stream

toPrettyXML

public static String toPrettyXML(Node node)
Returns a pretty-printed String representation of the given node (subtree).

Parameters:
node - the node (subtree) to convert.
See Also:
Serializer

toCanonicalXML

public static byte[] toCanonicalXML(Document doc)
Returns the W3C Canonical XML representation of the given document.

Parameters:
doc - the document to convert.
See Also:
Canonicalizer

getIgnoreWhitespaceOnlyTextNodeFactory

public static NodeFactory getIgnoreWhitespaceOnlyTextNodeFactory()
Returns a node factory that removes each Text node that is empty or consists of whitespace characters only. This method fully preserves narrative Text containing whitespace along with other characters.

Otherwise this factory behaves just like the standard NodeFactory.

Ignoring whitespace-only nodes reduces memory footprint for documents that are heavily pretty printed and indented, i.e. human-readable. Remember that without such a factory, every whitespace sequence occurring between element tags generates a mostly useless Text node.

Finally, note that this method's whitespace pruning is appropriate for many, but not all XML use cases (round-tripping). For example, the blank between <p><strong>Hello</strong> <em>World!</em></p> will be removed, which might not be what you want. This is because this method does not look across multiple Text nodes.


getTextTrimmingNodeFactory

public static NodeFactory getTextTrimmingNodeFactory()
Returns a node factory that removes leading and trailing whitespaces in each Text node, altogether removing a Text node that becomes empty after said trimming. Trimming is done via String.trim(). For example a text node of " hello world " becomes "hello world", and a text node of " " is removed.

Otherwise this factory behaves just like the standard NodeFactory.

Finally, note that this method's whitespace pruning is appropriate for many, but not all XML use cases (round-tripping).


getNullNodeFactory

public static NodeFactory getNullNodeFactory()
Returns a node factory for pure document validation. This factory does not generate a document on Builder.build(...), which is not required anyway for pure validation. Ignores all input and builds an empty document instead. This improves validation performance.


jaxbMarshal

public static Document jaxbMarshal(Marshaller marshaller,
                                   Object jaxbObj)
                            throws JAXBException
Marshals (serializes) the given JAXB object via the given marshaller into a new XOM Document (convenience method).

This implementation is somewhat inefficient but correctly does the job. There is no connection between the JAXB object tree and the XOM object tree; they are completely independent object trees without any cross-references. Hence, updates in one tree are not automatically reflected in the other tree.

Parameters:
marshaller - a JAXB serializer (note that a marshaller is typically not thread-safe and expensive to construct; hence the recommendation is to use a ThreadLocal to make it thread-safe and efficient)
jaxbObj - the JAXB object to serialize
Returns:
the new XOM document
Throws:
JAXBException - If an unexpected problem occurred in the conversion.
MarshalException - If an error occurred while performing the marshal operation. Whereever possible, one should prefer the MarshalException over the JAXBException.
See Also:
Marshaller.marshal(java.lang.Object, org.w3c.dom.Node)

jaxbUnmarshal

public static Object jaxbUnmarshal(Unmarshaller unmarshaller,
                                   ParentNode node)
                            throws JAXBException
Unmarshals (deserializes) the given XOM node via the given unmarshaller into a new JAXB object (convenience method).

This implementation is somewhat inefficient but correctly does the job. There is no connection between the JAXB object tree and the XOM object tree; they are completely independent object trees without any cross-references. Hence, updates in one tree are not automatically reflected in the other tree.

Parameters:
unmarshaller - a JAXB deserializer (note that an unmarshaller is typically not thread-safe and expensive to construct; hence the recommendation is to use a ThreadLocal to make it thread-safe and efficient)
node - the XOM node to deserialize
Returns:
the new JAXB object
Throws:
JAXBException - If an unexpected problem occurred in the conversion.
UnmarshalException - If an error occurred while performing the unmarshal operation. Whereever possible, one should prefer the UnmarshalException over the JAXBException.
See Also:
Unmarshaller.unmarshal(org.w3c.dom.Node)

Nux 1.0