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:

javax.xml.stream.XMLStreamConstants, javax.xml.stream.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	XOPDecodingStreamReader.DataHandlerProviderImpl

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.String	base64
private XOPDecodingStreamReader.DataHandlerProviderImpl	dh
private static org.apache.commons.logging.Log	log
private MimePartProvider	mimePartProvider
private static java.lang.String	SOLE_CHILD_MSG

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(javax.xml.stream.XMLStreamReader parent, MimePartProvider mimePartProvider) Constructor.

Method Summary

Modifier and Type	Method and Description
java.lang.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.
java.lang.String	getElementText()
int	getEventType()
java.lang.String	getLocalName()
javax.xml.stream.Location	getLocation()
javax.xml.namespace.QName	getName()
int	getNamespaceCount()
java.lang.String	getNamespacePrefix(int index)
java.lang.String	getNamespaceURI()
java.lang.String	getNamespaceURI(int index)
java.lang.String	getNamespaceURI(java.lang.String prefix)
java.lang.String	getPrefix()
java.lang.Object	getProperty(java.lang.String name)
java.lang.String	getText()
char[]	getTextCharacters()
int	getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
int	getTextLength()
int	getTextStart()
(package private) XOPEncodedStream	getXOPEncodedStream()
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.
boolean	isStartElement()
boolean	isWhiteSpace()
int	next()
int	nextTag()
private java.lang.String	processXopInclude() Process an xop:Include event and return the content ID.
void	require(int type, java.lang.String namespaceURI, java.lang.String localName)
private void	resetDataHandler()
private java.lang.String	toBase64()
private static java.lang.String	toBase64(javax.activation.DataHandler dh)

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

Field Detail

SOLE_CHILD_MSG

private static final java.lang.String SOLE_CHILD_MSG

See Also:

Constant Field Values

log

private static final org.apache.commons.logging.Log log

mimePartProvider

private final MimePartProvider mimePartProvider

dh

private XOPDecodingStreamReader.DataHandlerProviderImpl dh

base64

private java.lang.String base64

Constructor Detail

XOPDecodingStreamReader

