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.

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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.
    `String` | `getElementText()`
    `int` | `getEventType()`
    `String` | `getLocalName()`
    `javax.xml.stream.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(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

    - #### 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 Object getProperty(String name)
                             throws IllegalArgumentException

      Specified by:
        `getProperty` in interface `javax.xml.stream.XMLStreamReader`
      Overrides:
        `getProperty` in class `XMLStreamReaderWrapper`
      Throws:
        `IllegalArgumentException`

    - #### getElementText

          public 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 String getPrefix()

      Specified by:
        `getPrefix` in interface `javax.xml.stream.XMLStreamReader`
      Overrides:
        `getPrefix` in class `XMLStreamReaderWrapper`

    - #### getNamespaceURI

          public String getNamespaceURI()

      Specified by:
        `getNamespaceURI` in interface `javax.xml.stream.XMLStreamReader`
      Overrides:
        `getNamespaceURI` in class `XMLStreamReaderWrapper`

    - #### getLocalName

          public String getLocalName()

      Specified by:
        `getLocalName` in interface `javax.xml.stream.XMLStreamReader`
      Overrides:
        `getLocalName` in class `XMLStreamReaderWrapper`

    - #### getName

          public 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 String getNamespaceURI(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 String getNamespacePrefix(int index)

      Specified by:
        `getNamespacePrefix` in interface `javax.xml.stream.XMLStreamReader`
      Overrides:
        `getNamespacePrefix` in class `XMLStreamReaderWrapper`

    - #### getNamespaceURI

          public String getNamespaceURI(int index)

      Specified by:
        `getNamespaceURI` in interface `javax.xml.stream.XMLStreamReader`
      Overrides:
        `getNamespaceURI` in class `XMLStreamReaderWrapper`

    - #### getText

          public 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,
                              String namespaceURI,
                              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 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

Copyright © The Apache Software Foundation. All Rights Reserved.