org.schmant.support.xml.stax
Class StAXSupport

java.lang.Object
  org.schmant.support.xml.stax.StAXSupport

public final class StAXSupport
extends Object

This is a support class for StAX XML parsing.

Since:

0.5

Author:

Karl Gustafsson

Method Summary

static void	assertEndElementEvent(XMLEvent xe, String elementName) Assert that the event is an end element event for the specified XML tag name.
static void	assertEventOfType(XMLEvent xe, Class<? extends XMLEvent> c) Assert that the event is of the specified type.
static void	assertStartElementEvent(XMLEvent xe, String elementName) Assert that the event is a start element event for the specified XML tag name.
static StartElement	findElementInScope(XMLEventReader r, QName scope, QName... elements) Search for any of the named elements within the scope of an element.
static StartElement	findElementInScope(XMLEventReader r, String scope, String... localNames) Search for any of the named elements within the scope of an element.
static StartElement	findElementInScopeOrNull(XMLEventReader r, QName scope, QName... elements) Search for any of the named elements within the scope of an element, returning null if no such element was found.
static StartElement	findElementInScopeOrNull(XMLEventReader r, String scope, String... localNames) Search for any of the named elements within the scope of an element, returning null if no such element was found.
static String	getAttribute(StartElement se, String attributeName) Get the named attribute.
static String	getAttributeOrNull(StartElement se, String attributeName) Get the named attribute if it exists.
static String	getElementText(XMLEventReader xer, QName elementName) Get the text from the next occurrence of the named element.
static String	getElementText(XMLEventReader xer, String localPart) Get the text from the next occurrence of the named element.
static XMLEvent	getNextEvent(XMLEventReader xer) Get the next interesting event (comments are ignored).
static XMLEvent	getNextEventIgnoreCharacters(XMLEventReader xer) Get the next non-comment and non-characters event.
static XMLEvent	getNextEventOrNull(XMLEventReader xer) Get the next event, returning null if the end of the XML stream is reached.
static StartElement	getNextStartElement(XMLEventReader xer) Get the next StartElement event.
static StartElement	getNextStartElementOrNull(XMLEventReader xer) Get the next start element, returning null if the end of the file is encountered.
static String	getNextText(XMLEventReader xer) Get the next text.
static StartElement	goToElement(XMLEventReader xer, QName name) Go to the next occurrence of the named element.
static StartElement	goToElement(XMLEventReader xer, String localName) Go to the next occurrence of the named element.
static StartElement	goToElementOrNull(XMLEventReader xer, QName name) Go to the next occurrence of the named element.
static StartElement	goToElementOrNull(XMLEventReader xer, String localName) Go to the next occurrence of the named element.
static XMLEvent	goToEvent(XMLEventReader r, int... eventTypes) Go to the next event that is of any of the supplied event types.
static XMLEvent	goToEventOrNull(XMLEventReader r, int... eventTypes) Go to the next event that is of any of the supplied event types.
static boolean	isEventOfType(XMLEvent xe, Class<? extends XMLEvent> c) Check if the StAX event is of the supplied type.

Methods inherited from class java.lang.Object

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

Method Detail

getNextEventOrNull

public static XMLEvent getNextEventOrNull(XMLEventReader xer)
                                   throws XMLStreamException

Get the next event, returning null if the end of the XML stream is reached. Comments are skipped and not returned.

Parameters:

xer - The event reader.

Returns:

The next non-comment event, or null if at EOF.

Throws:

XMLStreamException - On errors.

getNextEvent

public static XMLEvent getNextEvent(XMLEventReader xer)
                             throws XMLStreamException,
                                    SchmantException

Get the next interesting event (comments are ignored).

Parameters:

xer - The event reader.

Returns:

The next non-comment event.

Throws:

XMLStreamException - On errors.

SchmantException - If EOF is reached.

getNextEventIgnoreCharacters

public static XMLEvent getNextEventIgnoreCharacters(XMLEventReader xer)
                                             throws XMLStreamException,
                                                    SchmantException

Get the next non-comment and non-characters event.

