org.apache.axiom.util.stax.xop

Class XOPDecodingStreamReader

java.lang.Object

org.apache.axiom.util.stax.wrapper.XMLStreamReaderWrapper

org.apache.axiom.util.stax.xop.XOPDecodingStreamReader

All Implemented Interfaces:

XMLStreamConstants, XMLStreamReader, DataHandlerReader

public class XOPDecodingStreamReader
extends XMLStreamReaderWrapper
implements DataHandlerReader

XMLStreamReader wrapper that decodes XOP. It uses the extension defined by DataHandlerReader to expose the DataHandler objects referenced by xop:Include elements encountered in the underlying stream. If the consumer uses getText(), getTextCharacters(), getTextCharacters(int, char[], int, int) or getElementText() when an xop:Include element is present in the underlying stream, then the decoder will produce a base64 representation of the data.

Note that this class only implements infoset transformation, but doesn't handle MIME processing. A MimePartProvider implementation must be provided to the constructor of this class. This object will be used to load MIME parts referenced by xop:Include elements encountered in the underlying stream.

This class supports deferred loading of MIME parts: If the consumer uses DataHandlerReader.getDataHandlerProvider(), then the MimePartProvider will only be invoked when DataHandlerProvider.getDataHandler() is called.

Field Summary

Fields inherited from interface org.apache.axiom.ext.stax.datahandler.DataHandlerReader

PROPERTY

Fields inherited from interface javax.xml.stream.XMLStreamConstants

ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT

Constructor Summary

Constructors

Constructor and Description
XOPDecodingStreamReader(XMLStreamReader parent, MimePartProvider mimePartProvider) Constructor.

Method Summary

Modifier and Type	Method and 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.
String	getElementText()
int	getEventType()
String	getLocalName()
Location	getLocation()
QName	getName()
int	getNamespaceCount()
String	getNamespacePrefix(int index)
String	getNamespaceURI()
String	getNamespaceURI(int index)
String	getNamespaceURI(String prefix)
String	getPrefix()
Object	getProperty(String name)
String	getText()
char[]	getTextCharacters()
int	getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
int	getTextLength()
int	getTextStart()
boolean	hasName()
boolean	hasText()
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	isCharacters()
boolean	isDeferred() Check whether the XMLStreamReader supports deferred loading of the binary content for the current event.
boolean	isEndElement()
boolean	isOptimized() Check if the binary content is eligible for optimization (e.g. using XOP) or if it should be serialized as base64.
boolean	isStartElement()
boolean	isWhiteSpace()
int	next()
int	nextTag()
void	require(int type, String namespaceURI, String localName)

Methods inherited from class org.apache.axiom.util.stax.wrapper.XMLStreamReaderWrapper

close, getAttributeCount, getAttributeLocalName, getAttributeName, getAttributeNamespace, getAttributePrefix, getAttributeType, getAttributeValue, getAttributeValue, getCharacterEncodingScheme, getEncoding, getNamespaceContext, getParent, getPIData, getPITarget, getVersion, hasNext, isAttributeSpecified, isStandalone, standaloneSet

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XOPDecodingStreamReader

public XOPDecodingStreamReader(XMLStreamReader parent,
                               MimePartProvider mimePartProvider)

Constructor.

Parameters:

parent - the XML stream to decode

mimePartProvider - An implementation of the MimePartProvider interface that will be used to load the DataHandler objects for MIME parts referenced by xop:Include element information items encountered in the underlying stream.

Method Detail

next

public int next()
         throws XMLStreamException

Specified by:

next in interface XMLStreamReader

Overrides:

next in class XMLStreamReaderWrapper

Throws:

XMLStreamException

getEventType

public int getEventType()

Specified by:

getEventType in interface XMLStreamReader

Overrides:

getEventType in class XMLStreamReaderWrapper

nextTag

public int nextTag()
            throws XMLStreamException

Specified by:

nextTag in interface XMLStreamReader

Overrides:

nextTag in class XMLStreamReaderWrapper

Throws:

XMLStreamException

getProperty

public Object getProperty(String name)
                   throws IllegalArgumentException

Specified by:

getProperty in interface XMLStreamReader

Overrides:

getProperty in class XMLStreamReaderWrapper

Throws:

IllegalArgumentException

getElementText

public String getElementText()
                      throws XMLStreamException

Specified by:

getElementText in interface XMLStreamReader

Overrides:

getElementText in class XMLStreamReaderWrapper

Throws:

XMLStreamException

getPrefix

public String getPrefix()

Specified by:

getPrefix in interface XMLStreamReader

Overrides:

getPrefix in class XMLStreamReaderWrapper

getNamespaceURI

public String getNamespaceURI()

Specified by:

getNamespaceURI in interface XMLStreamReader

Overrides:

getNamespaceURI in class XMLStreamReaderWrapper

getLocalName

public String getLocalName()

Specified by:

getLocalName in interface XMLStreamReader

Overrides:

