javanet.staxutils

Class XMLStreamUtils

java.lang.Object

javanet.staxutils.XMLStreamUtils

public class XMLStreamUtils
extends Object

Static utility methods useful when handling XML Streams.

Version:

$Revision: 1.8 $

Author:

Christian Niles

Constructor Summary

Constructors

Constructor and Description
XMLStreamUtils()

Method Summary

Methods

Modifier and Type	Method and Description
static String	attributeValue(XMLStreamReader reader, QName name) Returns the value of the attribute with the given name.
static String	attributeValue(XMLStreamReader reader, String name) Returns the value of the attribute with the given non-qualified name.
static void	copy(Source source, XMLEventWriter writer) Copies the content read from a TrAX Source to a StAX XMLEventWriter.
static void	copy(Source source, XMLStreamWriter writer) Copies the content read from a TrAX Source to a StAX XMLStreamWriter.
static void	copy(XMLEventReader reader, Result result) Copies the content read from a StAX XMLEventReader to a TrAX Result.
static void	copy(XMLEventReader reader, XMLEventConsumer consumer) Copies the content read from the specified source stream to the provided result stream.
static void	copy(XMLEventReader reader, XMLEventWriter writer) Copies the content read from the specified source stream to the provided result stream.
static void	copy(XMLStreamReader reader, Result result) Copies the content read from a StAX XMLStreamReader to a TrAX Result.
static void	copy(XMLStreamReader reader, XMLStreamWriter writer) Copies the content read from the specified source stream to the provided result stream.
static void	copy(XMLStreamReader reader, XMLStreamWriter writer, XMLInputFactory factory) Copies the content read from the specified source stream to the provided result stream.
static void	copyElement(XMLEventReader reader, XMLEventConsumer consumer) Copies an element and all its content from the provided event reader, to the provided event consumer.
static void	copyElementContent(XMLEventReader reader, XMLEventConsumer consumer) Copies all events within a StartElement until the matching EndElement is reached.
static String	getEventTypeName(int eventType) Returns the name of the specified stream event constant.
static StartElement	mergeAttributes(StartElement tag, Iterator attrs, XMLEventFactory factory) Constructs a new StartElement that merges the attributes and namespaces found in the specified StartElement, with the provided attributes.
static StartElement	nextElement(XMLEventReader reader) Reads the events from the provided event stream until either a start or end tag is encountered.
static StartElement	nextElement(XMLEventReader reader, QName name) Reads the events from the provided event stream until either a start or end tag is encountered.
static XMLEvent	nextTag(XMLEventReader reader) Advances the event stream until it encounters a start or end tag, but does not actaully read the event.
static String	readTextElement(XMLEventReader reader, QName elemName) Reads the text content of an element.
static void	requireElement(XMLStreamReader reader, QName name) Static utility method that throws an exception if the supplied reader's cursor doesn't point to a START_ELEMENT with the given name.
static void	requireStartElement(XMLEventReader reader, QName qname) Utility method that throws an exception if the provided reader is not positioned before a StartElement event with the specified tag name.
static void	skipElement(XMLEventReader reader) Skips all events within a single element, including its start and end tags.
static void	skipElement(XMLStreamReader reader) Skips the complete content of the element at the specified reader's cursor.
static void	skipElementContent(XMLEventReader reader) Skips all events within a StartElement until the matching EndElement is reached.
static void	skipElementContent(XMLStreamReader reader) Skips an element's complete content.

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

getEventTypeName

public static final String getEventTypeName(int eventType)

Returns the name of the specified stream event constant.

Parameters:

eventType - The event constant, such as XMLStreamConstants.START_DOCUMENT.

Returns:

The name of the specified event, or "UNKNOWN" if the constant isn't valid.

attributeValue

public static final String attributeValue(XMLStreamReader reader,
                    String name)

Returns the value of the attribute with the given non-qualified name.

Parameters:

reader - The xml stream reader

name - The name of the attribute.

Returns:

The value of the unqualified attribute, or null if the attribute wasn't present.

attributeValue

public static final String attributeValue(XMLStreamReader reader,
                    QName name)

Returns the value of the attribute with the given name.

Parameters:

reader - The xml stream reader

name - The name of the attribute.

Returns:

The value of the attribute, or null if the attribute wasn't present.

