org.apache.axiom.om.ds

## Class InputStreamDataSource

- java.lang.Object
- - org.apache.axiom.om.ds.OMDataSourceExtBase
  - - org.apache.axiom.om.ds.InputStreamDataSource

- All Implemented Interfaces:
    OMDataSource, OMDataSourceExt

      public class InputStreamDataSource
      extends OMDataSourceExtBase

  InputStream is an example OMDataSourceExt. Use it to insert a (InputStream, encoding) into an OM Tree. This data source is useful for placing an InputStream into an OM tree, instead of having a deeply nested tree.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `InputStreamDataSource.Data` Object containing the InputStream/encoding pair

  - ### Field Summary

    - ### Fields inherited from interface org.apache.axiom.om.OMDataSourceExt

      `LOSSY_PREFIX`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `InputStreamDataSource(InputStream is, String encoding)` Constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close the DataSource and free its resources.
    `OMDataSourceExt` | `copy()` Return a InputStreamDataSource backed by a ByteArrayInputStream
    `Object` | `getObject()` Get the object that backs this data source.
    `javax.xml.stream.XMLStreamReader` | `getReader()` Get parser for element data.
    `byte[]` | `getXMLBytes(String encoding)` Returns a byte[] representing the xml data
    `InputStream` | `getXMLInputStream(String encoding)` Returns a InputStream representing the xml data
    `boolean` | `isDestructiveRead()` Returns true if reading the backing object is destructive.
    `boolean` | `isDestructiveWrite()` Returns true if writing the backing object is destructive.
    `void` | `serialize(OutputStream output, OMOutputFormat format)` Serializes element data directly to stream.
    `void` | `serialize(javax.xml.stream.XMLStreamWriter xmlWriter)` Serializes element data directly to StAX writer.

    - ### Methods inherited from class org.apache.axiom.om.ds.OMDataSourceExtBase

      `getProperty, hasProperty, serialize, setProperty`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### InputStreamDataSource

          public InputStreamDataSource(InputStream is,
                                       String encoding)

      Constructor
      Parameters:
        `is` -
        `encoding` -

  - ### Method Detail

    - #### serialize

          public void serialize(OutputStream output,
                                OMOutputFormat format)
                         throws javax.xml.stream.XMLStreamException

      Description copied from interface: `OMDataSource`
      Serializes element data directly to stream.

      It is assumed that this method consumes the content (i.e. destroys the backing object) unless the data source also implements `OMDataSourceExt` and `OMDataSourceExt.isDestructiveWrite()` returns `false`.

      Specified by:
        `serialize` in interface `OMDataSource`
      Overrides:
        `serialize` in class `OMDataSourceExtBase`
      Parameters:
        `output` - destination stream for element XML text
        `format` - Output format information. The implementation must use this information to choose the correct character set encoding when writing to the output stream. This parameter must not be null.
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### serialize

          public void serialize(javax.xml.stream.XMLStreamWriter xmlWriter)
                         throws javax.xml.stream.XMLStreamException

      Description copied from interface: `OMDataSource`
      Serializes element data directly to StAX writer.

      The implementation of this method must satisfy the following requirements:

      - The implementation MUST NOT not write any start document or end document event, i.e. it MUST NOT use `XMLStreamWriter.writeStartDocument()`, `XMLStreamWriter.writeStartDocument(String)`, `XMLStreamWriter.writeStartDocument(String, String)` or `XMLStreamWriter.writeEndElement()`.
      - The implementation MUST output a single element (hereafter called the root element). It MUST NOT output any other content before or after that element.
      - The implementation MUST specify the namespace URI when writing an element, i.e. it MUST NOT use the namespace unaware methods `XMLStreamWriter.writeStartElement(String)` or `XMLStreamWriter.writeEmptyElement(String)`. On the other hand, it MAY use the namespace unaware `XMLStreamWriter.writeAttribute(String, String)` method, provided that the specified name is an `NCName`.
      - The implementation MUST ensure that the produced XML is well formed with respect to namespaces, i.e. it MUST generate the required namespace declarations using `XMLStreamWriter.writeNamespace(String, String)` and `XMLStreamWriter.writeDefaultNamespace(String)`. It MUST NOT assume that the `XMLStreamWriter` performs any kind of namespace repairing (although that may be the case).
      - In addition the implementation MAY use `XMLStreamWriter.setPrefix(String, String)` and `XMLStreamWriter.setDefaultNamespace(String)` to track the namespace declarations it generates, so that the namespace context maintained by the `XMLStreamWriter` accurately reflects the namespace context in the output document. However, it MUST NOT call these methods before the start of the root element or after the end of the root element.
      - Since the element may be serialized as part of a larger document, the implementation MUST take into account the pre-existing namespace context (which can be queried using `XMLStreamWriter.getPrefix(String)` and `XMLStreamWriter.getNamespaceContext()`). This means that the implementation MUST NOT assume that the empty prefix is bound to the empty namespace URI. Therefore if the implementation outputs elements that have no namespace, it MUST generate namespace declarations of the form `xmlns=""` in the appropriate locations. In addition it MAY use the namespace context information to minimize the number of generated namespace declarations (by reusing already bound prefixes).
      - If the implementation produces base64 binary data (that could be optimized using XOP/MTOM), then it SHOULD use `XMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandler, String, boolean)` or `XMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandlerProvider, String, boolean)` to write the data to the stream. If this is not possible (e.g. because the content is produced by a third party library that is not aware of these APIs), then the implementation MUST use the following approach:
        - If the `XMLStreamWriter` is an `MTOMXMLStreamWriter`, then the implementation MAY use `MTOMXMLStreamWriter.prepareDataHandler(DataHandler)` and generate the necessary `xop:Include` elements itself. In this case, the implementation MAY use `MTOMXMLStreamWriter.isOptimized()` to check if XOP/MTOM is enabled at all. Alternatively, instead of handling `MTOMXMLStreamWriter` in a special way, the implementation MAY use the approach described in the next item. This works because `MTOMXMLStreamWriter` exposes the `DataHandlerWriter` extension. However, this causes a slight overhead because the stream is first XOP decoded and then reencoded again.
        - If the `XMLStreamWriter` exposes the `DataHandlerWriter` extension, but is not an `MTOMXMLStreamWriter` (or is an `MTOMXMLStreamWriter`, but the implementation doesn't implement the approach described in the previous item), then the implementation MUST wrap the `XMLStreamWriter` in an `XOPDecodingStreamWriter` and write `xop:Include` elements to that wrapper, so that they can be translated into appropriate calls to the `DataHandlerWriter`. This requirement is important for two reasons:
          - It allows Axiom to respect the contract of the `OMSerializable.serialize(XMLStreamWriter, boolean)` method.
          - If the `OMDataSource` is push-only (see `AbstractPushOMDataSource`), then it enables `OMSourcedElement` to create `OMText` nodes for the binary content in an efficient way.
        - In all other cases, the implementation MUST use `XMLStreamWriter.writeCharacters(String)` or `XMLStreamWriter.writeCharacters(char[], int, int)` to write the base64 encoded data to the stream.
      - The implementation MUST NOT call `XMLStreamWriter.close()`.

      On the other hand, the caller of this method (typically an `OMSourcedElement` instance) must ensure that the following requirements are satisfied:

      - The namespace context information provided by `XMLStreamWriter.getPrefix(String)` and `XMLStreamWriter.getNamespaceContext()` MUST accurately reflect the actual namespace context at the location in the output document where the root element is serialized. Note that this requirement may be relaxed if the caller implements some form of namespace repairing.

      It is assumed that this method consumes the content (i.e. destroys the backing object) unless the data source also implements `OMDataSourceExt` and `OMDataSourceExt.isDestructiveWrite()` returns `false`.

      Specified by:
        `serialize` in interface `OMDataSource`
      Overrides:
        `serialize` in class `OMDataSourceExtBase`
      Parameters:
        `xmlWriter` - destination writer
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getReader

          public javax.xml.stream.XMLStreamReader getReader()
                                                     throws javax.xml.stream.XMLStreamException

      Description copied from interface: `OMDataSource`
      Get parser for element data. In the general case this may require the data source to serialize data as XML text and then parse that text.

      It is assumed that this method consumed the content (i.e. destroys the backing object) unless the data source also implements `OMDataSourceExt` and `OMDataSourceExt.isDestructiveRead()` returns `false`.

      `OMSourcedElement` implementations are expected to call `XMLStreamReader.close()` on the returned reader as soon as the element is completely built.

      Returns:
        element parser
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getXMLInputStream

          public InputStream getXMLInputStream(String encoding)
                                        throws UnsupportedEncodingException

      Description copied from interface: `OMDataSourceExt`
      Returns a InputStream representing the xml data
      Specified by:
        `getXMLInputStream` in interface `OMDataSourceExt`
      Overrides:
        `getXMLInputStream` in class `OMDataSourceExtBase`
      Parameters:
        `encoding` - String encoding of InputStream
      Returns:
        InputStream
      Throws:
        `UnsupportedEncodingException`

    - #### getObject

          public Object getObject()

      Description copied from interface: `OMDataSourceExt`
      Get the object that backs this data source. Application code should in general not call this method directly, but use `OMSourcedElement.getObject(Class)` instead.

      Data sources that support non destructive read/write should return the object from which the XML is produced. Data sources with destructive read/write should return a non null value only if the backing object has not been consumed yet (even partially).

      Returns:
        the backing object, or `null` if the data source has no backing object or if the backing object can't be accessed in a safe way

    - #### isDestructiveRead

          public boolean isDestructiveRead()

      Description copied from interface: `OMDataSourceExt`
      Returns true if reading the backing object is destructive. An example of an object with a destructive read is an InputSteam. The owning OMSourcedElement uses this information to detemine if OM tree expansion is needed when reading the OMDataSourceExt.
      Returns:
        boolean

    - #### isDestructiveWrite

          public boolean isDestructiveWrite()

      Description copied from interface: `OMDataSourceExt`
      Returns true if writing the backing object is destructive. An example of an object with a destructive write is an InputStream. The owning OMSourcedElement uses this information to detemine if OM tree expansion is needed when writing the OMDataSourceExt.
      Returns:
        boolean

    - #### getXMLBytes

          public byte[] getXMLBytes(String encoding)
                             throws UnsupportedEncodingException

      Description copied from interface: `OMDataSourceExt`
      Returns a byte[] representing the xml data
      Parameters:
        `encoding` - String encoding of InputStream
      Returns:
        byte[]
      Throws:
        `UnsupportedEncodingException`
      See Also:
        `OMDataSourceExt.getXMLInputStream(String)`

    - #### close

          public void close()

      Description copied from interface: `OMDataSourceExt`
      Close the DataSource and free its resources.

    - #### copy

          public OMDataSourceExt copy()

      Return a InputStreamDataSource backed by a ByteArrayInputStream
      Returns:
        the copy of the data source, or `null` if the data source can't be copied (e.g. because it is destructive)

Copyright © The Apache Software Foundation. All Rights Reserved.