Proposed Message API change -- preview

[James M Snell <ja...@us.ibm.com>]

Ok,

Here is a snapshot of the pluggable message api code that I've been 
working on.  You only need pay attention to the 
org.apache.axis.encoding.*, org.apache.axis.message.* , 
org.apache.axis.soap.*  and org.apache.axis.utils.* packages.  This is an 
experimental codebase I work off of to play around with different ideas, 
so you'll notice a bunch of other wierd stuff in there.  Ignore all that. 
Stick to the packages above to see the message api stuff. 

Basically, what I've done is this:

1. I removed all trace of SOAP from the org.apache.axis.message.* and 
org.apache.axis.encoding.* packages.  These are now completely generic and 
do not even assume that the message is XML-based.  Some of the classes are 
renamed, and some classes (such as DeserializationContext and 
Deserializer) have completely changed. 

2. I introduced the idea of an EncodingStyle.  This allows us to use 
different type mappings for each encoding style.  I haven't tested it 
completely, but it seems to work pretty well. 

4. Changed the Message API completely.  Now we have Message as an 
Interface and a new construct called a Part (replaces MessageElement). 
There is also a new MessageFactory class. The MessageFactory is the key to 
the message protocol pluggability scheme I'll explain in just a moment.

5. Moved all SOAP related stuff to org.apache.axis.soap.*

    a. Limited support for both SOAP 1.1 and SOAP 1.2
    b. Deserializes all SOAP primitives based on the XML Schema 2001 
specification (simple support for all XML Schema data types supported)
    c. Deserializes simple SOAP arrays
    d. Support for Headers, Independent elements, mustUnderstand and 
actors
    e. Uses the recorded-sax scheme
     f.  I need somebody else to verify, but I'm getting better results on 
deserialization with this new stuff than with the current stuff.  I made 
quite a few changes
        to the way the record/replay works, so take a look.
    g. Still testing, but I've got full support for encoding styles

6. Changed some stuff around in the org.apache.axis.utils.* package 
including a new NSStack class and a new org.apache.axis.utils.xml.* 
package. 

7. Serialization is not yet implemented.  I'm still working on this part. 
Give me a couple more days to get it done.  All you can do currently is 
read messages and manipulate them in memory. 
 
Pluggable protocol scheme.

It's pretty simple.  Basically, the type of message being passed into Axis 
needs to be determined before it's actually passed in.  This can be done 
in the servlet.  Once determined, an instance of the appropriate 
MessageFactory implementation would be created (SOAPMessageFactory for 
instance).  Use the factory to create the Message.  For example:

       Message message = 
SOAPMessageFactory.newMessage(httpRequest.getInputStream(), 
encodingStyleRegistry);

Now we can pass the message into Axis and process it using the new Message 
API interface.

Want to use an Http-Post message?  Then, use the as-yet-non-existent 
HttpPostMessageFactory:

      Message message = 
HttpPostMessageFactory.newMessage(httpRequest.getInputStream(), 
encodingStyleRegistry);

The one thing to be aware of is the fact that deserializers registered 
with the encoding style registry are going to be message protocol 
specific.  i.e. the SOAP implementation will need to use SOAP specific 
SAXDeserializers in order to work.  The HttpPost implementation will need 
to use HttpPost specific deserializers, etc.  I don't see any way to get 
around this since the deserializers are the work horses that do the actual 
message to native translation. 

Y'all please take a good look at this and let me know what you think. It's 
nowhere near perfect yet but I think I'm heading in the right direction. 

I've noticed several advantages with this code than over the current 
stuff:

1. It appears to be a bit faster, but I have yet to completely verify that
2. It's pluggable (allows us to use more protocols than just SOAP)
3. It's more organized.  (Sorry, I'm kinda anal about this one, I like 
things really organized ;-)   )
4. The Message API doesn't assume that all messages are XML based
5. Supports encodingStyles which allows us to have different type mappings 
for different encoding styles within a single message

Anyway, please review and comment.  If I don't hear anything by Wednesday 
or Thursday, I'm assuming consent and will continue to move forward.  Be 
warned, the next time you see this may be in a CVS commit !!!    I believe 
that it was Sam who has said "Commit first, appologize later".... well, 
I'm giving y'all a chance to scream about this now, so please do if you 
have any comments!  :-) .

Keep in mind that it's not done, it ain't perfect, and it ain't 
necessarily pretty.

I am not intending this to be a release 1 thing, btw (which is why I'm 
using an experimental psuedo-Axis codebase to write it and not the actual 
CVS code). 

(p.s. remember, just focus on the org.apache.axis.encoding.*, 
org.apache.axis.message.* , org.apache.axis.soap.* and 
org.apache.axis.utils.* packages.... the rest is my 
playing-around-with-random-ideas code)

(p.p.s regarding Messages with attachments... one could easily imagine 
that the SOAPMessage implementation could be made aware of 
SOAPAttachmentParts..... it wouldn't take a lot to implement support for 
it.  All of the work would be done in the SOAPDeserializationContext 
class.  More details on this later)



- James M Snell/Fresno/IBM
    Web services architecture and strategy
    Internet Emerging Technologies, IBM
    544.9035 TIE line
    559.587.1233 Office
    919.486.0077 Voice Mail
    jasnell@us.ibm.com
=================================================================
Have I not commanded you?  Be strong and courageous.  Do not be terrified, 

do not be discouraged, for the Lord your God will be with you wherever you 
go.  
- Joshua 1:9

Re: Proposed Message API change -- preview

[Sanjiva Weerawarana <sa...@watson.ibm.com>]

> Anyway, please review and comment.  If I don't hear anything by Wednesday
> or Thursday, I'm assuming consent and will continue to move forward.  Be
> warned, the next time you see this may be in a CVS commit !!!    I believe
> that it was Sam who has said "Commit first, appologize later".... well,
> I'm giving y'all a chance to scream about this now, so please do if you
> have any comments!  :-) .
>
> Keep in mind that it's not done, it ain't perfect, and it ain't
> necessarily pretty.

It would be ludicrous in my mind to consider this kind of a change for
v1. If its post v1, it IMO should not be committed now.

Sanjiva.