org.deegree.commons.xml.stax
Class XMLStreamUtils

java.lang.Object
  org.deegree.commons.xml.stax.XMLStreamUtils

public class XMLStreamUtils
extends Object

General XML stream manipulation utilities.

This class provides static utility methods for operations on XMLStreamReaders / XMLStreamWriters.

Version:

$Revision: 31888 $, $Date: 2011-09-15 14:29:09 +0200 (Thu, 15 Sep 2011) $

Author:

Markus Schneider, last edited by: $Author: lbuesching $

Constructor Summary

XMLStreamUtils()

Method Summary

static QName	asQName(XMLStreamReader xmlStream, String s)
static void	copy(XMLStreamWriter writer, XMLStreamReader reader) Copies an XML element (including all attributes and subnodes) from the given XMLStreamReader to the given XMLStreamWriter.
static Document	getAsDocument(XMLStreamReader xmlStreamReader) makes a Document out of a XMLStreamReader
static Map<QName,String>	getAttributes(XMLStreamReader reader) Returns the attributes of the element that the given XMLStreamReader points to.
static String	getAttributeValue(XMLStreamReader xmlStream, String localName)
static boolean	getAttributeValueAsBoolean(XMLStreamReader xmlStream, String namespaceURI, String localName, boolean defaultValue)
static QName	getAttributeValueAsQName(XMLStreamReader xmlStream, String namespaceURI, String localName, QName defaultValue)
static String	getCurrentEventInfo(XMLStreamReader xmlStream) Creates printable (debug) information about the event that the cursor of the given XMLStreamReader currently points at.
static boolean	getElementTextAsBoolean(XMLStreamReader xmlStream)
static boolean	getElementTextAsBoolean(XMLStreamReader reader, QName elementName, boolean defaultValue, boolean nextElemOnSucces) Post: reader will be unchanged or at XMLStreamConstants.END_ELEMENT of the matching element or at #START_ELEMENT of the next element if requested.
static double	getElementTextAsDouble(XMLStreamReader reader, QName elementName, double defaultValue, boolean nextElemOnSucces) Post: reader will be unchanged or on success at #END_ELEMENT of the matching element or at #START_ELEMENT of the next element if requested.
static int	getElementTextAsInteger(XMLStreamReader reader, QName elementName, int defaultValue, boolean nextElemOnSucces) Post: reader will be unchanged or on success at #END_ELEMENT of the matching element or at #START_ELEMENT of the next element if requested.
static QName	getElementTextAsQName(XMLStreamReader xmlStream)
static String	getEventTypeString(int eventType)
static String	getRequiredAttributeValue(XMLStreamReader xmlStream, String localName)
static String	getRequiredAttributeValue(XMLStreamReader xmlStream, String namespaceURI, String localName)
static boolean	getRequiredAttributeValueAsBoolean(XMLStreamReader xmlStream, String namespaceURI, String localName)
static QName	getRequiredAttributeValueAsQName(XMLStreamReader xmlStream, String namespaceURI, String localName)
static double	getRequiredElementTextAsDouble(XMLStreamReader reader, QName elementName, boolean nextElemOnSucces) Returns the text in the required element as a double.
static String	getRequiredText(XMLStreamReader reader, QName elementName, boolean nextElemOnSucces) Get the text of the given element which must be an element with given name.
static String[]	getSimpleUnboundedAsStrings(XMLStreamReader reader, QName name) The reader must be on a StartElement, any attributes will be skipped.
static String	getText(XMLStreamReader reader, QName elemName, String defaultText, boolean nextElemOnSucces) Get the text of the element or if the reader does not match the given elementName the default text will be returned.
static boolean	moveReaderToFirstMatch(XMLStreamReader reader, Collection<QName> alowedElements) Move the reader to the first element which matches one of the given name(s).
static boolean	moveReaderToFirstMatch(XMLStreamReader reader, QName elementName) Move the reader to the first element which matches the given name.
static int	nextElement(XMLStreamReader xmlReader) Move the reader to the next #START_ELEMENT or #END_ELEMENT event.
static void	require(XMLStreamReader xmlStream, int eventType)
static void	requireNextTag(XMLStreamReader xmlStream, int eventType)
static void	requireStartElement(XMLStreamReader xmlStream, Collection<QName> expectedElements)
static URL	resolve(String url, XMLStreamReader in)
static StreamBufferStore	serialize(XMLStreamReader reader) Serializes the XML element (including all attributes and subnodes) from the given XMLStreamReader into a StreamBufferStore.
static void	skipElement(XMLStreamReader xmlStream) Skips all events that belong to the current element (including descendant elements), so that the XMLStreamReader cursor points at the corresponding END_ELEMENT event.
static void	skipRequiredElement(XMLStreamReader reader, QName elementName) Skips to the next element if the reader points the required element.
static void	skipStartDocument(XMLStreamReader xmlStream)

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLStreamUtils

