net.sf.mmm.util.xml.api

Interface StaxUtil

All Known Implementing Classes:

StaxUtilImpl

@ComponentSpecification
public interface StaxUtil

This is the interface for a collection of utility functions that help to deal with the StAX API (JSR 173).

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

StaxUtilImpl

Method Summary

Modifier and Type	Method and Description
XMLEventReader	createXmlEventReader(InputStream inputStream) This method creates an XMLEventReader.
XMLStreamReader	createXmlStreamReader(DataResource resource, boolean xIncludeAware) This method creates an XMLStreamReader.
XMLStreamReader	createXmlStreamReader(InputStream inputStream) This method creates an XMLStreamReader.
XMLStreamWriter	createXmlStreamWriter(OutputStream out) This method creates a XMLStreamWriter.
XMLStreamWriter	createXmlStreamWriter(Writer writer) This method creates a XMLStreamWriter.
String	getEventTypeName(int eventType) This method gets the name for the given eventType.
XMLEvent	nextElement(XMLEventReader xmlReader) This method skips all events until a StartElement, EndElement or EndDocument is encountered.
<V> V	parseAttribute(XMLStreamReader xmlReader, String namespaceUri, String localAttributeName, Class<V> type) This method parses the attribute with the given localAttributeName from the given xmlReader as given by type.
<V> V	parseAttribute(XMLStreamReader xmlReader, String namespaceUri, String localAttributeName, Class<V> type, V defaultValue) This method parses the attribute with the given localAttributeName from the given xmlReader as given by type.
String	readText(XMLStreamReader xmlReader) This method reads the text at the current position of the given xmlReader .
void	skipOpenElement(XMLEventReader xmlReader) This method skips all events until the current element (tag) is closed.
void	skipOpenElement(XMLStreamReader xmlReader) This method skips all events until the current element (tag) is closed.

Method Detail

createXmlStreamReader

XMLStreamReader createXmlStreamReader(InputStream inputStream)
                               throws XmlException

This method creates an XMLStreamReader.

Parameters:

inputStream - is the InputStream to read from.

Returns:

the XMLStreamReader.

Throws:

XmlException - if the creation of the stream-reader failed (StAX not available or misconfigured).

See Also:

XMLInputFactory.createXMLStreamReader(InputStream)

createXmlStreamReader

XMLStreamReader createXmlStreamReader(DataResource resource,
                                      boolean xIncludeAware)
                               throws XmlException

This method creates an XMLStreamReader.

Parameters:

resource - is the DataResource to read from.

xIncludeAware - - true if XInclude should be supported, false otherwise.

Returns:

the XMLStreamReader.

Throws:

XmlException - if the creation of the stream-reader failed (StAX not available or misconfigured).

See Also:

XMLInputFactory.createXMLStreamReader(InputStream)

createXmlEventReader

XMLEventReader createXmlEventReader(InputStream inputStream)
                             throws XmlException

This method creates an XMLEventReader.

Parameters:

inputStream - is the InputStream to read from.

Returns:

the XMLEventReader.

Throws:

XmlException - if the creation of the event-reader failed (StAX not available or misconfigured).

See Also:

XMLInputFactory.createXMLEventReader(InputStream)

createXmlStreamWriter

XMLStreamWriter createXmlStreamWriter(OutputStream out)
                               throws XmlException

This method creates a XMLStreamWriter.

Parameters:

out - is the output stream where the XML will be written to.

Returns:

the XML stream writer.

Throws:

XmlException - if the creation of the stream-writer failed (StAX not available or misconfigured).

See Also:

XMLOutputFactory.createXMLStreamWriter(OutputStream)

createXmlStreamWriter

XMLStreamWriter createXmlStreamWriter(Writer writer)
                               throws XmlException

This method creates a XMLStreamWriter.

Parameters:

writer - is the writer where the XML will be written to.

Returns:

the XML stream writer.

Throws:

XmlException - if the creation of the stream-writer failed (StAX not available or misconfigured).

See Also:

XMLOutputFactory.createXMLStreamWriter(Writer)

parseAttribute

<V> V parseAttribute(XMLStreamReader xmlReader,
                     String namespaceUri,
                     String localAttributeName,
                     Class<V> type)
              throws ValueException