Parameters:

xer - The event reader.

Returns:

The next non-comment and non-characters event.

Throws:

XMLStreamException - On errors.

SchmantException - If EOF is reached.

goToEventOrNull

public static XMLEvent goToEventOrNull(XMLEventReader r,
                                       int... eventTypes)
                                throws XMLStreamException

Go to the next event that is of any of the supplied event types.

Parameters:

r - The event reader.

eventTypes - The event types to look for.

Returns:

The event found or null if none of the events were found before the end of the document.

Throws:

XMLStreamException - On errors.

goToEvent

public static XMLEvent goToEvent(XMLEventReader r,
                                 int... eventTypes)
                          throws XMLStreamException,
                                 SchmantException

Go to the next event that is of any of the supplied event types.

Parameters:

r - The event reader.

eventTypes - The event types to look for.

Returns:

The event found.

Throws:

XMLStreamException - On errors.

SchmantException - If none of the event types were found before the end of the document.

getNextStartElementOrNull

public static StartElement getNextStartElementOrNull(XMLEventReader xer)
                                              throws XMLStreamException

Get the next start element, returning null if the end of the file is encountered.

Parameters:

xer - The event reader.

Returns:

The start element, or null if at EOF.

Throws:

XMLStreamException - On errors.

getNextStartElement

public static StartElement getNextStartElement(XMLEventReader xer)
                                        throws XMLStreamException,
                                               SchmantException

Get the next StartElement event.

Parameters:

xer - The event reader.

Returns:

The next StartElement event.

Throws:

XMLStreamException - On errors.

SchmantException - If EOF is reached.

goToElement

public static StartElement goToElement(XMLEventReader xer,
                                       QName name)
                                throws XMLStreamException,
                                       SchmantException

Go to the next occurrence of the named element.

Parameters:

xer - The event reader.

name - The name of the element.

Returns:

The StartElement for the element.

Throws:

XMLStreamException - On errors.

SchmantException - If EOF is reached before the element is found.

goToElement

public static StartElement goToElement(XMLEventReader xer,
                                       String localName)
                                throws XMLStreamException,
                                       SchmantException

Go to the next occurrence of the named element.

Parameters:

xer - The event reader.

localName - The local name of the element.

Returns:

The StartElement for the element.

Throws:

XMLStreamException - On errors.

SchmantException - If EOF is reached before the element is found.

goToElementOrNull

public static StartElement goToElementOrNull(XMLEventReader xer,
                                             QName name)
                                      throws XMLStreamException

Go to the next occurrence of the named element.

Parameters:

xer - The event reader.

name - The name of the element.

Returns:

The StartElement for the element or null if EOF is found without finding the element.

Throws:

XMLStreamException - On errors.

goToElementOrNull

public static StartElement goToElementOrNull(XMLEventReader xer,
                                             String localName)
                                      throws XMLStreamException

Go to the next occurrence of the named element.

Parameters:

xer - The event reader.

localName - The local name of the element.

Returns:

The StartElement for the element or null if EOF is found without finding the element.

Throws:

XMLStreamException - On errors.

getNextText

public static String getNextText(XMLEventReader xer)
                          throws XMLStreamException,
                                 SchmantException

Get the next text.

Parameters:

xer - The event reader.

Returns:

The next text.

Throws:

XMLStreamException - On errors.

SchmantException - If EOF is reached.

getElementText

public static String getElementText(XMLEventReader xer,
                                    QName elementName)
                             throws XMLStreamException,
                                    SchmantException

Get the text from the next occurrence of the named element. The element must be text only, otherwise strange things may happen.

Parameters:

xer - The event reader.

elementName - The element name.

Returns:

The text from the element.

Throws:

XMLStreamException - On errors.

SchmantException - If EOF is reached.

See Also:

getElementText(XMLEventReader, String)

getElementText

public static String getElementText(XMLEventReader xer,
                                    String localPart)
                             throws XMLStreamException,
                                    SchmantException

Get the text from the next occurrence of the named element. The name does only have a local part.

The element must be text only, otherwise strange things may happen.

