[jira] Updated: (AXIOM-313) Add a new getDocumentElement method to StAXOMBuilder that allows to discard the OMDocument

["Andreas Veithen (JIRA)" <ji...@apache.org>]

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

Andreas Veithen updated AXIOM-313:
----------------------------------

    Component/s: API

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