[
https://issues.apache.org/jira/browse/AXIOM-412?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13259926#comment-13259926
]
Hudson commented on AXIOM-412:
------------------------------
Integrated in ws-axiom-trunk #900 (See
[https://builds.apache.org/job/ws-axiom-trunk/900/])
AXIOM-412: Some documentation updates. (Revision 1329401)
Result = SUCCESS
veithen :
Files :
*
/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/dom/DOMMetaFactory.java
> DOOM's OMFactory implementation should be stateless
> ---------------------------------------------------
>
> Key: AXIOM-412
> URL: https://issues.apache.org/jira/browse/AXIOM-412
> Project: Axiom
> Issue Type: Improvement
> Components: DOOM
> Affects Versions: 1.2.12
> Reporter: Andreas Veithen
> Assignee: Andreas Veithen
> Fix For: 1.2.14
>
>
> There is a sort of "impedance mismatch" between the Axiom API and DOM because
> * 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;
> * 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").
> The approach currently used by DOOM to solve that issue is to have a stateful
> OMFactory implementation which has a reference to a (OM)Document instance.
> That (OM)Document instance is then used as the owner document for nodes
> created using the Axiom API [Well, actually it is a bit more complicated and
> obscure than that...]. For this to work, the application code is required to
> request an OMFactory once and only once for each document created. This is
> one of the reasons why in general code written for the standard Axiom
> implementation (LLOM) doesn't work well when switching to DOOM. In addition,
> although the implementation of that design is relatively simple, it makes
> DOOM quite obscure from the user's perspective.
> There is an alternative approach to solve the Axiom/DOM impedance mismatch
> which doesn't require a stateful OMFactory implementation. It is based on the
> following set of rules that determine how the DOM owner document is handled
> when nodes are created and manipulated using the Axiom API:
> (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.
> 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. That is unavoidable if one wants a
> stateless/singleton OMFactory.
> (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 rule ensures that any operation that is
> valid with the LLOM implementation will also work with DOOM (without
> triggering a WRONG_DOCUMENT_ERR exception and without violating the rule that
> all nodes in a tree must have the same owner document).
> (4) When a node is detached from its parent using the Axiom API, it will get
> a new owner document. This rule is not strictly required to make the approach
> work; it merely 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
> * OMElement#setText (in the case where the side effect of the invocation is
> to detach preexisting nodes)
> * OMElement#addAttribute (in the case where the new attribute replaces an
> existing one, which will be removed from its owner)
> If implemented literally, these rules would obviously have a performance
> impact because (depending on the usage pattern) a large number of temporary
> Document instances may be needed. In addition, rules (3) and (4) require an
> efficient way to change the owner document of an entire tree (more efficient
> than to traverse the entire tree). Therefore these rules would be
> supplemented by the following design choices:
> (5) Owner documents are created lazily, namely when explicitly requested
> using DOM's Node#getOwnerDocument() API (or when DOOM needs to access data
> that it choses to store in the owner document).
> (6) Only the root node of a tree stores a reference to the owner document. As
> noted above, all nodes in a tree must have the same owner document. Therefore
> it is not necessary for a node to have references to both its parent and its
> owner document. Instead, a node should have a single attribute that stores
> the reference either to the parent (if it has a parent) or to the owner
> document (if it has no parent), as well as a flag that indicates the meaning
> of the reference (this is important if the reference points to a Document
> instance, which would otherwise be ambiguous). With this design, changing the
> owner document of a tree is O(1) instead of O(N) where N is the number of
> nodes in the tree. However, requesting the owner document of a node is O(M)
> instead of O(1) with M the depth of the tree. This is a good tradeoff
> considering that
> * Axiom methods never need to check the owner document;
> * DOM methods need to check the owner document more often (basically for
> every node addition) than the owner document of a tree is changed, but M << N.
> It should be noted that switching from the current design to the new design
> proposed here is not entirely transparent for application code. It implies a
> change in behavior if nodes are first created and manipulated using the Axiom
> API and then later passed to DOM APIs such as appendChild. In that situation
> it is likely that with the new design, the nodes have different owner
> documents, while this was not the case with the old design (because the same
> OMFactory instance was used). Such application code needs to be changed to
> use Document#adoptNode where appropriate. However, it is expected that in the
> Axis2 universe, the impact will be limited to a few places in the SAAJ
> implementation as well as Rampart. There are quite some examples where these
> two components depended on incorrect behavior in DOOM's DOM implementation or
> other implementation details, so that in general they can only be expected to
> work with the Axiom version for which they were built. One may therefore
> assume that the impact is acceptable.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@ws.apache.org
For additional commands, e-mail: dev-h...@ws.apache.org
