org.apache.axiom.util.stax
Class XMLStreamReaderUtils

java.lang.Object
  org.apache.axiom.util.stax.XMLStreamReaderUtils

public class XMLStreamReaderUtils
extends Object

Contains utility methods to work with XMLStreamReader objects, including the extension defined by DataHandlerReader. In addition to DataHandlerReader support, this class also provides support for the legacy extension mechanism described below.

Legacy XMLStreamReader extensions for optimized base64 handling

XMLStreamReader instances supporting the legacy extension must conform to the following requirements:

1. XMLStreamReader.getProperty(String) must return Boolean.TRUE for the property identified by OMConstants.IS_DATA_HANDLERS_AWARE, regardless of the current event. The property is assumed to be immutable and its value must not change during the lifetime of the XMLStreamReader implementation.

2. If the XMLStreamReader wishes to expose base64 encoded content using a DataHandler object, it must do so using a single XMLStreamConstants.CHARACTERS event.

   To maintain compatibility with consumers that are unaware of the extensions described here, the implementation should make sure that XMLStreamReader.getText(), XMLStreamReader.getTextStart(), XMLStreamReader.getTextLength(), XMLStreamReader.getTextCharacters(), XMLStreamReader.getTextCharacters(int, char[], int, int) and XMLStreamReader.getElementText() behave as expected for this type of event, i.e. return the base64 representation of the binary content.

3. XMLStreamReader.getProperty(String) must return Boolean.TRUE for the property identified by OMConstants.IS_BINARY if the current event is a XMLStreamConstants.CHARACTERS event representing base64 encoded binary content and for which a DataHandler is available. For all other events, the returned value must be Boolean.FALSE.

4. If for a given event, the implementation returned Boolean.TRUE for the OMConstants.IS_BINARY property, then a call to XMLStreamReader.getProperty(String) with argument OMConstants.DATA_HANDLER must return the corresponding DataHandler object.

   The OMConstants.DATA_HANDLER property is undefined for any other type of event. This implies that the consumer of the XMLStreamReader must check the OMConstants.IS_BINARY property before retrieving the OMConstants.DATA_HANDLER property.

The extension mechanism described here has been deprecated mainly because it doesn't support deferred loading of the binary content.

Method Summary

static DataHandler	getDataHandlerFromElement(XMLStreamReader reader) Get a DataHandler for the binary data encoded in an element.
static DataHandlerReader	getDataHandlerReader(XMLStreamReader reader) Get the DataHandlerReader extension for a given XMLStreamReader, if available.
static Reader	getElementTextAsStream(XMLStreamReader reader, boolean allowNonTextChildren) Get the text content of the current element as a Reader object.
static XMLStreamReader	getOriginalXMLStreamReader(XMLStreamReader parser) Searches the wrapper and delegate classes to find the original XMLStreamReader.
static Object	processGetProperty(DataHandlerReader extension, String propertyName) Helper method to implement XMLStreamReader.getProperty(String).
static void	writeTextTo(XMLStreamReader reader, Writer writer) Get the character data for the current event from the given reader and write it to the given writer.

Methods inherited from class java.lang.Object

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

Method Detail

getDataHandlerReader

public static DataHandlerReader getDataHandlerReader(XMLStreamReader reader)

Get the DataHandlerReader extension for a given XMLStreamReader, if available. If the XMLStreamReader only supports the legacy extension (as described above), then this method will return a compatibility wrapper. Note that this wrapper doesn't support deferred loading of the binary content.

Parameters:

reader - the stream reader to get the DataHandlerReader extension from

Returns:

the implementation of the extension, or null if the XMLStreamReader doesn't expose base64 encoded binary content as DataHandler objects.

processGetProperty

public static Object processGetProperty(DataHandlerReader extension,
                                        String propertyName)

Helper method to implement XMLStreamReader.getProperty(String). This method processed the properties defined by DataHandlerReader.PROPERTY and the legacy extension mechanism (as described above). It can therefore be used to make a XMLStreamReader implementation compatible with code that expects it to implement this legacy extension.

Parameters:

extension - the reference to the DataHandlerReader extension for the XMLStreamReader implementation

propertyName - the name of the property, as passed to the XMLStreamReader.getProperty(String) method

Returns:

the property value as specified by the DataHandlerReader or legacy extension; null if the property is not specified by any of these two extensions

getDataHandlerFromElement

public static DataHandler getDataHandlerFromElement(XMLStreamReader reader)
                                             throws XMLStreamException

Get a DataHandler for the binary data encoded in an element. The method supports base64 encoded character data as well as optimized binary data through the DataHandlerReader extension.

Precondition: the reader is on a XMLStreamConstants.START_ELEMENT

Postcondition: the reader is on the corresponding XMLStreamConstants.END_ELEMENT

Parameters:

reader - the stream to read the data from

Returns:

the binary data from the element

Throws:

XMLStreamException

writeTextTo

public static void writeTextTo(XMLStreamReader reader,
                               Writer writer)
                        throws XMLStreamException,
                               IOException

Get the character data for the current event from the given reader and write it to the given writer. The method will try to figure out the most efficient way to copy the data without unnecessary buffering or conversions between strings and character arrays.

Parameters:

reader - the reader to get the character data from

writer - the writer to write the character data to

Throws:

XMLStreamException - if the underlying XML source is not well-formed

IOException - if an I/O error occurs when writing the character data

IllegalStateException - if this state is not a valid text state.

See Also:

CharacterDataReader

getElementTextAsStream

public static Reader getElementTextAsStream(XMLStreamReader reader,
                                            boolean allowNonTextChildren)

Get the text content of the current element as a Reader object.

Parameters:

reader - The XML stream reader to read the element text from. The reader must be positioned on a XMLStreamConstants.START_ELEMENT event.

allowNonTextChildren - If set to true, non text child nodes are allowed and skipped. If set to false only text nodes are allowed and the presence of any other type of child node will trigger an exception.

Returns:

The reader from which the element text can be read. After the reader has reported the end of the stream, the XML stream reader will be positioned on the XMLStreamConstants.END_ELEMENT event corresponding to the initial XMLStreamConstants.START_ELEMENT event. Calling Reader.close() on the returned reader has no effect. Any parser exception will be reported by the reader using XMLStreamIOException.

Throws:

IllegalStateException - if the XML stream reader is not positioned on a XMLStreamConstants.START_ELEMENT event

getOriginalXMLStreamReader

public static XMLStreamReader getOriginalXMLStreamReader(XMLStreamReader parser)

Searches the wrapper and delegate classes to find the original XMLStreamReader. This method should only be used when a consumer of Axiom really needs to access the original stream reader.

Parameters:

parser - XMLStreamReader used by Axiom

Returns:

original parser