org.eclipse.smila.utils.xml
Class XMLUtils

java.lang.Object
  org.eclipse.smila.utils.xml.XMLUtils

public abstract class XMLUtils
extends java.lang.Object

All parse() methods must be given a wellformatted XML rescource, in which the encoding is set forth, since none of them recieves such an parameter. If no encoding is specified in the XML recource, UTF-8 is assumed as set forth by the W3C recommendation.

For all stream() methods without the encoding-paramter the default encoding UTF-8 is assumed (W3C Recommendation?).

Method Summary

static void	clearGrammarCache() Clear grammar cache.
static boolean	decodeBoolean(java.lang.String xmlBoolean) Decodes a Boolean.
static java.util.Date	decodeDate(java.lang.String xmlDate) Decodes a Date.
static java.util.Date	decodeDateTime(java.lang.String xmlDate) Decodes a DateTime.
static int	decodeInteger(java.lang.String xmlInteger) Decodes an Integer.
static byte[]	documentToBytes(org.w3c.dom.Document document) Converts a Document into a byte[].
static java.lang.String	documentToString(org.w3c.dom.Document document) Converts a Document to a String.
static java.lang.String	encodeBoolean(boolean javaBoolean) Encodes a boolean.
static java.lang.String	encodeDate(java.util.Date javaDate) Encodes a date.
static java.lang.String	encodeDateTime(java.util.Date javaDate) Encodes a DateTime.
static java.lang.String	encodeInteger(int value) Encodes and Integer.
static java.lang.String	encodeInteger(java.lang.Integer value) Encodes and Integer.
static java.lang.String	generateGUID(java.lang.Object o) A 32 byte GUID generator (Globally Unique ID).
static org.w3c.dom.Document	getDocument() Returns an empty document whose document element is not set ! The type of the document is by default an XML-Document.
static org.w3c.dom.Document	getDocument(java.lang.String docElement) Creates a document with a new document element with it's name set to the given text.
static java.lang.String	getLocalPart(java.lang.String xml) This method converts a given XML attribute or element name to a local representation by stripping it of its namespace prefix.
static boolean	isXML(byte[] message) Checks if the given byte[] is XML.
static boolean	isXML(java.io.File file) Checks if the given file is XML.
static boolean	isXML(java.io.InputStream is) Checks if the given InputStream is XML.
static void	loadSchema(java.lang.String schemaName, BundleContext context)
static void	loadSchemas(java.io.File folder, java.lang.String filter, java.lang.String schemaUrlPrefix) Load schemas.
static org.w3c.dom.Document	newDocument() Creates a new Document.
static org.w3c.dom.Document	parse(byte[] bytes, boolean validate) Shorthand for parse(bytes, new XMLUtilsConfig(validate,true)).
static org.w3c.dom.Document	parse(byte[] bytes, XMLUtilsConfig cfg) Parses a document from the given byte-array.The applied encoding must be declared within the XML-document-instance or otherwise UTF-8 is assumed according to the W3C recommendation.
static org.w3c.dom.Document	parse(java.io.File file, boolean validate) Shorthand for parse(file, new XMLUtilsConfig(validate,true)).
static org.w3c.dom.Document	parse(java.io.File file, XMLUtilsConfig cfg) Parses a document from the given File.
static org.w3c.dom.Document	parse(java.io.InputStream is, boolean validate) Shorthand for parse(is , new XMLUtilsConfig(validate,true)).
static org.w3c.dom.Document	parse(java.io.InputStream is, XMLUtilsConfig cfg) Parses a document from the given InputStream.
static void	removeWhitespaceTextNodes(org.w3c.dom.Element parent) Traverses through a DOM tree starting at the given element and removes all those text-nodes from it that only contain white spaces.
static void	setGrammarCacheLock(boolean lockState) Sets the grammar cache lock.
static byte[]	stream(org.w3c.dom.Element el, boolean validate) Shorthand for stream(el , validate, "UTF-8")).
static byte[]	stream(org.w3c.dom.Element el, boolean validate, boolean preserveSpace) Shorthand for stream(el , validate, "UTF-8")).
static byte[]	stream(org.w3c.dom.Element el, boolean validate, java.lang.String enc, boolean preserveSpace) Streams the given DOM-(Sub)tree starting at the given Element into the returned byte-array.
static void	stream(org.w3c.dom.Element el, boolean validate, java.lang.String enc, java.io.File file) Streams the given DOM-(Sub)tree starting at the given Element into the given File.
static void	stream(org.w3c.dom.Element el, boolean validate, java.lang.String enc, java.io.OutputStream os) Streams the given DOM-(Sub)tree starting at the given Element into the returned byte-array.
static boolean	validate(org.w3c.dom.Element el) Validates the given element and it's decendants against the XML-Schema as specified in the given element.

