org.apache.axiom.om

## Interface OMSourcedElement

- All Superinterfaces:
    OMContainer, OMElement, OMInformationItem, OMNamedInformationItem, OMNode, OMSerializable
  All Known Subinterfaces:
    SOAPHeaderBlock

      public interface OMSourcedElement
      extends OMElement

  Element whose data is backed by an arbitrary Java object. The backing Java object is accessed via the `OMDataSource` (or `OMDataSourceExt`) interface.

  An OMSourcedElement can be in one of two states:

  Not Expanded
    In this state the backing object is used to read and write the XML.
  Expanded
    In this state, the OMSourcedElement is backed by a normal OM tree.

  Here are the steps to place an arbitrary java object into the OM tree:

  1. Write an `OMDataSourceExt` implementation that provides access to your Java object.
  2. Use `OMFactory.createOMElement(OMDataSource, String, OMNamespace)` to create the OMSourcedElement.
  3. Attach the OMSourcedElement to the tree.

- - ### Field Summary

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

      `CDATA_SECTION_NODE, COMMENT_NODE, DTD_NODE, ELEMENT_NODE, ENTITY_REFERENCE_NODE, PI_NODE, SPACE_NODE, TEXT_NODE`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `OMDataSource` | `getDataSource()`
    `Object` | `getObject(Class dataSourceClass)` Get the object that backs the data source set on this element.
    `boolean` | `isExpanded()`
    `OMDataSource` | `setDataSource(OMDataSource dataSource)` Deprecated. This method is deprecated because its semantics are not clearly defined. In particular it is unspecified whether the name of the element may change as a result of an invocation of this method.

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

      `addAttribute, addAttribute, cloneOMElement, declareDefaultNamespace, declareNamespace, declareNamespace, findNamespace, findNamespaceURI, getAllAttributes, getAllDeclaredNamespaces, getAttribute, getAttributeValue, getChildElements, getDefaultNamespace, getFirstElement, getLineNumber, getNamespaceContext, getNamespacesInScope, getText, getTextAsQName, getTextAsStream, removeAttribute, resolveQName, serialize, serialize, serialize, serialize, serializeAndConsume, serializeAndConsume, serializeAndConsume, serializeAndConsume, setLineNumber, setNamespace, setNamespaceWithNoFindInCurrentScope, setText, setText, toString, toStringWithConsume, undeclarePrefix, writeTextTo`

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

      `buildWithAttachments, detach, discard, getNextOMSibling, getParent, getPreviousOMSibling, getType, insertSiblingAfter, insertSiblingBefore`

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

      `addChild, getBuilder, getChildren, getChildrenWithLocalName, getChildrenWithName, getChildrenWithNamespaceURI, getDescendants, getFirstChildWithName, getFirstOMChild, getSAXResult, getSAXSource, getXMLStreamReader, getXMLStreamReader, getXMLStreamReader, getXMLStreamReaderWithoutCaching, removeChildren`

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

      `build, close, isComplete, serialize, serialize, serializeAndConsume`

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

      `clone, getOMFactory`

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

      `getLocalName, getNamespace, getNamespaceURI, getPrefix, getQName, hasName, setLocalName, setNamespace`

- - ### Method Detail

    - #### isExpanded

          boolean isExpanded()

      Returns:
        true if tree is expanded or being expanded.

    - #### getDataSource

          OMDataSource getDataSource()

      Returns:
        OMDataSource

    - #### setDataSource

          OMDataSource setDataSource(OMDataSource dataSource)

      Deprecated. This method is deprecated because its semantics are not clearly defined. In particular it is unspecified whether the name of the element may change as a result of an invocation of this method.

    - #### getObject

          Object getObject(Class dataSourceClass)

      Get the object that backs the data source set on this element. This method provides a safe way to access that object. It will return a non null value if all of the following conditions are satisfied:
      1. The element is configured with an `OMDataSource` of the type specified by the `dataSourceClass` parameter (in the sense of `Class.isInstance(Object)`).
      2. The `OMDataSourceExt.getObject()` method returns a non null value on the configured data source.
      3. The instance can ensure that the content of the element has not been modified. This is always the case if the element has not been expanded (i.e. if `isExpanded()` returns `false`), but the implementation may use additional mechanisms to detect changes after expansion of the element.
      These are exactly the conditions that must be satisfied if the application code wants to implement optimized processing of the sourced element by accessing the backing object.
      Parameters:
        `dataSourceClass` - the expected data source class; must be assignment compatible with `OMDataSourceExt`
      Returns:
        the backing Java object or `null` if the conditions specified above are not satisfied

Copyright © The Apache Software Foundation. All Rights Reserved.