Interface DataHandlerReader
-
public interface DataHandlerReaderExtension interface forXMLStreamReaderimplementations that expose base64 encoded binary content asDataHandlerobjects.All the requirements specified in
org.apache.axiom.ext.staxapply to this extension interface. In particular, a consumer MUST useXMLStreamReader.getProperty(String)with the property name defined byPROPERTYto get a reference to this extension interface.If the
XMLStreamReaderwishes to expose base64 encoded content using this extension interface, it MUST do so using a singleXMLStreamConstants.CHARACTERSevent. To maintain compatibility with consumers that are unaware of the extension, the implementation SHOULD make sure thatXMLStreamReader.getText(),XMLStreamReader.getTextStart(),XMLStreamReader.getTextLength(),XMLStreamReader.getTextCharacters(),XMLStreamReader.getTextCharacters(int, char[], int, int)andXMLStreamReader.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 StringPROPERTYThe name of the property used to look up this extension interface from aXMLStreamReaderimplementation.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description StringgetContentID()Get the content ID of the binary content for the current event, if available.DataHandlergetDataHandler()Get theDataHandlerwith the binary content for the current event.DataHandlerProvidergetDataHandlerProvider()Get aDataHandlerProviderinstance for deferred loading of the binary content for the current event.booleanisBinary()Check whether the current event is aXMLStreamConstants.CHARACTERSevent representing base64 encoded binary content and for which aDataHandleris available.booleanisDeferred()Check whether theXMLStreamReadersupports deferred loading of the binary content for the current event.booleanisOptimized()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 aXMLStreamReaderimplementation.
-
-
Method Detail
-
isBinary
boolean isBinary()
Check whether the current event is aXMLStreamConstants.CHARACTERSevent representing base64 encoded binary content and for which aDataHandleris available.- Returns:
trueif the current event is aXMLStreamConstants.CHARACTERSevent representing base64 encoded binary content and for which aDataHandleris available;falsefor 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 ifisBinary()returnstruefor the current event. The behavior of this method is undefined if this is not the case.- Returns:
trueif the binary content is eligible for optimization;falseotherwise
-
isDeferred
boolean isDeferred()
Check whether theXMLStreamReadersupports deferred loading of the binary content for the current event. If this method returnstruethen a consumer MAY callgetDataHandlerProvider()and retrieve theDataHandlerlater usingDataHandlerProvider.getDataHandler(). Calling this method is only meaningful ifisBinary()returnstruefor the current event. The behavior of this method is undefined if this is not the case.- Returns:
trueif deferred loading is supported;falseotherwise
-
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 ifisBinary()returnstruefor 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
hrefattribute, it MUST NOT contain thecid:prefix. - If it has been extracted from a
Content-IDMIME 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
nullif no content ID is known
- If the content ID has been extracted from an
-
getDataHandler
DataHandler getDataHandler() throws XMLStreamException
Get theDataHandlerwith the binary content for the current event. The behavior of this method is only defined for events for whichisBinary()returnstrue. For events of this type the method MUST return a validDataHandler, regardless of the return value ofisDeferred(). IfisDeferred()returnstrue, 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 theDataHandler
-
getDataHandlerProvider
DataHandlerProvider getDataHandlerProvider()
Get aDataHandlerProviderinstance for deferred loading of the binary content for the current event. The behavior of this method is defined if and only ifisDeferred()returnstruefor 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
DataHandlerProviderinstance the consumer can use to load the binary content at a later time
-
-