Architecture guide : comments

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

Hi Glyn!  I think this is a good start on expanding the text in the integration
guide, but could use a little editing.  Some comments:

I'd prefer to see the "meta" discussion (things like "The relationship between
these subsystems needs to be documented and somewhat cleaned up...") elsewhere.
These are great topics for emails, but shouldn't, IMHO, go in the actual
document.  Ditto for the questions.  In various places you say "we need to
decide...", which I think detracts from the purpose of an architecture
document.  An "open issues" section would be fine at the end, but the main meat
of the document should be explanations of what we have decided and how the
system actually works.  It should read crisply and clearly, without venturing
off into speculation and questioning much at all.

Message Path on the Server - I'd pull "for instance when there is a response
message".  The path is the same whether or not there is an actual response
generated (i.e. the response handlers still get called, since they might do
things like stop timers, clean up resources, etc).  Ditto for the client.

We should make it clear that the connection between the "pivot" in the client
side diagram and the "Target Service" is in fact usually sending SOAP across a
"wire" of some kind.  Show the little cloud and a SOAP message traversing it,
etc.  Also, I'd call the pivot in this diagram the "sender" to follow along
with the text.

"Parsing / encoding" and "Message model" are probably other good subsystems to
note.  I'd call the "dispatcher" subsystem something like "processing flow",
since it seems like more than just simple dispatching.

The fault model consists of more than just the onFault() method.  There is also
the "faultFlow" stuff in WSDD which causes the creation of a
"FaultableHandler", which serves to wrap another Handler, catching exceptions
and potentially invoke()ing other Handlers to deal with the Fault.   See
FaultableHandler.java and WSDDFaultFlow.java for more.

OK, bedtime for me, more later.  This is a great start, let's keep the momentum
going!

--Glen