Parameters:

xer - The event reader.

localPart - The element name.

Returns:

The text from the element.

Throws:

XMLStreamException - On errors.

SchmantException - If EOF is reached.

See Also:

getElementText(XMLEventReader, QName)

isEventOfType

public static boolean isEventOfType(XMLEvent xe,
                                    Class<? extends XMLEvent> c)

Check if the StAX event is of the supplied type.

Parameters:

xe - The event.

c - The type.

Returns:

true if the event is of the specified type.

assertEventOfType

public static void assertEventOfType(XMLEvent xe,
                                     Class<? extends XMLEvent> c)
                              throws SchmantException

Assert that the event is of the specified type.

Parameters:

xe - The StAX event.

c - The type.

Throws:

SchmantException - If the event is of any other type.

assertStartElementEvent

public static void assertStartElementEvent(XMLEvent xe,
                                           String elementName)
                                    throws SchmantException

Assert that the event is a start element event for the specified XML tag name.

Parameters:

xe - The event.

elementName - The tag name.

Throws:

SchmantException - If the event is of any other type or if it is a start event for any other tag.

assertEndElementEvent

public static void assertEndElementEvent(XMLEvent xe,
                                         String elementName)
                                  throws SchmantException

Assert that the event is an end element event for the specified XML tag name.

Parameters:

xe - The event.

elementName - The tag name.

Throws:

SchmantException - If the event is of any other type or if it is a end event for any other tag.

findElementInScopeOrNull

public static StartElement findElementInScopeOrNull(XMLEventReader r,
                                                    QName scope,
                                                    QName... elements)
                                             throws XMLStreamException

Search for any of the named elements within the scope of an element, returning null if no such element was found.

Parameters:

r - The stream reader.

scope - The name of the scope.

elements - The names of elements to look for.

Returns:

The name of the found element or null if the end tag for the scope was found without finding any of the elements.

Throws:

XMLStreamException - On parsing errors from the underlying StAX parser

findElementInScope

public static StartElement findElementInScope(XMLEventReader r,
                                              QName scope,
                                              QName... elements)
                                       throws XMLStreamException,
                                              SchmantException

Search for any of the named elements within the scope of an element.

Parameters:

r - The stream reader.

scope - The name of the scope.

elements - The names of elements to look for.

Returns:

The name of the found element.

Throws:

XMLStreamException - On parsing errors from the underlying StAX parser

SchmantException - If none of the elements were found in the given scope.

findElementInScopeOrNull

public static StartElement findElementInScopeOrNull(XMLEventReader r,
                                                    String scope,
                                                    String... localNames)
                                             throws XMLStreamException

Search for any of the named elements within the scope of an element, returning null if no such element was found.

Parameters:

r - The stream reader.

scope - The name of the scope.

localNames - The names of elements to look for.

Returns:

The name of the found element or null if the end tag for the scope was found without finding any of the elements.

Throws:

XMLStreamException - On parsing errors from the underlying StAX parser

findElementInScope

public static StartElement findElementInScope(XMLEventReader r,
                                              String scope,
                                              String... localNames)
                                       throws XMLStreamException,
                                              SchmantException

Search for any of the named elements within the scope of an element.

Parameters:

r - The stream reader.

scope - The name of the scope.

localNames - The names of elements to look for.

Returns:

The name of the found element.

Throws:

XMLStreamException - On parsing errors from the underlying StAX parser

SchmantException - If none of the elements were found in the given scope.

getAttributeOrNull

public static String getAttributeOrNull(StartElement se,
                                        String attributeName)

Get the named attribute if it exists.

Parameters:

se - The start element event to get the attribute from.

attributeName - The attribute name.

Returns:

The value of the attribute, or null if the attribute does not exist.

getAttribute

public static String getAttribute(StartElement se,
                                  String attributeName)
                           throws SchmantException

Get the named attribute.

Parameters:

se - The start element event to get the attribute from.

attributeName - The attribute name.

Returns:

The value of the attribute.

Throws:

SchmantException - If the attribute does not exist.