[
https://issues.apache.org/jira/browse/AXIOM-313?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12975858#action_12975858
]
Hudson commented on AXIOM-313:
------------------------------
Integrated in ws-axiom-trunk #295 (See
[https://hudson.apache.org/hudson/job/ws-axiom-trunk/295/])
Implemented the new API described in AXIOM-313 so that we can get rid of
some references to OMNodeEx (which is an internal API) in Axis2.
> Add a new getDocumentElement method to StAXOMBuilder that allows to discard
> the OMDocument
> ------------------------------------------------------------------------------------------
>
> Key: AXIOM-313
> URL: https://issues.apache.org/jira/browse/AXIOM-313
> Project: Axiom
> Issue Type: Improvement
> Reporter: Andreas Veithen
> Assignee: Andreas Veithen
> Priority: Minor
> Fix For: 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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
