ws-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andreas Veithen (JIRA)" <>
Subject [jira] Resolved: (AXIOM-313) Add a new getDocumentElement method to StAXOMBuilder that allows to discard the OMDocument
Date Wed, 29 Dec 2010 19:49:45 GMT


Andreas Veithen resolved AXIOM-313.

    Resolution: Fixed

> Add a new getDocumentElement method to StAXOMBuilder that allows to discard the OMDocument
> ------------------------------------------------------------------------------------------
>                 Key: AXIOM-313
>                 URL:
>             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

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:
For additional commands, e-mail:

View raw message