public XOPDecodingStreamReader(javax.xml.stream.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

resetDataHandler

private void resetDataHandler()

processXopInclude

private java.lang.String processXopInclude()
                                    throws javax.xml.stream.XMLStreamException

Process an xop:Include event and return the content ID.

Precondition: The parent reader is on the START_ELEMENT event for the xop:Include element. Note that the method doesn't check this condition.

Postcondition: The parent reader is on the event following the END_ELEMENT event for the xop:Include element, i.e. the parent reader is on the END_ELEMENT event of the element enclosing the xop:Include element.

Returns:

the content ID the xop:Include refers to

Throws:

javax.xml.stream.XMLStreamException

next

public int next()
         throws javax.xml.stream.XMLStreamException

Specified by:

next in interface javax.xml.stream.XMLStreamReader

Overrides:

next in class XMLStreamReaderWrapper

Throws:

javax.xml.stream.XMLStreamException

getEventType

public int getEventType()

Specified by:

getEventType in interface javax.xml.stream.XMLStreamReader

Overrides:

getEventType in class XMLStreamReaderWrapper

nextTag

public int nextTag()
            throws javax.xml.stream.XMLStreamException

Specified by:

nextTag in interface javax.xml.stream.XMLStreamReader

Overrides:

nextTag in class XMLStreamReaderWrapper

Throws:

javax.xml.stream.XMLStreamException

getProperty

public java.lang.Object getProperty(java.lang.String name)
                             throws java.lang.IllegalArgumentException

Specified by:

getProperty in interface javax.xml.stream.XMLStreamReader

Overrides:

getProperty in class XMLStreamReaderWrapper

Throws:

java.lang.IllegalArgumentException

getElementText

public java.lang.String getElementText()
                                throws javax.xml.stream.XMLStreamException

Specified by:

getElementText in interface javax.xml.stream.XMLStreamReader

Overrides:

getElementText in class XMLStreamReaderWrapper

Throws:

javax.xml.stream.XMLStreamException

getPrefix

public java.lang.String getPrefix()

Specified by:

getPrefix in interface javax.xml.stream.XMLStreamReader

Overrides:

getPrefix in class XMLStreamReaderWrapper

getNamespaceURI

public java.lang.String getNamespaceURI()

Specified by:

getNamespaceURI in interface javax.xml.stream.XMLStreamReader

Overrides:

getNamespaceURI in class XMLStreamReaderWrapper

getLocalName

public java.lang.String getLocalName()

Specified by:

getLocalName in interface javax.xml.stream.XMLStreamReader

Overrides:

getLocalName in class XMLStreamReaderWrapper

getName

public javax.xml.namespace.QName getName()

Specified by:

getName in interface javax.xml.stream.XMLStreamReader

Overrides:

getName in class XMLStreamReaderWrapper

getLocation

public javax.xml.stream.Location getLocation()

Specified by:

getLocation in interface javax.xml.stream.XMLStreamReader

Overrides:

getLocation in class XMLStreamReaderWrapper

getNamespaceURI

public java.lang.String getNamespaceURI(java.lang.String prefix)

Specified by:

getNamespaceURI in interface javax.xml.stream.XMLStreamReader

Overrides:

getNamespaceURI in class XMLStreamReaderWrapper

getNamespaceCount

public int getNamespaceCount()

Specified by:

getNamespaceCount in interface javax.xml.stream.XMLStreamReader

Overrides:

getNamespaceCount in class XMLStreamReaderWrapper

getNamespacePrefix

public java.lang.String getNamespacePrefix(int index)

Specified by:

getNamespacePrefix in interface javax.xml.stream.XMLStreamReader

Overrides:

getNamespacePrefix in class XMLStreamReaderWrapper

getNamespaceURI

public java.lang.String getNamespaceURI(int index)

Specified by:

getNamespaceURI in interface javax.xml.stream.XMLStreamReader

Overrides:

getNamespaceURI in class XMLStreamReaderWrapper

toBase64

private static java.lang.String toBase64(javax.activation.DataHandler dh)
                                  throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

toBase64

private java.lang.String toBase64()
                           throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

getText

public java.lang.String getText()

Specified by:

getText in interface javax.xml.stream.XMLStreamReader

Overrides:

getText in class XMLStreamReaderWrapper

getTextCharacters

public char[] getTextCharacters()

Specified by:

getTextCharacters in interface javax.xml.stream.XMLStreamReader

Overrides:

getTextCharacters in class XMLStreamReaderWrapper

getTextCharacters

public int getTextCharacters(int sourceStart,
                             char[] target,
                             int targetStart,
                             int length)
                      throws javax.xml.stream.XMLStreamException

Specified by:

getTextCharacters in interface javax.xml.stream.XMLStreamReader

Overrides:

getTextCharacters in class XMLStreamReaderWrapper

Throws:

javax.xml.stream.XMLStreamException

getTextLength

public int getTextLength()

Specified by:

getTextLength in interface javax.xml.stream.XMLStreamReader

Overrides:

getTextLength in class XMLStreamReaderWrapper

getTextStart

public int getTextStart()

Specified by:

getTextStart in interface javax.xml.stream.XMLStreamReader

Overrides:

getTextStart in class XMLStreamReaderWrapper

hasText

public boolean hasText()

Specified by:

hasText in interface javax.xml.stream.XMLStreamReader

Overrides:

hasText in class XMLStreamReaderWrapper

isCharacters

public boolean isCharacters()

Specified by:

isCharacters in interface javax.xml.stream.XMLStreamReader

Overrides:

isCharacters in class XMLStreamReaderWrapper

isStartElement

public boolean isStartElement()

Specified by:

isStartElement in interface javax.xml.stream.XMLStreamReader

Overrides:

isStartElement in class XMLStreamReaderWrapper

isEndElement

public boolean isEndElement()

Specified by:

isEndElement in interface javax.xml.stream.XMLStreamReader

Overrides:

isEndElement in class XMLStreamReaderWrapper

hasName

public boolean hasName()

Specified by:

hasName in interface javax.xml.stream.XMLStreamReader

Overrides:

hasName in class XMLStreamReaderWrapper

isWhiteSpace

public boolean isWhiteSpace()

Specified by:

isWhiteSpace in interface javax.xml.stream.XMLStreamReader

Overrides:

isWhiteSpace in class XMLStreamReaderWrapper

require

public void require(int type,
                    java.lang.String namespaceURI,
                    java.lang.String localName)
             throws javax.xml.stream.XMLStreamException

Specified by:

require in interface javax.xml.stream.XMLStreamReader

Overrides:

require in class XMLStreamReaderWrapper

Throws:

javax.xml.stream.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 java.lang.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 javax.activation.DataHandler getDataHandler()
                                            throws javax.xml.stream.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:

javax.xml.stream.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

getXOPEncodedStream

XOPEncodedStream getXOPEncodedStream()