public XMLStreamUtils()

Method Detail

getCurrentEventInfo

public static final String getCurrentEventInfo(XMLStreamReader xmlStream)

Creates printable (debug) information about the event that the cursor of the given XMLStreamReader currently points at.

Parameters:

xmlStream -

Returns:

printable information

skipElement

public static void skipElement(XMLStreamReader xmlStream)
                        throws XMLStreamException

Skips all events that belong to the current element (including descendant elements), so that the XMLStreamReader cursor points at the corresponding END_ELEMENT event.

Parameters:

xmlStream -

Throws:

XMLStreamException

resolve

public static URL resolve(String url,
                          XMLStreamReader in)
                   throws MalformedURLException

Parameters:

url -

in -

Returns:

a resolved URL against the systemid of the reader

Throws:

MalformedURLException

asQName

public static QName asQName(XMLStreamReader xmlStream,
                            String s)

Parameters:

xmlStream -

s - may not be null

Returns:

a parsed qname

skipStartDocument

public static void skipStartDocument(XMLStreamReader xmlStream)
                              throws XMLStreamException

Throws:

XMLStreamException

getAttributeValue

public static String getAttributeValue(XMLStreamReader xmlStream,
                                       String localName)
                                throws XMLParsingException

Throws:

XMLParsingException

getRequiredAttributeValue

public static String getRequiredAttributeValue(XMLStreamReader xmlStream,
                                               String localName)
                                        throws XMLParsingException

Throws:

XMLParsingException

getRequiredAttributeValue

public static String getRequiredAttributeValue(XMLStreamReader xmlStream,
                                               String namespaceURI,
                                               String localName)
                                        throws XMLParsingException

Throws:

XMLParsingException

getRequiredAttributeValueAsQName

public static QName getRequiredAttributeValueAsQName(XMLStreamReader xmlStream,
                                                     String namespaceURI,
                                                     String localName)
                                              throws XMLParsingException

Throws:

XMLParsingException

getAttributeValueAsQName

public static QName getAttributeValueAsQName(XMLStreamReader xmlStream,
                                             String namespaceURI,
                                             String localName,
                                             QName defaultValue)
                                      throws XMLParsingException

Throws:

XMLParsingException

getElementTextAsBoolean

public static boolean getElementTextAsBoolean(XMLStreamReader xmlStream)
                                       throws XMLStreamException

Parameters:

xmlStream -

Returns:

the element text as boolean

Throws:

XMLStreamException

getElementTextAsBoolean

public static boolean getElementTextAsBoolean(XMLStreamReader reader,
                                              QName elementName,
                                              boolean defaultValue,
                                              boolean nextElemOnSucces)
                                       throws XMLStreamException

Post: reader will be unchanged or at XMLStreamConstants.END_ELEMENT of the matching element or at #START_ELEMENT of the next element if requested.

Parameters:

reader -

elementName -

defaultValue -

nextElemOnSucces - if true the reader will be moved to the next tag if the retrieval was successful.

Returns:

the element text as boolean

Throws:

XMLStreamException

getAttributeValueAsBoolean

public static boolean getAttributeValueAsBoolean(XMLStreamReader xmlStream,
                                                 String namespaceURI,
                                                 String localName,
                                                 boolean defaultValue)
                                          throws XMLParsingException

Throws:

XMLParsingException

