[
https://issues.apache.org/jira/browse/WSCOMMONS-232?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Rich Scheuerle updated WSCOMMONS-232:
-------------------------------------
Attachment: patch.txt
Here is the patch with the changes and test.
I plan on committing the changes on Friday, but I wanted to provide the patch
in case someone wanted to review the code.
Thanks,
Rich
> OMSourcedElement/OMDataSource Upgrade
> -------------------------------------
>
> Key: WSCOMMONS-232
> URL: https://issues.apache.org/jira/browse/WSCOMMONS-232
> Project: WS-Commons
> Issue Type: Improvement
> Components: AXIOM
> Reporter: Rich Scheuerle
> Assignee: Rich Scheuerle
> Attachments: patch.txt
>
>
> Summary:
> Upgrade the OMSourcedElement creation and usage.
> The changes will not affect the code or semantics of existing users of
> OMSourcedElement.
> Background:
> An OMSourcedElement is useful for adding a java object into an OM tree.
> This is accomplished by creating an OMSourceElement that is backed by a
> user-provided
> OMDataSource which wraps a java object.
> Overview:
> 1) Allow users to create and inspect OMSourcedElement objects using public
> interfaces.
> 2) Allow users to access the underlying OMDataSource of an OMSourcedElement
> 3) Allow users to replace an OMDataSource.
> 4) Provide example OMDataSource implementations to wrap byte[] and
> InputStream objects.
> 5) Provide an upgraded OMDataSourceExt interface that allows the
> OMSoucedElement to query
> additional information about the OMDataSource. See scenario 5 below for
> details.
> 6) Validation tests and upgraded javadocs
> ------------------------------------------------------------------
> Problem Scenario 1:
> Axiom does not have a public interface for OMSourcedElement.
> Solution:
> Addition of org.apache.axiom.om.OMSourcedElement
> An OMSourcedElement is created with OMFactory.createOMElement(OMDataSource...)
> -------------------------------------------------------------------
> Problem Scenario 2 & 3:
> Users may want to inspect and change the OMDataSource on an OMSourcedElement.
> For example, a consumer may wish to replace a OMDataSource of a JAXB object
> with
> an OMDataSource of the actual byte[].
> Solution:
> The new OMSourceElement interface exposes methods to getOMDataSource() and
> setOMDataSource(..)
> -------------------------------------------------------------------
> Problem Scenario 4:
> Axiom does not provide any concrete OMDataSource implementations.
> Solution:
> Added org.apache.axiom.om.ds.ByteArrayDataSource
> and org.apache.axiom.om.dsInputStreamDataSource
> These data sources are useful for storing content as a byte[] or an
> InputStream.
> They are also samples for demonstrating how users can construct their own
> OMDataSource implementations.
> --------------------------------------------------------------------
> Problem Scenario 5:
> The existing OMDataSource interface provides only 4 methods.
> One method for reading the data source via an XMLStreamReader.
> Three methods for serializing the data source.
> Unfortunately, these methods do not give the OMSourcedElement adequate
> information about
> the backing object. For example, in the current implementation the
> OMSourcedElement
> expands the tree when the XMLStreamReader is requested. The OMSourcedElement
> assumes
> that reading the OMDataSource is destructive.
> (Similar tree expansion occurs in serialization scenarios).
> Solution:
> A new interface, OMDataSourceExt, is added.
> OMDataSourceExte contains several new methods (close(), isDestructiveRead(),
> isDestructiveWrite(), getXMLBytes(encoding), copy()).
> These new methods improve the communication between the OMSourcedElement and
> the OMDataSource.
> Design Choice:
> I added a new interface, OMDataSourceExt, instead of adding methods to the
> existing interface, OMDataSource.
> Users can continue to use OMDataSource, and are not impacted by these changes.
> New users can choose to use either OMDataSource (with basic behavior) or
> OMDataSourceExt (with enhanced behavior).
> We can continue to upgrade OMDataSourceExt until the next release.
> --------------------------------------------------------------------
> Problem Scenario 6:
> OMSourcedElement is a powerful plugpoint. However its current dependence on
> implementation classes hinders
> customers to exploit it. The lack of concrete OMDataSources also makes it
> difficult
> for customers to understand.
> Solution:
> In addition to adding public interfaces and concrete OMDataSources, I have
> provided a OMSourcedElementTest
> that validates the new code. The test can also be used as a sample
> demonstration of OMSourcedElement.
> In addition, I have upgraded the javadocs for the key classes and interfaces.
> Though more work is needed, this is a
> step in the right direction.
> =================================================================
> Full Disclosure:
> Once these changes are accepted and committed, I have complimentary changes
> in the Axis2 JAX-WS layer.
> Currently, JAX-WS is the major consumer of OMSourcedElement. The initial
> Axis2 JAXWS changes will
> hookup the code to use OMDataSourceExt. I have plans to make follow-on
> changes to clean up the JAX-WS implementation.
> Thanks,
> Rich Scheuerle
--
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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
