net.sf.mmm.util.xml.base
Class StaxUtilImpl

java.lang.Object
  net.sf.mmm.util.component.base.AbstractComponent
      net.sf.mmm.util.component.base.AbstractLoggableComponent
          net.sf.mmm.util.xml.base.StaxUtilImpl

All Implemented Interfaces:

StaxUtil

@Singleton
@Named
public final class StaxUtilImpl
extends AbstractLoggableComponent
implements StaxUtil

This utility class contains methods that help to work with the StAX API (JSR 173).

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

private static StaxUtil	instance
private StringValueConverter	valueConverter
private javax.xml.stream.XMLInputFactory	xmlInputFactory
private javax.xml.stream.XMLOutputFactory	xmlOutputFactory

Constructor Summary

StaxUtilImpl()
The constructor.

Method Summary

javax.xml.stream.XMLEventReader	createXmlEventReader(InputStream inputStream) This method creates an XMLEventReader.
javax.xml.stream.XMLStreamReader	createXmlStreamReader(InputStream inputStream) This method creates an XMLStreamReader.
javax.xml.stream.XMLStreamWriter	createXmlStreamWriter(OutputStream out) This method creates a XMLStreamWriter.
javax.xml.stream.XMLStreamWriter	createXmlStreamWriter(Writer writer) This method creates a XMLStreamWriter.
protected void	doInitialize() This method performs the actual initialization.
String	getEventTypeName(int eventType) This method gets the name for the given eventType.
static StaxUtil	getInstance() This method gets the singleton instance of this StaxUtilImpl.
protected StringValueConverter	getValueConverter()
javax.xml.stream.XMLInputFactory	getXmlInputFactory() This method gets the XMLInputFactory to use.
protected javax.xml.stream.XMLOutputFactory	getXmlOutputFactory() This method gets the XMLOutputFactory to use.
javax.xml.stream.events.XMLEvent	nextElement(javax.xml.stream.XMLEventReader xmlReader) This method skips all events until a StartElement, EndElement or EndDocument is encountered.
<V> V	parseAttribute(javax.xml.stream.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(javax.xml.stream.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(javax.xml.stream.XMLStreamReader xmlReader) This method reads the text at the current position of the given xmlReader.
void	setValueConverter(StringValueConverter valueConverter)
void	setXmlInputFactory(javax.xml.stream.XMLInputFactory xmlInputFactory)
void	setXmlOutputFactory(javax.xml.stream.XMLOutputFactory xmlOutputFactory) This method sets the XML-output-factory.
void	skipOpenElement(javax.xml.stream.XMLEventReader xmlReader) This method skips all events until the current element (tag) is closed.
void	skipOpenElement(javax.xml.stream.XMLStreamReader xmlReader) This method skips all events until the current element (tag) is closed.

Methods inherited from class net.sf.mmm.util.component.base.AbstractLoggableComponent

getLogger, setLogger

Methods inherited from class net.sf.mmm.util.component.base.AbstractComponent

doInitialized, getInitializationState, initialize

Methods inherited from class java.lang.Object

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

Field Detail

instance

private static StaxUtil instance

See Also:

getInstance()

xmlInputFactory

private javax.xml.stream.XMLInputFactory xmlInputFactory

See Also:

getXmlInputFactory()

xmlOutputFactory

private javax.xml.stream.XMLOutputFactory xmlOutputFactory

See Also:

getXmlOutputFactory()

valueConverter

private StringValueConverter valueConverter

See Also:

getValueConverter()

Constructor Detail

StaxUtilImpl

public StaxUtilImpl()

The constructor.

Method Detail

getInstance

public static StaxUtil getInstance()

This method gets the singleton instance of this StaxUtilImpl.
This design is the best compromise between easy access (via this indirection you have direct, static access to all offered functionality) and IoC-style design which allows extension and customization.
For IoC usage, simply ignore all static getInstance() methods and construct new instances via the container-framework of your choice (like plexus, pico, springframework, etc.). To wire up the dependent components everything is properly annotated using common-annotations (JSR-250). If your container does NOT support this, you should consider using a better one.

Returns:

the singleton instance.

getValueConverter

protected StringValueConverter getValueConverter()

Returns:

the valueConverter

setValueConverter

@Inject
public void setValueConverter(StringValueConverter valueConverter)

Parameters:

valueConverter - the valueConverter to set

getXmlOutputFactory

protected javax.xml.stream.XMLOutputFactory getXmlOutputFactory()

This method gets the XMLOutputFactory to use.

Returns:

the xmlOutputFactory

setXmlOutputFactory

public void setXmlOutputFactory(javax.xml.stream.XMLOutputFactory xmlOutputFactory)

This method sets the XML-output-factory.

Parameters:

xmlOutputFactory - is the xmlOutputFactory to set.

getXmlInputFactory

public javax.xml.stream.XMLInputFactory getXmlInputFactory()

This method gets the XMLInputFactory to use.

Returns:

the xmlInputFactory

setXmlInputFactory

public void setXmlInputFactory(javax.xml.stream.XMLInputFactory xmlInputFactory)

Parameters:

xmlInputFactory - is the xmlInputFactory to set

doInitialize

protected void doInitialize()

This method performs the actual initialization. It is called when AbstractComponent.initialize() is invoked for the first time.
ATTENTION:
When you override this method from a sub-class you need to do a super.AbstractComponent.doInitialize().

Overrides:

doInitialize in class AbstractLoggableComponent

createXmlEventReader

public javax.xml.stream.XMLEventReader createXmlEventReader(InputStream inputStream)

This method creates an XMLEventReader.

Specified by:

createXmlEventReader in interface StaxUtil

Parameters:

inputStream - is the InputStream to read from.

Returns:

the XMLEventReader.

See Also:

XMLInputFactory.createXMLEventReader(InputStream)

createXmlStreamReader

public javax.xml.stream.XMLStreamReader createXmlStreamReader(InputStream inputStream)

This method creates an XMLStreamReader.

Specified by:

createXmlStreamReader in interface StaxUtil

Parameters:

inputStream - is the InputStream to read from.

Returns:

the XMLStreamReader.

See Also:

XMLInputFactory.createXMLStreamReader(InputStream)

createXmlStreamWriter

public javax.xml.stream.XMLStreamWriter createXmlStreamWriter(OutputStream out)

This method creates a XMLStreamWriter.

Specified by:

createXmlStreamWriter in interface StaxUtil

Parameters:

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

Returns:

the XML stream writer.

See Also:

XMLOutputFactory.createXMLStreamWriter(OutputStream)

createXmlStreamWriter

public javax.xml.stream.XMLStreamWriter createXmlStreamWriter(Writer writer)

This method creates a XMLStreamWriter.

Specified by:

createXmlStreamWriter in interface StaxUtil

Parameters:

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

Returns:

the XML stream writer.

See Also:

XMLOutputFactory.createXMLStreamWriter(Writer)

parseAttribute

public <V> V parseAttribute(javax.xml.stream.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.

Specified by:

parseAttribute in interface StaxUtil

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

public <V> V parseAttribute(javax.xml.stream.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.

Specified by:

parseAttribute in interface StaxUtil

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

public String readText(javax.xml.stream.XMLStreamReader xmlReader)

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().

Specified by:

readText in interface StaxUtil

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).

skipOpenElement

public void skipOpenElement(javax.xml.stream.XMLStreamReader xmlReader)

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);
     }
   }
 

Specified by:

skipOpenElement in interface StaxUtil

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.

skipOpenElement

public void skipOpenElement(javax.xml.stream.XMLEventReader xmlReader)

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

Specified by:

skipOpenElement in interface StaxUtil

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.

See Also:

StaxUtil.skipOpenElement(XMLStreamReader)

nextElement

public javax.xml.stream.events.XMLEvent nextElement(javax.xml.stream.XMLEventReader xmlReader)

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.

Specified by:

nextElement in interface StaxUtil

Parameters:

xmlReader - is the XMLEventReader to read the XML from.

Returns:

the according event.

getEventTypeName

public String getEventTypeName(int eventType)

This method gets the name for the given eventType.

Specified by:

getEventTypeName in interface StaxUtil

Parameters:

eventType - is an event type constant declared in XMLStreamConstants.

Returns:

the according name.

See Also:

XMLStreamConstants