getLocalName in class XMLStreamReaderWrapper

getName

public QName getName()

Specified by:

getName in interface XMLStreamReader

Overrides:

getName in class XMLStreamReaderWrapper

getLocation

public Location getLocation()

Specified by:

getLocation in interface XMLStreamReader

Overrides:

getLocation in class XMLStreamReaderWrapper

getNamespaceURI

public String getNamespaceURI(String prefix)

Specified by:

getNamespaceURI in interface XMLStreamReader

Overrides:

getNamespaceURI in class XMLStreamReaderWrapper

getNamespaceCount

public int getNamespaceCount()

Specified by:

getNamespaceCount in interface XMLStreamReader

Overrides:

getNamespaceCount in class XMLStreamReaderWrapper

getNamespacePrefix

public String getNamespacePrefix(int index)

Specified by:

getNamespacePrefix in interface XMLStreamReader

Overrides:

getNamespacePrefix in class XMLStreamReaderWrapper

getNamespaceURI

public String getNamespaceURI(int index)

Specified by:

getNamespaceURI in interface XMLStreamReader

Overrides:

getNamespaceURI in class XMLStreamReaderWrapper

getText

public String getText()

Specified by:

getText in interface XMLStreamReader

Overrides:

getText in class XMLStreamReaderWrapper

getTextCharacters

public char[] getTextCharacters()

Specified by:

getTextCharacters in interface XMLStreamReader

Overrides:

getTextCharacters in class XMLStreamReaderWrapper

getTextCharacters

public int getTextCharacters(int sourceStart,
                             char[] target,
                             int targetStart,
                             int length)
                      throws XMLStreamException

Specified by:

getTextCharacters in interface XMLStreamReader

Overrides:

getTextCharacters in class XMLStreamReaderWrapper

Throws:

XMLStreamException

getTextLength

public int getTextLength()

Specified by:

getTextLength in interface XMLStreamReader

Overrides:

getTextLength in class XMLStreamReaderWrapper

getTextStart

public int getTextStart()

Specified by:

getTextStart in interface XMLStreamReader

Overrides:

getTextStart in class XMLStreamReaderWrapper

hasText

public boolean hasText()

Specified by:

hasText in interface XMLStreamReader

Overrides:

hasText in class XMLStreamReaderWrapper

isCharacters

public boolean isCharacters()

Specified by:

isCharacters in interface XMLStreamReader

Overrides:

isCharacters in class XMLStreamReaderWrapper

isStartElement

public boolean isStartElement()

Specified by:

isStartElement in interface XMLStreamReader

Overrides:

isStartElement in class XMLStreamReaderWrapper

isEndElement

public boolean isEndElement()

Specified by:

isEndElement in interface XMLStreamReader

Overrides:

isEndElement in class XMLStreamReaderWrapper

hasName

public boolean hasName()

Specified by:

hasName in interface XMLStreamReader

Overrides:

hasName in class XMLStreamReaderWrapper

isWhiteSpace

public boolean isWhiteSpace()

Specified by:

isWhiteSpace in interface XMLStreamReader

Overrides:

isWhiteSpace in class XMLStreamReaderWrapper

require

public void require(int type,
                    String namespaceURI,
                    String localName)
             throws XMLStreamException

Specified by:

require in interface XMLStreamReader

Overrides:

require in class XMLStreamReaderWrapper

Throws:

XMLStreamException

isBinary

public boolean isBinary()

Description copied from interface: DataHandlerReader

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

Specified by:

isBinary in interface DataHandlerReader

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

public boolean isOptimized()

Description copied from interface: DataHandlerReader

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 DataHandlerReader.isBinary() returns true for the current event. The behavior of this method is undefined if this is not the case.

Specified by:

isOptimized in interface DataHandlerReader

Returns:

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

isDeferred

public boolean isDeferred()

Description copied from interface: DataHandlerReader

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 DataHandlerReader.getDataHandlerProvider() and retrieve the DataHandler later using DataHandlerProvider.getDataHandler(). Calling this method is only meaningful if DataHandlerReader.isBinary() returns true for the current event. The behavior of this method is undefined if this is not the case.

Specified by:

isDeferred in interface DataHandlerReader

Returns:

true if deferred loading is supported; false otherwise

getContentID

public String getContentID()

Description copied from interface: DataHandlerReader

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 DataHandlerReader.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.

Specified by:

getContentID in interface DataHandlerReader

Returns:

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

getDataHandler

public DataHandler getDataHandler()
                           throws XMLStreamException

Description copied from interface: DataHandlerReader

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

Specified by:

getDataHandler in interface DataHandlerReader

Returns:

the binary content for the current event

Throws:

XMLStreamException - if an error occurs while loading the DataHandler

getDataHandlerProvider

public DataHandlerProvider getDataHandlerProvider()

Description copied from interface: DataHandlerReader

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 DataHandlerReader.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.

Specified by:

getDataHandlerProvider in interface DataHandlerReader

Returns:

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