[
https://issues.apache.org/jira/browse/WSCOMMONS-416?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Andreas Veithen updated WSCOMMONS-416:
--------------------------------------
Fix Version/s: (was: Axiom 1.2.10)
Axiom 1.2.11
> Add a new getDocumentElement method to StAXOMBuilder that allows to discard
> the OMDocument
> ------------------------------------------------------------------------------------------
>
> Key: WSCOMMONS-416
> URL: https://issues.apache.org/jira/browse/WSCOMMONS-416
> Project: WS-Commons
> Issue Type: Improvement
> Components: AXIOM
> Reporter: Andreas Veithen
> Assignee: Andreas Veithen
> Priority: Minor
> Fix For: Axiom 1.2.11
>
>
> Very often StAXOMBuilder is used to build an OMElement that is added to an
> existing OM tree. Normally the code that does this would look like this:
> StAXOMBuilder builder = ...
> elementFromExistingTree.addChild(builder.getDocumentElement());
> However this will detach the element returned by builder.getDocumentElement()
> and therefore build it. This is in general not what is wanted. In order to
> defer building of the element, many people use the following code:
> StAXOMBuilder builder = ...
> OMNodeEx documentElement = (OMNodeEx)builder.getDocumentElement();
> documentElement.setParent(null);
> elementFromExistingTree.addChild(documentElement);
> Examples can be found in Axis2's ApplicationXMLBuilder and in
> SerializationTest#testOMSerializationWithTwoNonBuiltOMElements.
> There are two issues here:
> * OMNodeEx is an internal interface (that's why it is located in an "impl"
> package) and client code should avoid using this kind of interface.
> * To understand the subtle difference between the two code snippets shown
> above, the user needs some advanced knowledge about Axiom's internals.
> The proposal is to:
> 1) Add a new method to StAXOMBuilder with a following signature:
> OMElement getDocumentElement(boolean discardDocument)
> If discardDocument is false, this method would behave the same way as the
> existing getDocumentElement() method. If discardDocument is true, it would
> use the setParent(null) trick to detach the element from the document without
> building it (which renders the OMDocument unusable, hence the name of the
> parameter).
> 2) Clearly document the effect of the discardDocument parameter and explain
> in which case it should be used.
> 3) Scan the Axis2 (and Synapse, etc.) code for usage of the setParent(null)
> pattern and change it to use the new method.
> 4) [Optional] Deprecate the getDocumentElement() method to force people to
> review their code.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