Methods inherited from class java.lang.Object

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

Method Detail

newDocument

public static org.w3c.dom.Document newDocument()
                                        throws XMLUtilsException

Creates a new Document.

Returns:

the Document

Throws:

XMLUtilsException - if any error occurs

documentToString

public static java.lang.String documentToString(org.w3c.dom.Document document)
                                         throws XMLUtilsException

Converts a Document to a String.

Parameters:

document - the Document to convert

Returns:

a String

Throws:

XMLUtilsException - if any error occurs

documentToBytes

public static byte[] documentToBytes(org.w3c.dom.Document document)
                              throws XMLUtilsException

Converts a Document into a byte[].

Parameters:

document - the Document

Returns:

a byte[]

Throws:

XMLUtilsException - if any error occurs

decodeDate

public static java.util.Date decodeDate(java.lang.String xmlDate)
                                 throws java.text.ParseException

Decodes a Date.

Parameters:

xmlDate - the xmlDate

Returns:

a Date

Throws:

java.text.ParseException - if any error occurs

encodeDate

public static java.lang.String encodeDate(java.util.Date javaDate)

Encodes a date.

Parameters:

javaDate - a Date

Returns:

a String

decodeDateTime

public static java.util.Date decodeDateTime(java.lang.String xmlDate)
                                     throws java.text.ParseException

Decodes a DateTime.

Parameters:

xmlDate - the xmlDate

Returns:

Date

Throws:

java.text.ParseException - if any error occurs

encodeDateTime

public static java.lang.String encodeDateTime(java.util.Date javaDate)

Encodes a DateTime.

Parameters:

javaDate - a date

Returns:

a String

decodeBoolean

public static boolean decodeBoolean(java.lang.String xmlBoolean)

Decodes a Boolean.

Parameters:

xmlBoolean - the xmlBoolean

Returns:

a boolean

encodeBoolean

public static java.lang.String encodeBoolean(boolean javaBoolean)

Encodes a boolean.

Parameters:

javaBoolean - a boolean

Returns:

a String

decodeInteger

public static int decodeInteger(java.lang.String xmlInteger)

Decodes an Integer.

Parameters:

xmlInteger - the xmlInteger

Returns:

a int

encodeInteger

public static java.lang.String encodeInteger(int value)

Encodes and Integer.

Parameters:

value - a int

Returns:

a String

encodeInteger

public static java.lang.String encodeInteger(java.lang.Integer value)

Encodes and Integer.

Parameters:

value - Integer

Returns:

a String

generateGUID

public static final java.lang.String generateGUID(java.lang.Object o)

A 32 byte GUID generator (Globally Unique ID). These artificial keys SHOULD NOT be seen by the user, not even touched by the DBA but with very rare exceptions, just manipulated by the database and the programs. Usage: Add an id field (type java.lang.String) to your EJB, and add setId(XXXUtil.generateGUID(this)); to the ejbCreate method.

Parameters:

o - a Object

Returns:

a String