getElementTextAsQName

public static QName getElementTextAsQName(XMLStreamReader xmlStream)
                                   throws XMLParsingException,
                                          XMLStreamException

Throws:

XMLParsingException

XMLStreamException

requireStartElement

public static void requireStartElement(XMLStreamReader xmlStream,
                                       Collection<QName> expectedElements)
                                throws XMLParsingException

Throws:

XMLParsingException

require

public static void require(XMLStreamReader xmlStream,
                           int eventType)
                    throws XMLParsingException

Throws:

XMLParsingException

requireNextTag

public static void requireNextTag(XMLStreamReader xmlStream,
                                  int eventType)
                           throws XMLParsingException,
                                  XMLStreamException

Throws:

XMLParsingException

XMLStreamException

getEventTypeString

public static final String getEventTypeString(int eventType)

getRequiredAttributeValueAsBoolean

public static boolean getRequiredAttributeValueAsBoolean(XMLStreamReader xmlStream,
                                                         String namespaceURI,
                                                         String localName)

getText

public static String getText(XMLStreamReader reader,
                             QName elemName,
                             String defaultText,
                             boolean nextElemOnSucces)
                      throws XMLStreamException

Get the text of the element or if the reader does not match the given elementName the default text will be returned. Post: reader will be unchanged or at XMLStreamConstants.END_ELEMENT of the matching element or at #START_ELEMENT of the next element if requested.

Parameters:

reader -

elemName -

defaultText -

nextElemOnSucces - if true the reader will be moved to the next tag if the retrieval was successful.

Returns:

the text of the element or if the reader does not match the given elementName the default text will be returned.

Throws:

XMLStreamException

skipRequiredElement

public static void skipRequiredElement(XMLStreamReader reader,
                                       QName elementName)
                                throws XMLStreamException

Skips to the next element if the reader points the required element. Post: reader will be at XMLStreamConstants.START_ELEMENT of the next element.

Parameters:

reader -

elementName -

Throws:

XMLStreamException

getRequiredText

public static String getRequiredText(XMLStreamReader reader,
                                     QName elementName,
                                     boolean nextElemOnSucces)
                              throws XMLStreamException

Get the text of the given element which must be an element with given name. Post: reader will be at XMLStreamConstants.END_ELEMENT of matching element or at #START_ELEMENT of the next element if requested.

Parameters:

reader -

elementName -

nextElemOnSucces - if true the reader will be moved to the next tag if the retrieval was successful.

Returns:

the text of the current 'required' element.

Throws:

XMLStreamException

getSimpleUnboundedAsStrings

public static String[] getSimpleUnboundedAsStrings(XMLStreamReader reader,
                                                   QName name)
                                            throws XMLStreamException

The reader must be on a StartElement, any attributes will be skipped. Post: reader will be unchanged or at XMLStreamConstants.START_ELEMENT of the first element after the last matching element

Parameters:

reader -

name - of the elements

Returns:

an array of strings, denoting the elements with the given name.

Throws:

XMLStreamException

nextElement

public static int nextElement(XMLStreamReader xmlReader)
                       throws XMLStreamException,
                              NoSuchElementException

Move the reader to the next #START_ELEMENT or #END_ELEMENT event.

Parameters:

xmlReader -

Returns:

event type

Throws:

XMLStreamException

NoSuchElementException - if the end of the document is reached

getElementTextAsDouble

public static double getElementTextAsDouble(XMLStreamReader reader,
                                            QName elementName,
                                            double defaultValue,
                                            boolean nextElemOnSucces)
                                     throws XMLStreamException

Post: reader will be unchanged or on success at #END_ELEMENT of the matching element or at #START_ELEMENT of the next element if requested.

Parameters:

reader - pointing to the current element.

elementName - of the current element.

defaultValue - to return if the current name was not the one given or the value could not be parsed as a double.

nextElemOnSucces - if true the reader will be moved to the next tag if the retrieval was successful.

Returns:

the text of the current element (which should have element name) parsed as a double.

Throws:

XMLStreamException - from XMLStreamReader.getElementText().

getElementTextAsInteger

