axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tom Jordahl <t...@macromedia.com>
Subject RE: Synching up the docs, samples, and generation...
Date Mon, 03 Dec 2001 15:28:54 GMT

+1

-----Original Message-----
From: Sam Ruby [mailto:rubys@us.ibm.com]
Sent: Monday, December 03, 2001 8:55 AM
To: axis-dev@xml.apache.org
Subject: Synching up the docs, samples, and generation...


Preface:

   The below is not intended to suggest that we should remove any
   functionality or options.  Merely that we focus on a few, easy to
   understand scenarios, and then clearly document alternatives and
   advanced functionality as such.  Nor am I suggesting that we need to
   address everything identified here in this next alpha, or in any
   specific timeframe, I'm just identifying a direction that I think we
   should evolve towards.  Nor am I suggesting that anything is actually
   wrong with the stuff we have, just that it is more focused on where
   we've been than where we would like to go.

   OK, enough rambling

Quick statement of the problem:

   Current samples and documentation are focused on the low-level Call
   interfaces, not as much on WSDLGen.  Many still use the "old style"
   deployment descriptors.

   WSDLGen seems to default to (or only support) deployment of services by
   target namespace.

   User's guide seems to focus a lot on low level interfaces and handlers,
   and less on higher level concepts.  Topics seem added in chronological
   order of development, not necessarily in the order that new users need
   to be exposed to this information.

   Next to no mention of attachments or message based processing.

General statement of preferred direction (and proposed outline of
restructured users guide):

   Scenario 1 (a.k.a. bottom up):

     Create a simple Java file that implements a web service
     Annotate it with deployment information (WSDD)
     Deploy the service
     Generate the client stub (Java2WSDL + WSDL2Java)
     Use the stub in a client application

   Scenario 2 (a.k.a. top down)

     Start with a WSDL
     Generate skeleton and stub
     Complete the implementation
     Deploy the service
     Use the stub in a client information

   Additional topics:
     Attachments
     Message based processing
     XML<->Java mapping
     Identifying services by SOAPAction or body namespace
     Lower level JAX RPC apis

Specific suggestions:

   Move architecture overview and descriptions of creating handlers to
   system integrators guide
     Rationale: while handlers are general purpose, the primary anticipated
     usage is for concepts like authentication, authorization, transaction
     context, and the like.

   Move reference material to a separate document
     Rationalle: Make it easier to find and the users guide easier to
     digest

   Standardize on URL based deployment as the primary means.  This means
   making it work from WSDL4J, and converting the samples and examples.
     Note: In examples which do not follow this pattern, highlight the
     difference.

   Continue the migration to WSDD

   Add examples and documentation on attachments and message based
   processing

- Sam Ruby

Mime
View raw message