[prev in list] [next in list] [prev in thread] [next in thread] 

List:       xmlrpc-user
Subject:    [jira] Resolved: (AXIOM-313) Add a new getDocumentElement method to
From:       "Andreas Veithen (JIRA)" <jira () apache ! org>
Date:       2010-12-29 19:49:45
Message-ID: 15994015.63281293652185872.JavaMail.jira () thor
[Download RAW message or body]


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

Andreas Veithen resolved AXIOM-313.
-----------------------------------

    Resolution: Fixed

> 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


[prev in list] [next in list] [prev in thread] [next in thread]