public static int getElementTextAsInteger(XMLStreamReader reader,
                                          QName elementName,
                                          int defaultValue,
                                          boolean nextElemOnSucces)
                                   throws XMLStreamException

Post: reader will be unchanged or on success at #END_ELEMENT of the matching element or at #START_ELEMENT of the next element if requested.

Parameters:

reader - pointing to the current element.

elementName - of the current element.

defaultValue - to return if the current name was not the one given or the value could not be parsed as a integer.

nextElemOnSucces - if true the reader will be moved to the next tag if the retrieval was successful.

Returns:

the text of the current element (which should have element name) parsed as a integer.

Throws:

XMLStreamException - from XMLStreamReader.getElementText().

getRequiredElementTextAsDouble

public static double getRequiredElementTextAsDouble(XMLStreamReader reader,
                                                    QName elementName,
                                                    boolean nextElemOnSucces)
                                             throws XMLStreamException

Returns the text in the required element as a double. If the name of the reader does not match the given qName, an exception will be thrown. If the value is not a double, an exception will be thrown. Post: reader will be unchanged or at #END_ELEMENT of the matching element or at #START_ELEMENT of the next element if requested.

Parameters:

reader -

elementName -

nextElemOnSucces - if true the reader will be move to the next element if the operation was successful.

Returns:

the double value of the required element.

Throws:

XMLStreamException

moveReaderToFirstMatch

public static boolean moveReaderToFirstMatch(XMLStreamReader reader,
                                             QName elementName)
                                      throws XMLStreamException

Move the reader to the first element which matches the given name. The reader will be positioned on the XMLStreamConstants.START_ELEMENT event or after the XMLStreamConstants.END_DOCUMENT which ever comes first.

Parameters:

reader - to position

elementName - name of the element to move forward to.

Returns:

true if the reader is on the given element, false otherwise.

Throws:

XMLStreamException

moveReaderToFirstMatch

public static boolean moveReaderToFirstMatch(XMLStreamReader reader,
                                             Collection<QName> alowedElements)
                                      throws XMLStreamException

Move the reader to the first element which matches one of the given name(s). The reader will be positioned on the XMLStreamConstants.START_ELEMENT event or after the XMLStreamConstants.END_DOCUMENT which ever comes first.

Parameters:

reader - to position

alowedElements - name of the element to move forward to.

Returns:

true if the reader is on the given element, false otherwise.

Throws:

XMLStreamException

getAttributes

public static Map<QName,String> getAttributes(XMLStreamReader reader)

Returns the attributes of the element that the given XMLStreamReader points to.

Parameters:

reader - xml stream, must not be null and point to a XMLStreamConstants.START_ELEMENT

Returns:

attributes of the element, can be empty, but never null

getAsDocument

public static Document getAsDocument(XMLStreamReader xmlStreamReader)
                              throws XMLStreamException,
                                     FactoryConfigurationError,
                                     ParserConfigurationException,
                                     SAXException,
                                     IOException

makes a Document out of a XMLStreamReader

Parameters:

xmlStreamReader - the xmlStreamRader to convert

Returns:

the xmlStreamRader as Document

Throws:

FactoryConfigurationError

XMLStreamException

ParserConfigurationException

IOException

SAXException

copy

public static void copy(XMLStreamWriter writer,
                        XMLStreamReader reader)
                 throws XMLStreamException

Copies an XML element (including all attributes and subnodes) from the given XMLStreamReader to the given XMLStreamWriter.

Parameters:

writer - XMLStreamWriter that the xml is appended to

reader - cursor must point at a START_ELEMENT event and points at the corresponding END_ELEMENT event afterwards

Throws:

XMLStreamException

serialize

public static StreamBufferStore serialize(XMLStreamReader reader)
                                   throws IOException,
                                          XMLStreamException,
                                          FactoryConfigurationError

Serializes the XML element (including all attributes and subnodes) from the given XMLStreamReader into a StreamBufferStore.

Parameters:

reader - cursor must point at a START_ELEMENT event and points at the corresponding END_ELEMENT event afterwards

Returns:

stored document, never null

Throws:

IOException

FactoryConfigurationError

XMLStreamException