ws-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andreas Veithen (JIRA)" <j...@apache.org>
Subject [jira] [Work started] (AXIOM-412) DOOM's OMFactory implementation should be stateless
Date Sat, 21 Apr 2012 12:14:35 GMT

     [ https://issues.apache.org/jira/browse/AXIOM-412?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]

Work on AXIOM-412 started by Andreas Veithen.

> 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-unsubscribe@ws.apache.org
For additional commands, e-mail: dev-help@ws.apache.org


Mime
View raw message