This method parses the attribute with the given localAttributeName from the given xmlReader as given by type.

Type Parameters:

V - is the generic for the type.

Parameters:

xmlReader - is where to read the XML from.

namespaceUri - is the URI representing the namespace of the requested attribute or null to ignore the namespace.

localAttributeName - is the local name of the requested attribute.

type - is the type the requested attribute should be converted to.

Returns:

the requested attribute as the given type.

Throws:

ValueException - if the attribute is NOT defined or its value can NOT be converted to type.

parseAttribute

<V> V parseAttribute(XMLStreamReader xmlReader,
                     String namespaceUri,
                     String localAttributeName,
                     Class<V> type,
                     V defaultValue)
              throws ValueException

This method parses the attribute with the given localAttributeName from the given xmlReader as given by type.

Type Parameters:

V - is the generic for the type.

Parameters:

xmlReader - is where to read the XML from.

namespaceUri - is the URI representing the namespace of the requested attribute or null to ignore the namespace.

localAttributeName - is the local name of the requested attribute.

type - is the type the requested attribute should be converted to.

defaultValue - is the default value returned if the requested attribute is NOT defined. It may be null .

Returns:

the requested attribute as the given type.

Throws:

ValueException - if the attribute value can NOT be converted to type.

readText

String readText(XMLStreamReader xmlReader)
         throws XmlGenericException

This method reads the text at the current position of the given xmlReader .
If the xmlReader is pointing to XMLStreamConstants.START_ELEMENT or XMLStreamConstants.ATTRIBUTE all attributes are skipped before. For XMLEventReader use XMLEventReader.getElementText().

Parameters:

xmlReader - is the XMLStreamReader to read the XML from.

Returns:

the text at the current position or null if there is no text to read (e.g. XMLStreamConstants.END_ELEMENT was hit).

Throws:

XmlGenericException - if an XMLStreamException was caused by the given xmlReader.

skipOpenElement

void skipOpenElement(XMLStreamReader xmlReader)
              throws XmlGenericException

This method skips all events until the current element (tag) is closed.
You can use this method if you hit an element you want to ignore. Here is a piece of code that shows an example that loops over all child elements of the current open element:

   ...
   while (xmlReader.nextTag() == XMLStreamConstants.START_ELEMENT) {
     String tagname = xmlReader.getLocalName();
     if (XML_TAG_FOO.equals(tagname)) {
       handleFoo(xmlReader);
     } else {
       // ignore all other tags
       staxUtil.skipOpenElement(xmlReader);
     }
   }
 

Parameters:

xmlReader - is the STaX reader currently pointing at or inside the element to skip. After the call of this method it will point to the end-element event of the element to skip. Calling XMLStreamReader.nextTag() will then point to start-element of the next sibling or to end-element of the parent.

Throws:

XmlGenericException - if an XMLStreamException was caused by the given xmlReader.

skipOpenElement

void skipOpenElement(XMLEventReader xmlReader)
              throws XmlGenericException

This method skips all events until the current element (tag) is closed.

Parameters:

xmlReader - is the STaX reader currently pointing at or inside the element to skip. After the call of this method it will point to the end-element event of the element to skip. Calling XMLEventReader.nextEvent() will then return the event after the EndElement-Event of the skipped element.

Throws:

XmlGenericException - if an XMLStreamException was caused by the given xmlReader.

See Also:

skipOpenElement(XMLStreamReader)

nextElement

XMLEvent nextElement(XMLEventReader xmlReader)
              throws XmlGenericException

This method skips all events until a StartElement, EndElement or EndDocument is encountered. Unlike XMLEventReader.nextTag() no exception is thrown according to unexpected events except if has no next event.

Parameters:

xmlReader - is the XMLEventReader to read the XML from.

Returns:

the according event.

Throws:

XmlGenericException - if an XMLStreamException was caused by the given xmlReader.

getEventTypeName

String getEventTypeName(int eventType)

This method gets the name for the given eventType.

Parameters:

eventType - is an event type constant declared in XMLStreamConstants.

Returns:

the according name.

See Also:

XMLStreamConstants