skipElement

public static final void skipElement(XMLEventReader reader)
                              throws XMLStreamException

Skips all events within a single element, including its start and end tags. The provided reader must be positioned directly in front of a StartElement event or it will have no effect. After this method completes, the reader will be positioned before the event following the end tag (the end tag will have been read).

Parameters:

reader - The event stream to read.

Throws:

XMLStreamException - If an error occurs reading events.

copyElement

public static final void copyElement(XMLEventReader reader,
               XMLEventConsumer consumer)
                              throws XMLStreamException

Copies an element and all its content from the provided event reader, to the provided event consumer. The event reader must be positioned before a start element event, or this method has no effect.

Parameters:

reader - The reader from which to read the events.

consumer - The destination for read events, or null to ignore all events.

Throws:

XMLStreamException - If an error occurs reading or writing the events.

skipElementContent

public static final void skipElementContent(XMLEventReader reader)
                                     throws XMLStreamException

Skips all events within a StartElement until the matching EndElement is reached. This method assumes that the reader is positioned after the StartElement event, and when the method completes, the stream will be positioned before the EndElement event, but it will not consume the end tag.

Parameters:

reader - The event stream to read, positioned after the StartElement

Throws:

XMLStreamException - If an error occurs reading events.

copyElementContent

public static final void copyElementContent(XMLEventReader reader,
                      XMLEventConsumer consumer)
                                     throws XMLStreamException

Copies all events within a StartElement until the matching EndElement is reached. This method assumes that the reader is positioned after the StartElement event, and when the method completes, the stream will be positioned before the EndElement event, but it will not consume the end tag.

Parameters:

reader - The event stream to read, positioned after the StartElement

consumer - The destination for events read from teh stream, or null to ignore the events completely.

Throws:

XMLStreamException - If an error occurs reading events.

skipElement

public static final void skipElement(XMLStreamReader reader)
                              throws XMLStreamException

Skips the complete content of the element at the specified reader's cursor. The reader's current event type must be START_ELEMENT, otherwise this method will have no effect. Upon completion, the reader's cursor will be at the END_ELEMENT event for the skipped element.

Parameters:

reader - An XML stream reader currently in the START_ELEMENT event.

Throws:

XMLStreamException

skipElementContent

public static final void skipElementContent(XMLStreamReader reader)
                                     throws XMLStreamException

Skips an element's complete content. This method assumes that the START_ELEMENT has already be passed, and when it terminates, the stream will be positioned at the END_ELEMENT.

Parameters:

reader - The stream reader to read.

Throws:

XMLStreamException - If an error occurs reading the stream.

requireElement

public static final void requireElement(XMLStreamReader reader,
                  QName name)
                                 throws XMLStreamException

Static utility method that throws an exception if the supplied reader's cursor doesn't point to a START_ELEMENT with the given name.

Parameters:

reader - The reader to test.

name - The name of the element to require.

Throws:

XMLStreamException - If the reader state is an element with the specified name.

copy

public static final void copy(XMLEventReader reader,
        XMLEventConsumer consumer)
                       throws XMLStreamException

Copies the content read from the specified source stream to the provided result stream. This method is exactly the same as calling XMLEventWriter.add(XMLEventReader), and is provided only for completeness.

Parameters:

reader - The source stream.

consumer - The destination stream.

Throws:

XMLStreamException - If an error occurs copying the stream contents.

copy

public static final void copy(XMLEventReader reader,
        XMLEventWriter writer)
                       throws XMLStreamException

Copies the content read from the specified source stream to the provided result stream. This method is exactly the same as calling XMLEventWriter.add(XMLEventReader), and is provided only for completeness.

Parameters:

reader - The source stream.

writer - The destination stream.

Throws:

XMLStreamException - If an error occurs copying the stream contents.

copy

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

Copies the content read from the specified source stream to the provided result stream.

Parameters:

reader - The source stream.

writer - The destination stream.

Throws:

XMLStreamException - If an error occurs copying the stream contents.

copy

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

Copies the content read from the specified source stream to the provided result stream.

Parameters:

reader - The source stream.

writer - The destination stream.

factory - An optional input factory used to create any intermediate streams.

Throws:

XMLStreamException - If an error occurs copying the stream contents.

copy

