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