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:
  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.