Extension interface for {@link OMMetaFactory} implementations that support{@link 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:
| Axiom interface | DOM interface |
| {@link OMDocument} | {@link Document} |
| {@link OMDocType} | {@link DocumentType} |
| {@link OMElement} | {@link Element} [1] |
| {@link OMAttribute} | {@link Attr} [2] |
| {@link OMText} with type {@link OMNode#TEXT_NODE} or {@link OMNode#SPACE_NODE} | {@link Text} |
| {@link OMText} with type {@link OMNode#CDATA_SECTION_NODE} | {@link CDATASection} |
| {@link OMComment} | {@link Comment} |
| {@link OMProcessingInstruction} | {@link ProcessingInstruction} |
| {@link OMEntityReference} | {@link EntityReference} |
- [1]
- Only applies to elements created using DOM 2 methods such as {@link Document#createElementNS(String,String)}.
- [2]
- Only applies to attributes created using DOM 2 methods such as {@link Document#createAttributeNS(String,String)} and that don't represent namespacedeclarations. Axiom doesn't use {@link OMAttribute} to represent namespace declarations, and{@link OMNamespace} instances representing a namespace declarations are not expected to implement{@link Attr}.
The Axiom API is designed such that nodes are created using a factory ( {@link OMFactory} or{@link SOAPFactory}) that is expected to be a singleton and stateless. On the other hand, in the DOM API, the {@link Document} instance plays the role of node factory, and each node (explicitlyor implicitly) keeps a reference to the {@link Document} instance from which it was created (theowner 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:
- 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.
- 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 {@link OMFactory} that don't have an{@link OMContainer} parameter or that are invoked with a
null {@link OMContainer}as well as to methods such as {@link OMElement#cloneOMElement()}. - 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 {@link DOMException#WRONG_DOCUMENT_ERR}error.
- 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:
- {@link OMNode#detach()}
- {@link OMElement#removeAttribute(OMAttribute)}
- {@link OMElement#setText(String)} and {@link OMElement#setText(QName)} (in the case where theside effect of the invocation is to detach preexisting nodes)
- {@link OMElement#addAttribute(OMAttribute)} and{@link OMElement#addAttribute(String,String,OMNamespace)} (in the case where the new attributereplaces an existing one, which will be removed from its owner)
- {@link Document} instances created using the {@link DocumentBuilderFactory} and{@link DOMImplementation} APIs as well as the {@link Document} instances implicitly created (asowner documents) by the Axiom API will have as their {@link OMFactory} (as reported by{@link OMInformationItem#getOMFactory()}) the instance returned by {@link OMMetaFactory#getOMFactory()}. Any additional nodes created using the DOM API will inherit the {@link OMFactory} of the owner document.
The implementation SHOULD instantiate the implicitly created owner documents lazily (typically when explicitly requested using DOM's {@link Node#getOwnerDocument()} API) to avoid creating alarge number of temporary {@link Document} instances when the Axiom API is used. Note howeverthat this no impact on the behavior visible to the application code.