org.apache.axiom.om

## Interface OMDataSourceExt

- All Superinterfaces:
    OMDataSource
  All Known Implementing Classes:
    AbstractOMDataSource, AbstractPullOMDataSource, AbstractPushOMDataSource, ByteArrayDataSource, CharArrayDataSource, InputStreamDataSource, JAXBOMDataSource, OMDataSourceExtBase, ParserInputStreamDataSource, WrappedTextNodeOMDataSource, WrappedTextNodeOMDataSourceFromDataSource, WrappedTextNodeOMDataSourceFromReader

      public interface OMDataSourceExt
      extends OMDataSource

  Interface to a backing object that can can be read and written as XML. To plug an arbitrary object into an OM tree. Follow these steps 1) Provide a class that implements OMDataSourceExt. 2) Use OMFactory.createOMElement(OMDataSource, String, OMNamespace) to build an OMSourcedElement. 3) Add the OMSourcedElement to the OM tree. OMDataSourceExt provides additional methods that are not available on the original OMDataSource.
  See Also:
    `OMDataSource`, `OMSourcedElement`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `LOSSY_PREFIX` Deprecated. To create an `OMSourcedElement` with unknown prefix, use `OMFactory.createOMElement(OMDataSource, String, OMNamespace)` and pass `null` as prefix.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close the DataSource and free its resources.
    `OMDataSourceExt` | `copy()` Create a copy of the data source.
    `Object` | `getObject()` Get the object that backs this data source.
    `Object` | `getProperty(String key)` Query a property stored on the OMDataSource
    `byte[]` | `getXMLBytes(String encoding)` Returns a byte[] representing the xml data
    `InputStream` | `getXMLInputStream(String encoding)` Returns a InputStream representing the xml data
    `boolean` | `hasProperty(String key)` Returns true if property is set
    `boolean` | `isDestructiveRead()` Returns true if reading the backing object is destructive.
    `boolean` | `isDestructiveWrite()` Returns true if writing the backing object is destructive.
    `Object` | `setProperty(String key, Object value)` Set a property on the OMDataSource

    - ### Methods inherited from interface org.apache.axiom.om.OMDataSource

      `getReader, serialize, serialize, serialize`

- - ### Field Detail

    - #### LOSSY_PREFIX

          static final String LOSSY_PREFIX

      Deprecated. To create an `OMSourcedElement` with unknown prefix, use `OMFactory.createOMElement(OMDataSource, String, OMNamespace)` and pass `null` as prefix.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getObject

          Object getObject()

      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

          boolean isDestructiveRead()

      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

          boolean isDestructiveWrite()

      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

    - #### getXMLInputStream

          InputStream getXMLInputStream(String encoding)
                                 throws UnsupportedEncodingException

      Returns a InputStream representing the xml data
      Parameters:
        `encoding` - String encoding of InputStream
      Returns:
        InputStream
      Throws:
        `UnsupportedEncodingException`

    - #### getXMLBytes

          byte[] getXMLBytes(String encoding)
                      throws UnsupportedEncodingException

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

    - #### close

          void close()

      Close the DataSource and free its resources.

    - #### copy

          OMDataSourceExt copy()

      Create a copy of the data source. This method is used by `OMInformationItem.clone(OMCloneOptions)` when the `OMCloneOptions.isCopyOMDataSources()` option is enabled. If the data source is immutable and stateless, then it may return a reference to itself instead of creating a new data source instance.
      Returns:
        the copy of the data source, or `null` if the data source can't be copied (e.g. because it is destructive)

    - #### hasProperty

          boolean hasProperty(String key)

      Returns true if property is set
      Parameters:
        `key` -
      Returns:
        TODO

    - #### getProperty

          Object getProperty(String key)

      Query a property stored on the OMDataSource
      Parameters:
        `key` -
      Returns:
        value or null

    - #### setProperty

          Object setProperty(String key,
                             Object value)

      Set a property on the OMDataSource
      Parameters:
        `key` -
        `value` -
      Returns:
        old property object or null

Copyright © The Apache Software Foundation. All Rights Reserved.