public static final void copy(Source source,
        XMLStreamWriter writer)
                       throws XMLStreamException

Copies the content read from a TrAX Source to a StAX XMLStreamWriter.

Parameters:

source - The content source.

writer - The destination stream.

Throws:

XMLStreamException - If an error occurs copying the content to the stream.

copy

public static final void copy(Source source,
        XMLEventWriter writer)
                       throws XMLStreamException

Copies the content read from a TrAX Source to a StAX XMLEventWriter.

Parameters:

source - The content source.

writer - The destination event stream.

Throws:

XMLStreamException - If an error occurs copying the content to the event stream.

copy

public static final void copy(XMLEventReader reader,
        Result result)
                       throws XMLStreamException

Copies the content read from a StAX XMLEventReader to a TrAX Result.

Parameters:

reader - The source event stream.

result - The destination Result.

Throws:

XMLStreamException - If an error occurs copying the content to the result.

copy

public static final void copy(XMLStreamReader reader,
        Result result)
                       throws XMLStreamException

Copies the content read from a StAX XMLStreamReader to a TrAX Result.

Parameters:

reader - The source stream.

result - The destination Result.

Throws:

XMLStreamException - If an error occurs copying the content to the result.

requireStartElement

public static final void requireStartElement(XMLEventReader reader,
                       QName qname)
                                      throws XMLStreamException

Utility method that throws an exception if the provided reader is not positioned before a StartElement event with the specified tag name.

Parameters:

reader - The reader to test.

qname - The required name of the start-tag. If null, any start tag is accepted.

Throws:

XMLStreamException - If an error occurs reading from the stream.

mergeAttributes

public static StartElement mergeAttributes(StartElement tag,
                           Iterator attrs,
                           XMLEventFactory factory)

Constructs a new StartElement that merges the attributes and namespaces found in the specified StartElement, with the provided attributes. The returned StartElement will contain all the attributes and namespaces of the original, plus those defined in the map.

Parameters:

tag - The original StartElement

attrs - An iterator of Atributes to add to the element.

Returns:

A new StartElement that contains all the original attributes and namespaces, plus the provided attributes.

readTextElement

public static final String readTextElement(XMLEventReader reader,
                     QName elemName)
                                    throws XMLStreamException

Reads the text content of an element. The reader should be positioned in front of a StartElement event, and will be read up to and including the end element tag.

Parameters:

reader - The event stream from which to read the element text.

elemName - The optional name of the element being read. If this paramter is non- null then an exception will be thrown if the element read doesn't have the same name.

Returns:

The text read from the element.

Throws:

XMLStreamException - If an error occurs reading the stream, or if the read element doesn't match the provided QName.

nextTag

public static final XMLEvent nextTag(XMLEventReader reader)
                              throws XMLStreamException

Advances the event stream until it encounters a start or end tag, but does not actaully read the event.

Parameters:

reader - The reader to peek.

Returns:

The next StartElement or EndElement event, retrieved using peek(), or null if the end of the stream was encountered before any tag event.

Throws:

XMLStreamException - If an error occurs reading the stream.

nextElement

public static final StartElement nextElement(XMLEventReader reader)
                                      throws XMLStreamException

Reads the events from the provided event stream until either a start or end tag is encountered. In the former case, the start tag will be returned, but if an end tag is encountered, null will be returned. After returning, the stream will be positioned just before the returned start element. The start element will not be consumed by this method.

Parameters:

reader - The event stream from which to read.

Returns:

The StartElement read from the stream, or null if an end tag was found first, or the stream ended before a start element was found.

Throws:

XMLStreamException - If an error occurs reading the stream.

nextElement

public static final StartElement nextElement(XMLEventReader reader,
                       QName name)
                                      throws XMLStreamException

Reads the events from the provided event stream until either a start or end tag is encountered. In the former case, the start tag will be returned if it matches the specified QName, but if it doesn't match, an end tag is encountered, or the stream ends, null will be returned. After returning, the stream will be positioned just before the start element. The start element will not be consumed by this method.

Parameters:

reader - The event stream from which to read.

name - The name of the element to read, or null to read any start tag.

Returns:

The StartElement read from the stream, or null if the encountered start tag didn't match the specified QName, an end tag was found first, or the stream ended before a start element was found.

Throws:

XMLStreamException - If an error occurs reading the stream.