com.aspc.remote.util.misc

Class DocumentUtil

java.lang.Object

com.aspc.remote.util.misc.DocumentUtil

public final class DocumentUtil
extends java.lang.Object

Handles XML documents.
THREAD MODE: MULTI-THREADED DOM objects created by Xerces are NOT multi-thread safe even if these objects are only in read only mode may not be accessed concurrently by separate threads. Currently we are sharing the DOM objects for the stored results across threads. http://xerces.apache.org/xerces2-j/faq-dom.html#faq-1 http://old.nabble.com/DOM-thread-safety-issues---disapearring-children-td31795248.html

Since:

3 December 2001, 12:02

Author:

Nigel Leck

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DocumentUtil.PARSER The parser type.

Method Summary

Modifier and Type	Method and Description
static void	clearCache() Clear the templates cache
static org.w3c.dom.Element	createTextOnlyElement(org.w3c.dom.Document doc, java.lang.String element_name, java.lang.String element_value) Convenience function for creating a text-only element.
static JSONObject	docToJson(org.w3c.dom.Document doc)
static java.lang.String	docToString(org.w3c.dom.Document doc) convert a document to a string.
static javax.xml.parsers.DocumentBuilder	getBuilder() returns the current builder for this thread
static javax.xml.parsers.DocumentBuilder	getBuilder(DocumentUtil.PARSER parser) returns the current builder for this thread
static java.lang.String	getNodeText(org.w3c.dom.Document doc, java.lang.String nodeTag) get the node text
static org.w3c.dom.Document	loadDocument(java.io.File file) Load a file and return it as an XML Document object
static org.w3c.dom.Document	loadDocument(java.io.File file, DocumentUtil.PARSER parser) Load a file and return it as an XML Document object
static org.w3c.dom.Document	loadEncodedDocument(java.io.File file, java.lang.String encoding) Read the encoded file
static org.w3c.dom.Document	makeDocument(java.lang.String xml) make a document.
static org.w3c.dom.Document	makeDocument(java.lang.String xml, DocumentUtil.PARSER parser) make a document.
static org.w3c.dom.Document	newDocument() Create a new XML document
static javax.xml.transform.Transformer	newTransformer() New transformer.
static javax.xml.transform.Transformer	newTransformer(java.lang.String xslt) New XSLT transformer.
static java.lang.String	nodeToString(org.w3c.dom.Node node) convert a node to a string
static void	normaliseDocument(org.w3c.dom.Node n) The function normaliseDocument removes superfluous and non-intuitive "#TEXT#" nodes created from a space between XML elements sourced from http://www.javaworld.com/javaworld/jw-06-2001/jw-0622-traps-p2.html
static void	writeDocument(org.w3c.dom.Document document, java.io.File file) write a document to a file.
static void	writeNode(org.w3c.dom.Node node, java.io.Writer w) write a document to a file.
static void	writeNode(org.w3c.dom.Node node, java.io.Writer w, int indent) write a document to a file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getNodeText

@CheckReturnValue
 @Nonnull
public static java.lang.String getNodeText(@Nonnull
                                                                       org.w3c.dom.Document doc,
                                                                       @Nonnull
                                                                       java.lang.String nodeTag)

get the node text

Parameters:

doc - the document

nodeTag - the node

Returns:

the text

getBuilder

@CheckReturnValue
 @Nonnull
public static javax.xml.parsers.DocumentBuilder getBuilder()
                                                                                throws javax.xml.parsers.ParserConfigurationException

returns the current builder for this thread

Returns:

the current document builder

Throws:

javax.xml.parsers.ParserConfigurationException - a serious problem

getBuilder

@CheckReturnValue
 @Nonnull
public static javax.xml.parsers.DocumentBuilder getBuilder(@Nonnull
                                                                                       DocumentUtil.PARSER parser)
                                                                                throws javax.xml.parsers.ParserConfigurationException

returns the current builder for this thread

Parameters:

parser - the parser to use.

Returns:

the current document builder

Throws:

javax.xml.parsers.ParserConfigurationException - a serious problem

makeDocument

@CheckReturnValue
 @Nonnull
public static org.w3c.dom.Document makeDocument(@Nonnull
                                                                            java.lang.String xml)
                                                                     throws DocumentException

make a document.

Parameters:

xml - The XML to parse

Returns:

The newly created and populated DOM

Throws:

DocumentException - a serious problem

makeDocument

@CheckReturnValue
 @Nonnull
public static org.w3c.dom.Document makeDocument(@Nonnull
                                                                            java.lang.String xml,
                                                                            @Nonnull
                                                                            DocumentUtil.PARSER parser)
                                                                     throws DocumentException

make a document.

Parameters:

xml - The XML to parse

parser - the parser to use

Returns:

The newly created and populated DOM

Throws:

DocumentException - a serious problem

loadDocument

@CheckReturnValue
 @Nonnull
