Package org.apache.axiom.ext.stax.datahandler

Interface DataHandlerReader

public interface DataHandlerReader

Extension interface for XMLStreamReader implementations that expose base64 encoded binary content as DataHandler objects.

All the requirements specified in org.apache.axiom.ext.stax apply to this extension interface. In particular, a consumer MUST use XMLStreamReader.getProperty(String) with the property name defined by PROPERTY to get a reference to this extension interface.

If the XMLStreamReader wishes to expose base64 encoded content using this extension interface, it MUST do so using a single XMLStreamConstants.CHARACTERS event. To maintain compatibility with consumers that are unaware of the extension, 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.

The extension described by this interface will typically be implemented by XMLStreamReader instances provided by databinding frameworks or XMLStreamReader proxies that enrich a stream of StAX events with binary data existing outside of the XML document (e.g. an XOP/MTOM decoder).

Field Summary

Fields

Modifier and Type	Field	Description
static String	PROPERTY	The name of the property used to look up this extension interface from a XMLStreamReader implementation.

Method Summary

Modifier and Type	Method	Description
String	getContentID()	Get the content ID of the binary content for the current event, if available.
DataHandler	getDataHandler()	Get the DataHandler with the binary content for the current event.
DataHandlerProvider	getDataHandlerProvider()	Get a DataHandlerProvider instance for deferred loading of the binary content for the current event.
boolean	isBinary()	Check whether the current event is a XMLStreamConstants.CHARACTERS event representing base64 encoded binary content and for which a DataHandler is available.
boolean	isDeferred()	Check whether the XMLStreamReader supports deferred loading of the binary content for the current event.
boolean	isOptimized()	Check if the binary content is eligible for optimization (e.g. using XOP) or if it should be serialized as base64.

Field Detail

PROPERTY

static final String PROPERTY

The name of the property used to look up this extension interface from a XMLStreamReader implementation.

Method Detail

isBinary

boolean isBinary()

Check whether the current event is a XMLStreamConstants.CHARACTERS event representing base64 encoded binary content and for which a DataHandler is available.

Returns:

true if the current event is a XMLStreamConstants.CHARACTERS event representing base64 encoded binary content and for which a DataHandler is available; false for all other types of events.

isOptimized

boolean isOptimized()

Check if the binary content is eligible for optimization (e.g. using XOP) or if it should be serialized as base64. Calling this method is only meaningful if isBinary() returns true for the current event. The behavior of this method is undefined if this is not the case.

Returns:

true if the binary content is eligible for optimization; false otherwise

isDeferred

boolean isDeferred()

Check whether the XMLStreamReader supports deferred loading of the binary content for the current event. If this method returns true then a consumer MAY call getDataHandlerProvider() and retrieve the DataHandler later using DataHandlerProvider.getDataHandler(). Calling this method is only meaningful if isBinary() returns true for the current event. The behavior of this method is undefined if this is not the case.

Returns:

true if deferred loading is supported; false otherwise

getContentID

String getContentID()

Get the content ID of the binary content for the current event, if available. The result of this method is defined if and only if isBinary() returns true for the current event.

The implementation SHOULD only return a non null value if the content ID has been used previously in an interaction with another component or system. The implementation SHOULD NOT generate a new content ID solely for the purpose of this method.

If available, the returned value MUST be a raw content ID. In particular:

• If the content ID has been extracted from an href attribute, it MUST NOT contain the cid: prefix.
• If it has been extracted from a Content-ID MIME header, it MUST NOT be enclosed in angles (<>).

A consumer MAY use the return value of this method in contexts where it is desirable to preserve the original content ID used by another system or component to identify the binary content. However, the consumer MUST NOT make any assumption about the uniqueness or validity of the content ID (with respect to relevant standards such as RFC822) and SHOULD make provision to sanitize the value if necessary.

Returns:

any content ID used previously to identify the binary content, or null if no content ID is known

getDataHandler

DataHandler getDataHandler()
                    throws XMLStreamException

Get the DataHandler with the binary content for the current event. The behavior of this method is only defined for events for which isBinary() returns true. For events of this type the method MUST return a valid DataHandler, regardless of the return value of isDeferred(). If isDeferred() returns true, then the consumer may use this method to force the implementation to load the binary content immediately.

Returns:

the binary content for the current event

Throws:

XMLStreamException - if an error occurs while loading the DataHandler

getDataHandlerProvider

DataHandlerProvider getDataHandlerProvider()

Get a DataHandlerProvider instance for deferred loading of the binary content for the current event. The behavior of this method is defined if and only if isDeferred() returns true for the current event. The returned reference MUST remain valid after the current event has been consumed. It is up to the implementation to specify the exact lifecycle of the returned instance, in particular until when the binary content can be retrieved.

Returns:

the DataHandlerProvider instance the consumer can use to load the binary content at a later time