org.apache.axiom.om.impl.builder
Class DataHandlerReaderUtils

java.lang.Object
  org.apache.axiom.om.impl.builder.DataHandlerReaderUtils

public class DataHandlerReaderUtils
extends java.lang.Object

Utility class to work with the XMLStreamReader 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 DataHandlerReader	getDataHandlerReader(javax.xml.stream.XMLStreamReader reader) Get the DataHandlerReader extension for a given XMLStreamReader, if available.
static java.lang.Object	processGetProperty(DataHandlerReader extension, java.lang.String propertyName) Helper method to implement XMLStreamReader.getProperty(String).

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(javax.xml.stream.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 java.lang.Object processGetProperty(DataHandlerReader extension,
                                                  java.lang.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