org.apache.axiom.util.stax
Class XMLStreamReaderUtils

java.lang.Object
  extended by 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


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.