getDocument

public static org.w3c.dom.Document getDocument()

Returns an empty document whose document element is not set ! The type of the document is by default an XML-Document.

Returns:

a Document

getDocument

public static org.w3c.dom.Document getDocument(java.lang.String docElement)

Creates a document with a new document element with it's name set to the given text.

Parameters:

docElement - a docElement

Returns:

a Document

getLocalPart

public static java.lang.String getLocalPart(java.lang.String xml)

This method converts a given XML attribute or element name to a local representation by stripping it of its namespace prefix.

Parameters:

xml - the xml

Returns:

String

isXML

public static boolean isXML(java.io.File file)

Checks if the given file is XML.

Parameters:

file - a File

Returns:

boolean

isXML

public static boolean isXML(byte[] message)

Checks if the given byte[] is XML.

Parameters:

message - a byte[]

Returns:

boolean

isXML

public static boolean isXML(java.io.InputStream is)

Checks if the given InputStream is XML.

Parameters:

is - a InputStream

Returns:

boolean

loadSchema

public static void loadSchema(java.lang.String schemaName,
                              BundleContext context)
                       throws XMLUtilsException

Parameters:

schemaName - Schema name.

Throws:

XMLUtilsException - Unable to resolve schema.

loadSchemas

public static void loadSchemas(java.io.File folder,
                               java.lang.String filter,
                               java.lang.String schemaUrlPrefix)
                        throws XMLUtilsException

Load schemas.

Parameters:

folder - the folder

filter - the filter

schemaUrlPrefix - the schemaUrlPrefix

Throws:

XMLUtilsException - if any error occurs

clearGrammarCache

public static void clearGrammarCache()

Clear grammar cache.

setGrammarCacheLock

public static void setGrammarCacheLock(boolean lockState)

Sets the grammar cache lock.

Parameters:

lockState - boolean flag

parse

public static org.w3c.dom.Document parse(byte[] bytes,
                                         boolean validate)
                                  throws XMLUtilsException

Shorthand for parse(bytes, new XMLUtilsConfig(validate,true)).

Parameters:

bytes - a byte[]

validate - boolean flag

Returns:

a Document

Throws:

XMLUtilsException - if any error occurs

parse

public static org.w3c.dom.Document parse(byte[] bytes,
                                         XMLUtilsConfig cfg)
                                  throws XMLUtilsException

Parses a document from the given byte-array.The applied encoding must be declared within the XML-document-instance or otherwise UTF-8 is assumed according to the W3C recommendation.

Parameters:

bytes - a byte[]

cfg - a XMLUtilsConfig

Returns:

a Document

Throws:

XMLUtilsException - if cgf contains invalid values or parsing results in an error.

parse

public static org.w3c.dom.Document parse(java.io.File file,
                                         boolean validate)
                                  throws XMLUtilsException

Shorthand for parse(file, new XMLUtilsConfig(validate,true)).

Parameters:

file - a File

validate - boolean flag

Returns:

a Document

Throws:

XMLUtilsException - if any error occurs

parse

public static org.w3c.dom.Document parse(java.io.File file,
                                         XMLUtilsConfig cfg)
                                  throws XMLUtilsException

Parses a document from the given File. The applied encoding must be declared within the XML-document-instance or otherwise UTF-8 is assumed according to the W3C recommendation.

Parameters:

file - a File

cfg - the XMLUtilsConfig

Returns:

a Document

Throws:

XMLUtilsException - if the File dosn't point to a valid location, cgf contains invalid values, or parsing results in an error.

parse

public static org.w3c.dom.Document parse(java.io.InputStream is,
                                         boolean validate)
                                  throws XMLUtilsException

Shorthand for parse(is , new XMLUtilsConfig(validate,true)).

Parameters:

is - a InputStream

validate - boolean flag

Returns:

a Document

Throws:

XMLUtilsException - if any error occurs

parse

