Package org.apache.axiom.om.dom

## Interface DOMMetaFactory

- All Superinterfaces:
    `OMMetaFactory`

      public interface DOMMetaFactory
      extends OMMetaFactory

  Extension interface for `OMMetaFactory` implementations that support `OMAbstractFactory.FEATURE_DOM`.

  Axiom implementations supporting this feature MUST conform to the Axiom API as well as the DOM API, and nodes created by the implementation MUST implement both the Axiom interfaces and the DOM interfaces corresponding, as specified by the following table:

  Mapping between Axiom and DOM interfaces
  Axiom interface | DOM interface
  --- | ---
  `OMDocument` | `Document`
  `OMDocType` | `DocumentType`
  `OMElement` | `Element` [1]
  `OMAttribute` | `Attr` [2]
  `OMText` with type `OMNode.TEXT_NODE` or `OMNode.SPACE_NODE` | `Text`
  `OMText` with type `OMNode.CDATA_SECTION_NODE` | `CDATASection`
  `OMComment` | `Comment`
  `OMProcessingInstruction` | `ProcessingInstruction`
  `OMEntityReference` | `EntityReference`
  - | `DocumentFragment`

  [1]
    Only applies to elements created using DOM 2 methods such as `Document.createElementNS(String, String)`.
  [2]
    Only applies to attributes created using DOM 2 methods such as `Document.createAttributeNS(String, String)` and that don't represent namespace declarations. Axiom doesn't use `OMAttribute` to represent namespace declarations, and `OMNamespace` instances representing namespace declarations are not expected to implement `Attr`.

  The Axiom API is designed such that nodes are created using a factory (`OMFactory` or `SOAPFactory`) that is expected to be a singleton and stateless. On the other hand, in the DOM API, the `Document` instance plays the role of node factory, and each node (explicitly or implicitly) keeps a reference to the `Document` instance from which it was created (the owner document). To address this difference in a consistent way and to make it possible to use both the Axiom API and the DOM API on the same object model instance, the implementation MUST conform to the following rules:

  1. Nodes created using the Axiom API and for which a parent node is specified will have as their owner document the owner document of the parent. Note that this is simply a consequence of the fact that DOM is designed such that two nodes that are part of the same tree must have the same owner document.
  2. Nodes created using the Axiom API and for which no parent node is specified will get a new owner document. This applies to methods in `OMFactory` that don't have an `OMContainer` parameter or that are invoked with a `null` `OMContainer` as well as to methods such as `OMElement.cloneOMElement()`.
  3. When the Axiom API is used to add a node A as a child of another node B, then the owner document of B becomes the new owner document of A and all its descendants. In DOM parlance, this means that node A is automatically adopted by the owner document of B. This implies that no method defined by the Axiom API will ever trigger a `DOMException.WRONG_DOCUMENT_ERR` error.
  4. When a node is detached from its parent using the Axiom API, it will get a new owner document. This rule exists for consistency because together with the other rules it implies that every tree has a distinct owner document as long as only the Axiom API is used to manipulate the nodes. That rule applies to the following methods:
     - `OMNode.detach()`
     - `OMElement.removeAttribute(OMAttribute)`
     - `OMElement.setText(String)` and `OMElement.setText(QName)` (in the case where the side effect of the invocation is to detach preexisting nodes)
     - `OMElement.addAttribute(OMAttribute)` and `OMElement.addAttribute(String, String, OMNamespace)` (in the case where the new attribute replaces an existing one, which will be removed from its owner)
  5. `Document` instances created using the `DocumentBuilderFactory` and `DOMImplementation` APIs as well as the `Document` instances implicitly created (as owner documents) by the Axiom API will have as their `OMFactory` (as reported by `OMInformationItem.getOMFactory()`) the instance returned by `OMMetaFactory.getOMFactory()`. Any additional nodes created using the DOM API will inherit the `OMFactory` of the owner document.

  The implementation SHOULD instantiate the implicitly created owner documents lazily (typically when explicitly requested using DOM's `Node.getOwnerDocument()` API) to avoid creating a large number of temporary `Document` instances when the Axiom API is used. Note however that this has no impact on the behavior visible to the application code.

  As indicated in the table above, although `Attr` and `DocumentFragment` nodes are parent nodes in the DOM API, they MUST NOT implement the `OMContainer` interface. Only `OMDocument` and `OMElement` instances can implement that interface.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `DOMImplementation` | `getDOMImplementation()` | Get the `DOMImplementation` instance.
    `DocumentBuilderFactory` | `newDocumentBuilderFactory()` | Create a new `DocumentBuilderFactory`.

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

      `getOMFactory, getSOAP11Factory, getSOAP12Factory`

- - ### Method Detail

    - #### newDocumentBuilderFactory

          DocumentBuilderFactory newDocumentBuilderFactory()

      Create a new `DocumentBuilderFactory`. Since Axiom doesn't support non namespace aware processing, the returned factory is always configured with `namespaceAware` set to `true` (in contrast to the default settings used by `DocumentBuilderFactory.newInstance()`).
      Returns:
        the factory instance

    - #### getDOMImplementation

          DOMImplementation getDOMImplementation()

      Get the `DOMImplementation` instance.
      Returns:
        the `DOMImplementation` instance