Interface DOMMetaFactory
-
- All Superinterfaces:
OMMetaFactory
public interface DOMMetaFactory extends OMMetaFactory
Extension interface forOMMetaFactoryimplementations that supportOMAbstractFactory.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 OMDocumentDocumentOMDocTypeDocumentTypeOMElementElement[1]OMAttributeAttr[2]OMTextwith typeOMNode.TEXT_NODEorOMNode.SPACE_NODETextOMTextwith typeOMNode.CDATA_SECTION_NODECDATASectionOMCommentCommentOMProcessingInstructionProcessingInstructionOMEntityReferenceEntityReference- 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 useOMAttributeto represent namespace declarations, andOMNamespaceinstances representing namespace declarations are not expected to implementAttr.
The Axiom API is designed such that nodes are created using a factory (
OMFactoryorSOAPFactory) that is expected to be a singleton and stateless. On the other hand, in the DOM API, theDocumentinstance plays the role of node factory, and each node (explicitly or implicitly) keeps a reference to theDocumentinstance 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:- 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
OMFactorythat don't have anOMContainerparameter or that are invoked with anullOMContaineras well as to methods such asOMElement.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
DOMException.WRONG_DOCUMENT_ERRerror. - 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)andOMElement.setText(QName)(in the case where the side effect of the invocation is to detach preexisting nodes)OMElement.addAttribute(OMAttribute)andOMElement.addAttribute(String, String, OMNamespace)(in the case where the new attribute replaces an existing one, which will be removed from its owner)
Documentinstances created using theDocumentBuilderFactoryandDOMImplementationAPIs as well as theDocumentinstances implicitly created (as owner documents) by the Axiom API will have as theirOMFactory(as reported byOMInformationItem.getOMFactory()) the instance returned byOMMetaFactory.getOMFactory(). Any additional nodes created using the DOM API will inherit theOMFactoryof 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 temporaryDocumentinstances 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
AttrandDocumentFragmentnodes are parent nodes in the DOM API, they MUST NOT implement theOMContainerinterface. OnlyOMDocumentandOMElementinstances can implement that interface.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description DOMImplementationgetDOMImplementation()Get theDOMImplementationinstance.DocumentBuilderFactorynewDocumentBuilderFactory()Create a newDocumentBuilderFactory.-
Methods inherited from interface org.apache.axiom.om.OMMetaFactory
getOMFactory, getSOAP11Factory, getSOAP12Factory
-
-
-
-
Method Detail
-
newDocumentBuilderFactory
DocumentBuilderFactory newDocumentBuilderFactory()
Create a newDocumentBuilderFactory. Since Axiom doesn't support non namespace aware processing, the returned factory is always configured withnamespaceAwareset totrue(in contrast to the default settings used byDocumentBuilderFactory.newInstance()).- Returns:
- the factory instance
-
getDOMImplementation
DOMImplementation getDOMImplementation()
Get theDOMImplementationinstance.- Returns:
- the
DOMImplementationinstance
-
-