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

java.lang.Object
  extended by org.apache.axiom.util.stax.wrapper.XMLStreamReaderWrapper
      extended by 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
XOPDecodingStreamReader(XMLStreamReader parent, MimePartProvider mimePartProvider)
          Constructor.
 
Method Summary
 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:

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


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.