public interface DataHandlerReader
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).
Modifier and Type | Field and Description |
---|---|
static String |
PROPERTY
The name of the property used to look up this extension interface from a
XMLStreamReader implementation. |
Modifier and Type | Method and Description |
---|---|
String |
getContentID()
Get the content ID of the binary content for the current event, if available.
|
javax.activation.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.
|
static final String PROPERTY
XMLStreamReader
implementation.boolean isBinary()
XMLStreamConstants.CHARACTERS
event representing base64 encoded binary content and for which a
DataHandler
is available.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.boolean isOptimized()
isBinary()
returns true
for
the current event. The behavior of this method is undefined if this is not the case.true
if the binary content is eligible for optimization;
false
otherwiseboolean isDeferred()
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.true
if deferred loading is supported; false
otherwiseString getContentID()
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:
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.
null
if no content ID is knownjavax.activation.DataHandler getDataHandler() throws javax.xml.stream.XMLStreamException
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.javax.xml.stream.XMLStreamException
- if an error occurs while loading the DataHandler
DataHandlerProvider getDataHandlerProvider()
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.DataHandlerProvider
instance the consumer can use to load the binary
content at a later timeCopyright © 2004-2013 The Apache Software Foundation. All Rights Reserved.