RE: [axis2] "simple" axis data binding architecture and approach forrpc support

[Dinesh Shahane <ds...@tibco.com>]

Sanjiva,

I really liked this idea to have a common message form, are you thinking
of making this form public for complex data binding modules? 

I have a question regarding the intermediate message conventions
proposed in this architecture. Would the elements created to hold
message parts using the algorithm you mentioned include the parts bound
to soap headers and attachments too? Somehow it wasn't very clear to me
if the proposal just includes the body parts.

If yes, is it possible to have additional conventions for things like 

- ordering of the parts
- unbound parts
- headers not bound to abstract messages
- parts referenced using swaRefs

we can probably think of few more if applicable.

This way the intermediate form would not loose any information found in
the SOAP or SwA message and can be open for future expansions in the
databinding modules. 

Thanks,
Dinesh

 

-----Original Message-----
From: Sanjiva Weerawarana [mailto:sanjiva@opensource.lk] 
Sent: Wednesday, October 12, 2005 12:04 AM
To: axis-dev@ws.apache.org
Subject: [axis2] "simple" axis data binding architecture and approach
forrpc support

Hi Guys,

I volunteered to write up the current design being implemented for the
"simple" Axis data binding and for supporting RPC. This design is a bit
different from the Axis1 design of data binding (I think) .. hopefully
its an improvement and not a regression!


Axis Data Binding
-----------------

The objective is to provide a tool that supports a minimal subset of XML
Schema and generates Java data bindings for them. The definition of
where "minimal" ends is currently under debate of course; we have to all
come to some consensus on where to draw that line.
	
The tool augments the WSDL2Code tool by becoming a pluggable data binder
to generate data bound parameters instead of OMElement parameters.
	
Note that this step does not extend the support for RPC style WSDLs yet;
WSDL2Code only supports doc/lit stuff so far.

To avoid generating lots of extra classes, the current plan is to put
into each generated ADB class a static read() and a non-static write()
method. Each generated class implements the following interface so that
we can detect when these will be present:

==========
public interface ADBBean {
    /**
     * This method is used to serialize an ADBBean: get the pull parser
     * and pull the XML pull events to represent the bean.
     * 
     * @param adbBeanQName
     *            the name of the element to be generated for this
     *            ADBBean
     * @return a pull parser for this ADBBean.
     */
    public XMLStreamReader getPullParser(QName adbBeanQName);

    /**
     * There will be a self factory in every generated data bound 
     * class XXX:
     * public static XXX read (XMLStreamReader);
     */
}
==========

	So, if we generate an ADB binding for a Person type say, we'd
get
something like:

==========
public class Person implements ADBBean {
    /* normal bean stuff for the properties */

    public XMLStreamReader getPullParser();

    public static Person read (XMLStreamReader);
}
==========

	This leads to a kind of cool unit testing environment:

==========
Person p = new Person();
p.set* ();
Person pcopy = Person.read (p.getPullParser(new QName ("myPerson")));
assert pcopy.equals (p);
==========

	To support arbitrary beans, we can also write a reflective tool
that
allows us to get to do these with arbitrary beans:

==========
SomeBean sb = new SomeBean ();
SomeBean sbcopy = (SomeBean) ADBUtils.readBean
    (ADBUtils.getPullParser(new QName("myBean"), sb), SomeBean.class);
==========

Once this code is plugged in to the tool, we will be able to data bind
doc/lit WSDLs and generate methods which have some JavaBean as the
argument instead of an OMElement.


Supporting RPC Style WSDLs
--------------------------

The objective here is to support the following use-cases:
- read a WSDL which has a rpc/lit SOAP binding and generate a stub
- read a WSDL which has a rpc/encoded SOAP binding with SOAP-Enc
encoding style and generate a stub [this may have restrictions]
- read a WSDL which has up to a portType and generate a skeleton with or
without unwrapping (as appropriate - more later)

Axis2's guts depends on WSDL2 concepts of interface -> operation ->
message. (If you're not familiar with WSDL2 you may need to understand
that before being able to fully grok the rest of this message.) So, an
operation has a bunch of message references, where each message
reference has purely one element. 

Given a WSDL 1.1 document, if style=rpc, then there could be 0..n
<wsdl11:part> children in the <wsdl11:message> element. In that case, in
order to read it into the WSDL2 concepts, we need to generate what
amounts to the method call element that will appear in the SOAP body and
represent that as the element corresponding to the message. That's
fairly straightforward:
	- local name of element: /portType/operation/@name
	- namespace name of element: /binding/operation/(input|
output)/soap:body/@namespace
	- content: a <sequence> who's contents are elements
corresponding to
each <part> of the message where the name of that child element is the
name of the part (if the part is defined by @type) or the name of the
part's element (if the part is defined by @element)

With the above algorithm, we can take any rpc/lit style WSDL and
generate the corresponding WSDL2 style stuff.

For rpc/enc style WSDLs we are only looking to support them when the
encoding style is SOAP-Enc. Now I'm going to assert a controversial
position about rpc/enc style WSDL documents which use SOAP-Enc encoding
style: they are really rpc/lit WSDLs for many cases (except for those
that use soapenc:Array stuff - I propose *not* to handle soapenc:Array
in the simple ADB world). The reason rpc/enc WSDLs are really rpc/lit
WSDLs is because in the the SOAP encoding style defines an abstract data
model but does not define an interoperable means for serializing that
into XML.

[Supporting soapenc:Array can be done with some XSD games too but IMO
its not worth it because we're talking about old legacy .. not even WS-I
blessed.]

So, if the WSDL is rpc/enc with encType=soapenc, we can now proceed as
if it were a rpc/lit WSDL and execute the previous algorithm to create a
WSDL2 style world. Ah yes we should check and throw an exception if the
schemas have soapenc:Array stuff as that's not supported.

Now what we've done is collapse all three use-cases to one: a WSDL2
style world of goodness. (As you can tell I'm getting tired of this long
email ..)

Now we want to generate a stub and a skeleton from a WSDL2 style
description and allow the user the option to "unwrap" the element and
look at each child element as a separate param and also allow the option
of data binding the children or not. So we have two separate options:
	- unwrap=yes/no
	- databind=yes/no

If we unwrap we take each child of the element and map into a separate
parameter. The contents of the generated stub methods or the generate
message receiver have to take this unwrapping into consideration and
generate the wrapping element.

If we data bind we take each parameter and data bind.

Details left to the reader as an exercise .. its actually quite
straightforward conceptually .. a bit of pain at the code level of
course :).

Game, set and match?

Sanjiva.