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.9
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.
