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:

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
[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 a 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 no impact on the behavior visible to the application code.


Method Summary
 DOMImplementation getDOMImplementation()
          Get the DOMImplementation instance.
 DocumentBuilderFactory newDocumentBuilderFactory()
          Create a new DocumentBuilderFactory.
 
Methods inherited from interface org.apache.axiom.om.OMMetaFactory
createOMBuilder, createOMBuilder, createOMBuilder, createOMBuilder, createOMBuilder, createSOAPModelBuilder, createSOAPModelBuilder, createStAXOMBuilder, createStAXSOAPModelBuilder, 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


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.