public static org.w3c.dom.Document parse(java.io.InputStream is,
                                         XMLUtilsConfig cfg)
                                  throws XMLUtilsException

Parses a document from the given InputStream. The applied encoding must be declared within the XML-document-instance or otherwise UTF-8 is assumed according to the W3C recommendation.

Parameters:

is - a InputStream

cfg - the XMLUtilsConfig

Returns:

a Document

Throws:

XMLUtilsException - if cfg contains invalid values or parsing results in an error.

removeWhitespaceTextNodes

public static void removeWhitespaceTextNodes(org.w3c.dom.Element parent)

Traverses through a DOM tree starting at the given element and removes all those text-nodes from it that only contain white spaces.

Parameters:

parent - the parent Element

stream

public static byte[] stream(org.w3c.dom.Element el,
                            boolean validate)
                     throws XMLUtilsException

Shorthand for stream(el , validate, "UTF-8")).

Parameters:

el - a Element

validate - boolean flag

Returns:

a byte[]

Throws:

XMLUtilsException - if any exception occurs

stream

public static byte[] stream(org.w3c.dom.Element el,
                            boolean validate,
                            boolean preserveSpace)
                     throws XMLUtilsException

Shorthand for stream(el , validate, "UTF-8")).

Parameters:

el - a Element

validate - boolean flag

preserveSpace - boolean flag

Returns:

a byte[]

Throws:

XMLUtilsException - if any exception occurs

stream

public static byte[] stream(org.w3c.dom.Element el,
                            boolean validate,
                            java.lang.String enc,
                            boolean preserveSpace)
                     throws XMLUtilsException

Streams the given DOM-(Sub)tree starting at the given Element into the returned byte-array.

Parameters:

el - a Element

validate - whether the given DOM-(sub)tree shall be validated against an XML-Schema that is referenced in the given element.

enc - the encoding that shall be applied. The given String must conform to the encodings as set forth by the W3C and are somewhat different to that of Java.

preserveSpace - boolean flag

Returns:

a byte[]

Throws:

XMLUtilsException - if any exception occurs

stream

public static void stream(org.w3c.dom.Element el,
                          boolean validate,
                          java.lang.String enc,
                          java.io.File file)
                   throws XMLUtilsException

Streams the given DOM-(Sub)tree starting at the given Element into the given File. *

Parameters:

el - a Element

enc - the encoding that shall be applied. The given String must conform to the encodings as set forth by the W3C and are somewhat different to that of Java.

validate - whether the given DOM-(sub)tree shall be validated against an XML-Schema that is referenced in the given element.

file - if it exist it will be overwritten otherwise created. If access rights are violated an XMLUtilsExcpetion is thrown.

Throws:

XMLUtilsException - if any error occurs

stream

public static void stream(org.w3c.dom.Element el,
                          boolean validate,
                          java.lang.String enc,
                          java.io.OutputStream os)
                   throws XMLUtilsException

Streams the given DOM-(Sub)tree starting at the given Element into the returned byte-array.

Parameters:

el - a Element

enc - the encoding that shall be applied. The given String must conform to the encodings as set forth by the W3C and are somewhat different to that of Java.

validate - whether the given DOM-(sub)tree shall be validated against an XML-Schema that is referenced in the given element.

os - a OutputStream

Throws:

XMLUtilsException - if any error occurs

validate

public static boolean validate(org.w3c.dom.Element el)
                        throws XMLUtilsException

Validates the given element and it's decendants against the XML-Schema as specified in the given element. When validation has been succesfull true is returned but an exception if the document isnt valid, since this is in most cases the desired result anyways.

Unless someone finds a way to validate a life DOM-Tree against a given schema, the quickest way to do this is to, write the damn thing into an ByteArrayOutputStream and to read from that again, and while reading it perform a validation.

Parameters:

el - a Element

Returns:

a boolean

Throws:

XMLUtilsException - if any error occurs