RE: cvs commit: xml-axis/java/test/encoding TestArrayListConversi ons.java

[Glen Daniels <gd...@macromedia.com>]

*hands Russell some pepto-bismol*

First off, understand that this metadata stuff (ServiceDesc/OperationDesc/ParameterDesc) is different from the TypeDesc stuff, although both being metadata about Java<->XML relationships, there are a few similarities.  They are independent.

The main point of the Service/Operation/Parameter descriptors is to act as a consistent common model across the engine of what a service is, what it can do, and the various mappings of XML names to things like Java methods and parameters.  I'm in the midst of roughing in the core parts of these classes now, and I expect we'll improve them as we go - please don't consider this stuff a polished work yet, but it moves in a direction we've needed to go in for a long time now.  We've been discussing these concepts for months/years.  I agree a design/arch doc is needed, and I'll commit to doing one but I want to get this phase of development effort done first.

Here's a summary.  A service has a name, a pointer to a Java class, and a set of operations.  An operation has a QName, a java method name, information about the return qname/type, and a set of ordered parameters.  A parameter has a qname, an ordinal position, a mode (IN/OUT/INOUT), and a type.  This should all feel pretty familiar - the idea is that this is an abstract model of what Axis cares about for a service which is not tied tightly to WSDL (though it can be used to generate WSDL or be built from WSDL).

This data comes from one of two places.  Either WSDD/deployment info or introspection.  So if you want to specify that the third parameter for your calculateInterest() method has an XML QName of ["myNS", "term"], you can do that like this in WSDD:
  <service name="loanCalc">
    <operation name="calculateInterest">
      <parameter name="rate" type="xsd:float"/>
      <parameter name="principal" type="xsd:float"/>
      <parameter qname="foo:term" xmlns:foo="myNS" type="xsd:int"/>
    </operation>
  </service>

If there is no info which defines this stuff in the WSDD, we will build it by introspecting.  We only need to do this once now, because once we have built the OperationDescs from the introspection, everything else in the engine uses those directly.

There is actually a third way this information gets into the system - on the client side via the Call APIs.  A Call is really a mechanism which makes an operation happen, and it contains metadata about that operation.  So we're moving towards a world where the Call stores all of this stuff (parameter info, etc) in the OperationDesc inside it, instead of in custom ways.  Also, pointing a Call at a WSDL document should enable generation of OperationDescs from there.

Each request gets an OperationDesc associated with it - for the client, this gets handed down from the Call.  For the server, we figure it out by looking at the XML which came in (and then potentially resolving overloads).

Now, here's an example of where the rubber meets the road.  We're deserializing some XML like this on the server:

<calculateInterest>
  <rate>6.625</rate>
  <principal>10000</principal>
  <ns1:term xmlns:ns1="myNS">48</term>
</calculateInterest>

We've already dispatched to a SOAPService (via URL/SOAPAction/NS), and we look in there for a ServiceDescription.  Then we ask the ServiceDescription for an OperationDesc which matches <calculateInterest> - note that this can be an arbitrary QName match to allow document-style services to dispatch on any XML they want.  Once we've got the OperationDesc, the RPCHandler can do the same trick when encountering each of the parameters <rate>, <principal>, and <ns1:term>.  It asks the OperationDesc for a ParameterDesc which matches the XML, and that ParameterDesc contains the type to apply.  We used to introspect the Java class on every request to figure this stuff out, now we just do a lookup.

Because we get parameters by QName, we are now moving towards being able to support the "missing element == null value" pattern.  If we can unambiguously determine the OperationDesc which we're calling (i.e. don't have overloaded methods), we now have the ability to set up the method call with the passed parameters in the right places and nulls for the missing ones.

Note also that once this info is in the WSDD, we no longer need to generate the Skeleton classes for services built with WSDL2Java -s.

This is just an initial summary, but I hope it conveys some of what's up with these classes and eases your "queasy feeling".  You're right, this model is weaving its way into several parts of the runtime, which is exactly what it was designed to do.  Discussion / questions / etc. most appreciated.

--Glen

> -----Original Message-----
> From: Russell Butek [mailto:butek@us.ibm.com]
> Sent: Friday, March 22, 2002 11:23 AM
> To: axis-dev@xml.apache.org
> Subject: Re: cvs commit: xml-axis/java/test/encoding
> TestArrayListConversions.java
> 
> 
> Hey, Glen!  Where's your design doc for this stuff!?!  I 
> would really like
> to understand what you're doing here!  There seem to be a lot of
> dependencies on this meta-data model within the runtime.  
> That's giving me
> a rather queasy feeling.
> 
> Russell Butek
> butek@us.ibm.com