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

List:       xmlrpc-user
Subject:    [jira] Commented: (AXIOM-313) Add a new getDocumentElement method
From:       "Hudson (JIRA)" <jira () apache ! org>
Date:       2010-12-29 18:09:45
Message-ID: 20834153.61851293646185679.JavaMail.jira () thor
[Download RAW message or body]


    [ 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: 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]