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

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