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