public static org.w3c.dom.Document loadDocument(@Nonnull
                                                                            java.io.File file)
                                                                     throws java.lang.Exception

Load a file and return it as an XML Document object

Parameters:

file - the file to read the XML file from

Returns:

The XML document

Throws:

java.lang.Exception - a serious problem

loadDocument

@CheckReturnValue
 @Nonnull
public static org.w3c.dom.Document loadDocument(@Nonnull
                                                                            java.io.File file,
                                                                            @Nonnull
                                                                            DocumentUtil.PARSER parser)
                                                                     throws java.lang.Exception

Load a file and return it as an XML Document object

Parameters:

file - the file to read the XML file from

parser - the parser

Returns:

The XML document

Throws:

java.lang.Exception - a serious problem

loadEncodedDocument

@CheckReturnValue
 @Nonnull
public static org.w3c.dom.Document loadEncodedDocument(@Nonnull
                                                                                   java.io.File file,
                                                                                   @Nonnull
                                                                                   java.lang.String encoding)
                                                                            throws java.lang.Exception

Read the encoded file

Parameters:

file - file to be read

encoding - what for the encoding is

Returns:

document

Throws:

java.lang.Exception - if file does not exists

writeDocument

public static void writeDocument(@Nonnull
                                 org.w3c.dom.Document document,
                                 @Nonnull
                                 java.io.File file)
                          throws java.lang.Exception

write a document to a file.

Parameters:

document - the document to write

file - the file to write to.

Throws:

java.lang.Exception - a serious problem

writeNode

public static void writeNode(@Nonnull
                             org.w3c.dom.Node node,
                             @Nonnull
                             java.io.Writer w)
                      throws java.lang.Exception

write a document to a file.

Parameters:

node -

w -

Throws:

java.lang.Exception - a serious problem

writeNode

public static void writeNode(@Nonnull
                             org.w3c.dom.Node node,
                             @Nonnull
                             java.io.Writer w,
                             @Nonnegative
                             int indent)
                      throws java.lang.Exception

write a document to a file.

Parameters:

node -

w -

indent - amount to indent

Throws:

java.lang.Exception - a serious problem

clearCache

public static void clearCache()

Clear the templates cache

newTransformer

@CheckReturnValue
 @Nonnull
public static javax.xml.transform.Transformer newTransformer(@Nonnull
                                                                                         java.lang.String xslt)
                                                                                  throws javax.xml.transform.TransformerConfigurationException,
                                                                                         java.io.IOException

New XSLT transformer.

Parameters:

xslt - the XSLT to transform.

Returns:

the transformer.

Throws:

javax.xml.transform.TransformerConfigurationException

java.io.IOException - if an IO exception occurs.

newTransformer

@CheckReturnValue
 @Nonnull
public static javax.xml.transform.Transformer newTransformer()
                                                                                  throws javax.xml.transform.TransformerConfigurationException

New transformer.

Returns:

the new clean transformer.

Throws:

javax.xml.transform.TransformerConfigurationException

newDocument

@CheckReturnValue
 @Nonnull
public static org.w3c.dom.Document newDocument()
                                                                    throws javax.xml.parsers.ParserConfigurationException

Create a new XML document

Returns:

the new blank document

Throws:

javax.xml.parsers.ParserConfigurationException - a serious problem

docToString

@CheckReturnValue
 @Nonnull
public static java.lang.String docToString(@Nonnull
                                                                       org.w3c.dom.Document doc)
                                                                throws java.lang.Exception

convert a document to a string.

Parameters:

doc - The document to convert

Returns:

The XML string

Throws:

java.lang.Exception - a serious problem

nodeToString

public static java.lang.String nodeToString(@Nonnull
                                            org.w3c.dom.Node node)
                                     throws java.lang.Exception

convert a node to a string

Parameters:

node - the node to convert

Returns:

The XML string

Throws:

java.lang.Exception

docToJson

@CheckReturnValue
 @Nonnull
public static JSONObject docToJson(@Nonnull
                                                               org.w3c.dom.Document doc)
                                                        throws java.lang.Exception

Throws:

java.lang.Exception

normaliseDocument

public static void normaliseDocument(@Nonnull
                                     org.w3c.dom.Node n)

The function normaliseDocument removes superfluous and non-intuitive "#TEXT#" nodes created from a space between XML elements sourced from http://www.javaworld.com/javaworld/jw-06-2001/jw-0622-traps-p2.html

Parameters:

n - the node to normalize

createTextOnlyElement

@CheckReturnValue
 @Nonnull
public static org.w3c.dom.Element createTextOnlyElement(@Nonnull
                                                                                    org.w3c.dom.Document doc,
                                                                                    @Nonnull
                                                                                    java.lang.String element_name,
                                                                                    @Nonnull
                                                                                    java.lang.String element_value)

Convenience function for creating a text-only element.

Parameters:

doc - the document

element_name -

element_value -

Returns:

the value