[Smartfrog-checkins] core/extras/alpine/doc/jaxrpc abstract.tex,1.9,1.10 acknowledgements.tex,1.1,1.2 alpine.tex,1.12,1.13 bibliography.bib,1.14,1.15 implications.tex,1.5,1.6 introduction.tex,1.13,1.14 jaxrpc.tex,1.16,1.17 objections.tex,1.16,1.17 wsdl.tex,1.10,1.11

[Edmund S. <ic...@us...>]

Update of /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18438

Modified Files:
	abstract.tex acknowledgements.tex alpine.tex bibliography.bib 
	implications.tex introduction.tex jaxrpc.tex objections.tex 
	wsdl.tex 
Log Message:
major review for forthcoming IEEE submission


Index: introduction.tex
===================================================================
RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/introduction.tex,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -d -r1.13 -r1.14
*** introduction.tex	25 Jan 2005 22:54:48 -0000	1.13
--- introduction.tex	28 Jan 2005 20:32:43 -0000	1.14
***************
*** 2,33 ****
  \label{introduction}
  
! In any discussion of SOAP-based technologies, it is important to
! remember the core reasons for adopting SOAP originally. We
! characterise them as follows:
  
  \begin{enumerate}
! \item simplicity: It is intended to be easy to work with.
! 
! \item interoperability: It is more interoperable than binary
! predecessors
  
! \item XML-centric: Built on XML, and intended to integrate with
! XML-based technologies.
  
! \item extensibility: The envelope/header/body structure
  allows extra data to be attached to a request, potentially without
  breaking existing systems.
  
! \item self-describing: Messages can contain type definitions
  alongside data, and provide human readable names.
  
! \item flexibility: Participants can handle variable amounts
  of incoming data.
  
! \item long-haul: It is designed to work through firewalls,
  over HTTP.
  
! \item loosely-coupled: Participants are not expected to share
  implementation code.
  \end{enumerate}
  
--- 2,34 ----
  \label{introduction}
  
! In beginning any discussion of SOAP-based technologies, it is 
! valuable to review the core features which made adopting SOAP
! attractive initially. We briefly characterise these as follows:
  
  \begin{enumerate}
! \item Simplicity: It is intended to be easy to work with.
  
! \item Interoperability: It is more interoperable than binary
! predecessors.
  
! \item Extensibility: The envelope/header/body structure
  allows extra data to be attached to a request, potentially without
  breaking existing systems.
  
! \item Self-describing: Messages can contain type definitions
  alongside data, and provide human readable names.
  
! \item Flexibility: Participants can handle variable amounts
  of incoming data.
  
! \item Long-haul: It is designed to work through firewalls,
  over HTTP.
  
! \item Loosely-coupled: Participants are not expected to share
  implementation code.
+ 
+ \item XML-centric: Built on XML and intended to integrate with
+ XML-based technologies.
+ 
  \end{enumerate}
  
***************
*** 48,52 ****
  are JAX-RPC\footnote{Java API for XML-based RPC}
  \cite{spec:JAX-RPC-11} and JAXM\footnote{Java API for XML Messaging}
! \cite{spec:JAX-M-11}. We look at each of these in turn.
  
  \subsubsection{JAXM}
--- 49,53 ----
  are JAX-RPC\footnote{Java API for XML-based RPC}
  \cite{spec:JAX-RPC-11} and JAXM\footnote{Java API for XML Messaging}
! \cite{spec:JAX-M-11}. We review each of these in turn.
  
  \subsubsection{JAXM}
***************
*** 68,80 ****
  
  JAXM does not provide significant transport support: the primary
! method of receiving JAXM messages is to implement and deploy an HTTP
  servlet.  The sole method of sending a message is to ask a
  {\tt SOAPConnectionFactory} for a {\tt SOAPConnection} instance, and
  then make a blocking call of the endpoint.
  
! JAXM is an orphan specification. If ebXML had taken off, perhaps it
! would be more popular, and message-centric SOAP development in Java
! commonplace. Instead JAX-RPC is touted as the recommended way to work
! with SOAP in Java. 
  
  \subsubsection{JAX-RPC}
--- 69,82 ----
  
  JAXM does not provide significant transport support: the primary
! method of receiving JAXM messages is to implement and deploy a HTTP
  servlet.  The sole method of sending a message is to ask a
  {\tt SOAPConnectionFactory} for a {\tt SOAPConnection} instance, and
  then make a blocking call of the endpoint.
  
! JAXM has become an orphan specification. Had ebXML been more
! successful, it is conceivable that JAXM might have proven more
! popular, and made message-centric SOAP development in Java
! commonplace. As it is, JAX-RPC is touted as the recommended way to
! work with SOAP in Java.
  
  \subsubsection{JAX-RPC}
***************
*** 82,87 ****
  
  In JAX-RPC\footnote{The current edition of the JAX-RPC specification
! is version 1.1, and this is the version we discuss here. JAX-RPC2.0
! is discussed in section \ref{implications:future}}, all the details of
  how a message was encoded are hidden, and the developer works with
  Java objects created automatically from the XML data using a
--- 84,89 ----
  
  In JAX-RPC\footnote{The current edition of the JAX-RPC specification
! is version 1.1, and this is the version we discuss here. JAX-RPC 2.0
! is discussed in section \ref{implications:future}.}, all the details of
  how a message was encoded are hidden, and the developer works with
  Java objects created automatically from the XML data using a
***************
*** 95,113 ****
  Client side proxy classes can be generated from the WSDL files, proxy
  classes which again provide a method for every operation the service
! supports. In Java-Java communications, the result is that methods
! called on the proxy class result in the passing of the method
! parameters to remote methods on an instance of the implementation
! class, a behaviour that superficially resembles Java RMI
! \cite{paper:RMI}. We will return to this in section
  \ref{objections:soap-not-rmi}.
  
  One good architectural feature of JAX-RPC is the \emph{handler chain},
! which consists of an ordered sequence of classes which are configured to
! manage requests and responses. Using the handler chain, it is possible
! to add support for new SOAP headers to existing services, or to apply
! extra diagnostics. The dispatch of operations to Java methods,
! Enterprise Java Bean methods or other destinations is actually
! implemented by specific handlers, making the handler chain the
! foundation for the rest of the system.
  
  JAX-RPC is widely implemented, both by open source projects (for
--- 97,115 ----
  Client side proxy classes can be generated from the WSDL files, proxy
  classes which again provide a method for every operation the service
! supports. In communications between systems running on the Java
! platform, the result is that methods called on the proxy class result
! in the passing of the method parameters to remote methods on an
! instance of the implementation class, a behaviour that superficially
! resembles Java RMI \cite{paper:RMI}. We will return to this in section
  \ref{objections:soap-not-rmi}.
  
  One good architectural feature of JAX-RPC is the \emph{handler chain},
! which consists of an ordered sequence of classes which are configured
! to manage requests and responses. Using the handler chain, it is
! possible to add support for new SOAP headers to existing services, or
! to apply extra diagnostics, in a relatively transparent fashion. The
! dispatch of operations to Java methods, Enterprise Java Bean methods
! or other destinations is generally implemented by specific handlers,
! making the handler chain the foundation for the rest of the system.
  
  JAX-RPC is widely implemented, both by open source projects (for
***************
*** 119,123 ****
  examples in the vendors' documentation.
  
! The bias is such that, for Java development, JAX-RPC \emph{is} SOAP. 
  
  \subsection{The Hard Lessons of Service Implementation}
--- 121,126 ----
  examples in the vendors' documentation.
  
! The bias is such that, for Java development, it is widely seen that
! JAX-RPC \emph{is} SOAP.
  
  \subsection{The Hard Lessons of Service Implementation}
***************
*** 132,143 ****
  fabric.
  
! This service was defined in a ``pure way'', by writing the XSD and
! WSDL files first. This approach is believed to aid in creating a
! platform-independent system, and represents current best
! practise. However, the XSD file for the service messages is
  approximately 2000 lines, including all the comments and annotations
  needed to make it comprehensible. That it takes so many lines to
  describe a relatively simple service is clearly one reason why this
! approach, despite its superiority of output, is so unpopular.
  
  Many problems were encountered turning this WSDL specification into
--- 135,146 ----
  fabric.
  
! The development of this service was performed in a ``pure way'', by
! creating the XSD and WSDL files first. This approach is believed to
! aid in creating a platform-independent system, and represents current
! best practise. However, the XSD file for the service messages is
  approximately 2000 lines, including all the comments and annotations
  needed to make it comprehensible. That it takes so many lines to
  describe a relatively simple service is clearly one reason why this
! approach, despite its alleged superiority of output, is so unpopular.
  
  Many problems were encountered turning this WSDL specification into

Index: abstract.tex
===================================================================
RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/abstract.tex,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** abstract.tex	25 Jan 2005 22:54:47 -0000	1.9
--- abstract.tex	28 Jan 2005 20:32:43 -0000	1.10
***************
*** 5,19 ****
  JAX-RPC, which is effectively the standard API for SOAP on the
  Java platform. We claim that JAX-RPC, and indeed any SOAP API that
! relies on a perfect two-way mapping between XML data and native
  language objects is fundamentally flawed. Furthermore, we claim that
  the attempt JAX-RPC makes to extend the remote method invocation 
  metaphor to SOAP services is counterproductive.
  
! We base our reasoning from experience with JAX-RPC
! and SOAP, and in the light of previous distributed computing
! technologies. We argue that JAX-RPC is not capable of delivering on the
! SOAP design goals, but conclude by suggesting an alternate system,
! {\it Alpine}, which is free from many known flaws of existing systems,
! and should prove better able to deliver on the promise of SOAP.
  
  \end{abstract}
--- 5,19 ----
  JAX-RPC, which is effectively the standard API for SOAP on the
  Java platform. We claim that JAX-RPC, and indeed any SOAP API that
! relies upon a perfect two-way mapping between XML data and native
  language objects is fundamentally flawed. Furthermore, we claim that
  the attempt JAX-RPC makes to extend the remote method invocation 
  metaphor to SOAP services is counterproductive.
  
! We base our argument both upon experience with JAX-RPC and SOAP, and
! upon experience of previous distributed computing technologies. We
! argue that JAX-RPC is not capable of delivering on the SOAP design
! goals, but conclude by suggesting an alternate system, {\it Alpine},
! which is free from many known flaws of existing systems, and should
! prove better able to deliver upon the promise of SOAP.
  
  \end{abstract}

Index: implications.tex
===================================================================
RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/implications.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** implications.tex	8 Nov 2004 12:08:57 -0000	1.5
--- implications.tex	28 Jan 2005 20:32:43 -0000	1.6
***************
*** 2,27 ****
  \label{implications}
  
! 
! We believe that there are only two categories of people writing web
! services: those who know XML and want to work with it, and those who
! don't but end up doing so anyway. JAX-RPC provides a sugar coated
  wrapping that encourages developers who are relatively unfamiliar with
  XML to bite. Yet, as anyone who has written a web service of any
  complexity knows, the XML must be faced and understood eventually. In
  practise, the task of creating a real web service is made more
! difficult, not less, by the huge volume of code JAX-RPC introduces.
  
  JAX-RPC only superficially benefits developers who do not want to work
  with XML: by hiding all the details, and giving developers a model of
! remote method calls via serialised Java graphs, JAX-RPC makes it harder
! to write true, interoperable SOAP services. Not only that, but it
! introduces the O/X mapping problem, while retaining an invocation model
! that is inappropriate for long-distance networks and slow
  communications.
  
! We argue that JAX-RPC greatly complicates users' software by introducing a
! complex and fickle serialisation system. The generation of WSDL from Java code,
! which JAX-RPC encourages, makes it very difficult to maintain version
! consistency of an interfaces, and creates significant interoperability problems.
  
  On top of all of this, for users who do want to work with the XML
--- 2,28 ----
  \label{implications}
  
! We believe that only two categories of web service developer exist:
! those who are comfortable with XML and want to work with it, and those
! who aren't but end up doing so anyway. JAX-RPC provides a sugar coated
  wrapping that encourages developers who are relatively unfamiliar with
  XML to bite. Yet, as anyone who has written a web service of any
  complexity knows, the XML must be faced and understood eventually. In
  practise, the task of creating a real web service is made more
! difficult, not less, by the huge volume of code JAX-RPC introduces
! into a project.
  
  JAX-RPC only superficially benefits developers who do not want to work
  with XML: by hiding all the details, and giving developers a model of
! remote method calls via serialised Java graphs, JAX-RPC makes it
! harder to write true, interoperable SOAP services. Not only that, but
! it introduces the O/X mapping problem, while retaining an invocation
! model that is inappropriate for long-distance networks and slow
  communications.
  
! We argue that JAX-RPC greatly complicates users' software by
! introducing a complex and fickle serialisation system. The generation
! of WSDL from Java code, which JAX-RPC encourages, makes it very
! difficult to maintain version consistency of an interfaces, and
! creates significant interoperability problems.
  
  On top of all of this, for users who do want to work with the XML
***************
*** 44,63 ****
  
  The forthcoming 2.0 release of the JAX-RPC specification promises to
! correct some of these flaws, but does it correct enough? An alternate
! O/X mapping, JAX-B\footnote{Java Architecture for XML Binding}, is
! used which is independent of the SOAP stack, but still represents a
! compile-time declaration of what XML is to be expected. The 2.0
! release also retains the core metaphor of service invocation as method
! invocation, with the payload of most invocations being Java objects
! that are somehow mapped to XML content. The automated generation of
! WSDL from Java source is retained, despite this problem having been
! shown to be fundamentally flawed.
  
  We understand the rationale for much of this. Working with raw XML is
  hard.  Writing good XML Schema documents is hard. WSDL is exceedingly
! painful to work with. However, we believe that if service developers
! do not write their XSD and WSDL definitions of messages, they will
! never have control of the messages that get sent over the wire, and
  without that control, interoperability and loose coupling will remain
! out of reach.  
  
--- 45,64 ----
  
  The forthcoming 2.0 release of the JAX-RPC specification promises to
! correct some of these flaws, it is unclear whether it corrects
! sufficiently many of them. An alternate O/X mapping, JAX-B, the Java
! Architecture for XML Binding, is introduced which is a compile-time
! declaration of what XML is to be expected, but is independent of the
! SOAP stack. The 2.0 release also retains the core metaphor of service
! calls as method invocation, with the payload of most invocations
! being Java objects that are somehow mapped to XML content. The
! automated generation of WSDL from Java source is retained, despite
! this problem having been shown to be fundamentally flawed.
  
  We understand the rationale for much of this. Working with raw XML is
  hard.  Writing good XML Schema documents is hard. WSDL is exceedingly
! painful to work with. However, we believe that if developers do not
! create the XSD and WSDL definitions of their service, they will never
! have control of the messages that get sent over the wire, and that
  without that control, interoperability and loose coupling will remain
! out of reach.
  

Index: acknowledgements.tex
===================================================================
RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/acknowledgements.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** acknowledgements.tex	25 Jan 2005 22:54:47 -0000	1.1
--- acknowledgements.tex	28 Jan 2005 20:32:43 -0000	1.2
***************
*** 1,7 ****
  \section{Acknowledgements}
  The authors would like to thank Tim Ewald and Ted Neward for their
! valuable feedback and corrections. One implementation of the CDDLM 
! deployment service was
! created for the OGSAConfig project, which is funded by a grant from
! the Joint Information Systems Committee (JISC). The other was produced
! as part of the HP Laboratories SmartFrog project. 
--- 1,7 ----
  \section{Acknowledgements}
  The authors would like to thank Tim Ewald and Ted Neward for their
! valuable feedback and corrections. One implementation of the CDDLM
! deployment service was created for the OGSAConfig project, which is
! funded by a grant from the Joint Information Systems Committee
! (JISC). The other was produced as part of the HP Laboratories
! SmartFrog project.

Index: wsdl.tex
===================================================================
RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/wsdl.tex,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** wsdl.tex	8 Nov 2004 12:08:57 -0000	1.10
--- wsdl.tex	28 Jan 2005 20:32:43 -0000	1.11
***************
*** 2,6 ****
  \label{objections:wsdl-gen}
  
! The role of an Interface Definition Language (IDL) has always been
  twofold:
  
--- 2,6 ----
  \label{objections:wsdl-gen}
  
! The role of an interface definition language (IDL) has always been
  twofold:
  
***************
*** 13,17 ****
  language needs an explicit notion of interfaces. The interface is
  inherently implementation independent, and can be frozen or carefully
! managed with respects to versioning.
  
  \item Secondly, the act of writing an IDL description inherently
--- 13,17 ----
  language needs an explicit notion of interfaces. The interface is
  inherently implementation independent, and can be frozen or carefully
! managed with respect to versioning.
  
  \item Secondly, the act of writing an IDL description inherently
***************
*** 19,34 ****
  datatypes and operations available in the restricted language of the
  IDL.  This can effectively guarantee portability, and is a significant
! improvement over similar definitions in the implementation languages,
  which invariably contain constructs which are not portable. As such
  constructs are excluded from the interface language, a portability
! issue is the exception, rather than the rule.
  \end{enumerate}
  
  IDLs have many advantages for creating interoperable systems, yet the
  generally accepted practise for working with JAX-RPC discards all
! these notions. Instead of generating implementation classes from the
! WSDL, the WSDL is usually generated from the implementation classes,
! using Java's Reflection API. We shall term this process
! \emph{WSDL-last development}.
  
  This has the following consequences.
--- 19,34 ----
  datatypes and operations available in the restricted language of the
  IDL.  This can effectively guarantee portability, and is a significant
! improvement over similar definitions in implementation languages,
  which invariably contain constructs which are not portable. As such
  constructs are excluded from the interface language, a portability
! issue is the exception, rather than being commonplace.
  \end{enumerate}
  
  IDLs have many advantages for creating interoperable systems, yet the
  generally accepted practise for working with JAX-RPC discards all
! these notions. Instead of generating implementation classes from WSDL,
! the WSDL description is usually generated from the implementation
! classes using tools leveraging Java's Reflection API. We shall term
! this process \emph{WSDL-last development}.
  
  This has the following consequences.
***************
*** 46,63 ****
  
  Some aspects of the service are not extracted from the raw signatures
! of the classes and methods. For example, if a method chooses to extract
! attachments from the message, that information can be hidden in the contents
! of the message, instead of its signature. The generated WSDL will thus
! omit any information about the attachment needs of the service.
  
  \item
  
! There is no warning of portability issues before integration time. 
! When defining a service using an IDL, the author knows
! when there are problems, as the IDL will not compile. Yet with WSDL-last
! development, everything seems to work, until the service goes live and
! a customer using a different language attempts to import the WSDL and
! invoke the service.
! 
      
  \end{itemize}
--- 46,63 ----
  
  Some aspects of the service are not extracted from the raw signatures
! of the classes and methods. For example, if a method chooses to
! extract attachments from a message, that information can be hidden in
! the contents of the message, instead of in the signature of the
! call. The generated WSDL will hence omit any information about the
! attachment needs of the service.
  
  \item
  
! There is no warning of portability issues before integration time.
! When defining a service using an IDL, the author typically knows when
! there are problems as the IDL will not compile. Yet with WSDL-last
! development, everything may well seem to work until the service goes
! live and a customer using a different language attempts to import the
! WSDL and invoke the service.
      
  \end{itemize}
***************
*** 76,90 ****
  in the IDL-era of distributed systems programming.
  
! It is worth noting that REST systems \cite{fielding:rest} tend not to
! use WSDL, even though it is theoretically possible. Instead they
! resort to their XML type language of choice and quality human-readable
! documentation. This would appear to be sub-optimal, yet REST is
! growing in popularity, despite (or perhaps because of) the lack of
! WSDL integration.
  
! Returning to the desiderata for SOAP, a WSDL-last process sacrifice
! interoperability for ease of service development. Perhaps WSDL is not
! the appropriate language for describing SOAP services (we are
! certainly not enthused about it), yet the sole solution being
  advocated is not a major undertaking to fix WSDL's core flaws, it is
  to continue to encourage developers to hand over to their SOAP stacks
--- 76,90 ----
  in the IDL-era of distributed systems programming.
  
! We in passing that that REST systems \cite{fielding:rest} tend not to
! make use of WSDL, even though it is theoretically possible. Instead
! they resort to their XML type language of choice and quality
! human-readable documentation. This would appear to be sub-optimal, yet
! REST is growing in popularity, despite (or perhaps because of) the
! lack of WSDL integration.
  
! Returning to the desiderata for SOAP, following a WSDL-last process
! sacrifices interoperability for ease of service development. Perhaps
! WSDL is not the appropriate language for describing SOAP services (we
! are certainly not enthused about it), yet the sole solution being
  advocated is not a major undertaking to fix WSDL's core flaws, it is
  to continue to encourage developers to hand over to their SOAP stacks
***************
*** 96,99 ****
  development more aggressively than any previous IDL ever did. We do
  observe that once the type declarations of a service have been moved
! into their own document, WSDL becomes much more manageable. This is a
! pattern of service definition which we strongly encourage.
--- 96,99 ----
  development more aggressively than any previous IDL ever did. We do
  observe that once the type declarations of a service have been moved
! into their own document, WSDL becomes much more manageable and this is
! a pattern of service definition which we strongly encourage.

Index: bibliography.bib
===================================================================
RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/bibliography.bib,v
retrieving revision 1.14
retrieving revision 1.15
diff -C2 -d -r1.14 -r1.15
*** bibliography.bib	9 Nov 2004 15:45:12 -0000	1.14
--- bibliography.bib	28 Jan 2005 20:32:43 -0000	1.15
***************
*** 216,220 ****
      author="Steve Loughran",
      title="{A SOAP API for Deployment}",
!     url="http://forge.gridforum.org/projects/cddlm-wg/document/Deployment_API_-_Draft_0/en/1",
      year="2004"
      }     
--- 216,220 ----
      author="Steve Loughran",
      title="{A SOAP API for Deployment}",
!     url="http://forge.gridforum.org/projects/cddlm-wg/document/Deployment\_API\_-\_Draft\_0/en/1",
      year="2004"
      }     
***************
*** 239,243 ****
      year=2003,
      howpublished="online presentation",
!     url="http://research.microsoft.com/Users/luca/Slides/2003-11-13%20Transitions%20in%20Programming%20Models%20(Lisbon).pdf",
      annote="New University of Lisbon, November 13, 2003."    
      }
--- 239,243 ----
      year=2003,
      howpublished="online presentation",
!     url="http://research.microsoft.com/Users/luca/Slides/2003-11-13\%20Transitions\%20in\%20Programming\%20Models\%20(Lisbon).pdf",
      annote="New University of Lisbon, November 13, 2003."    
      }

Index: objections.tex
===================================================================
RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/objections.tex,v
retrieving revision 1.16
retrieving revision 1.17
diff -C2 -d -r1.16 -r1.17
*** objections.tex	8 Nov 2004 12:08:57 -0000	1.16
--- objections.tex	28 Jan 2005 20:32:43 -0000	1.17
***************
*** 21,41 ****
  \emph{``Object-relational mapping is the Vietnam of Computer Science''}
  - Ted Neward, 2004.
! %{\small \tt http://www.neward.net/ted/weblog/index.jsp?date=20041003#1096871640048}
! }. 
! Over a decade has been spent trying to map between records in relational
! databases and language-level objects, and there is still no sign of an ideal
! solution. There is significantly less experience in mapping between XML and
! objects, and rather than drawing on the experiences of the many failed attempts
! at O/R mapping, O/X mapping technologies appear destined to share a similar
! evolution.
  
! At first glance, O/X mapping appears simple: create a Java object for
! each XML element, building a DAG\footnote{directed, acyclic graph}
! when serialising to RPC/encoded SOAP or a tree with document/literal
! messages. Read or write between attributes and class fields, bind to
! children and the conversion is complete. If only it were so
! straightforward. There is a fundamental difference between the type
! systems of XML (especially that of XML Schema) and that of Java, which
! makes any mapping both complex and brittle.
  
  \subsubsection{Binding XML Elements to Java Classes}
--- 21,41 ----
  \emph{``Object-relational mapping is the Vietnam of Computer Science''}
  - Ted Neward, 2004.
! %{\small \tt http://www.neward.net/ted/weblog/index.jsp?date=20041003#1096871640048} 
! }.  Over a decade has been spent trying create robust mappings between
! records in relational databases and language-level objects, and there
! is still no sign of an ideal solution. There is significantly less
! experience in mapping between XML and objects, and rather than drawing
! on the experiences of the many failed attempts at O/R mapping, O/X
! mapping technologies appear destined to share a similar evolution.
  
! At first glance, the O/X mapping problem facing JAX-RPC appears
! simple: create a Java object for each XML element, building a
! directed, acyclic graph when serialising to RPC/encoded SOAP or a tree
! when using document/literal messages. Read or write between attributes
! and class fields, bind to children and the conversion is
! complete... If only it were so straightforward. Undermining it all is
! a fundamental difference between the type systems of XML (especially
! that of XML Schema) and that of Java, making any mapping both complex
! and brittle.
  
  \subsubsection{Binding XML Elements to Java Classes}
***************
*** 53,57 ****
  This is a fundamental difference which means that one cannot
  accurately model an XSD type hierarchy in a Java class hierarchy. All
! one can do is inaccurately model it.Here, for example, a postcode is
  modelled by restricting a string:
  
--- 53,57 ----
  This is a fundamental difference which means that one cannot
  accurately model an XSD type hierarchy in a Java class hierarchy. All
! one can do is inaccurately model it. Here, for example, a postcode is
  modelled by restricting a string:
  
***************
*** 114,119 ****
  This appears a straightforward example of how O/X mapping should
  work. But what if the value of the one of the enumeration types is a
! reserved word?  Our API (from section \ref{intro:experience} contains
! a lifecycle state machine like this:
  
  \begin{verbatim}
--- 114,119 ----
  This appears a straightforward example of how O/X mapping should
  work. But what if the value of the one of the enumeration types is a
! reserved word?  Our API (as described in section
! \ref{intro:experience} contains a lifecycle state machine like this:
  
  \begin{verbatim}
***************
*** 133,141 ****
  all states as {\tt value1}, {\tt value2}, and so on, for the entire
  list.  The enumeration names in the Java source no longer contain any
! informative value at all, other than a position number in the
! set. Any change to the enumeration
! could reorder the values, without this change being detected by code
! that used the enumeration. The defect would only show up in interoperability
! testing. 
  
  \subsubsection{Unportable types}
--- 133,140 ----
  all states as {\tt value1}, {\tt value2}, and so on, for the entire
  list.  The enumeration names in the Java source no longer contain any
! informative value at all, other than a position number in the set. Any
! change to the enumeration could reorder the values, without this
! change being detected by code that used the enumeration. The defect
! would only show up in interoperability testing.
  
  \subsubsection{Unportable types}
***************
*** 145,162 ****
  expect to be able to have a SOAP runtime serialise a database
  connection instance and have it reconstituted in working order at the
! far end. One might hope that a {\tt java.util.Hashtable} could be
! translated into some structure that could be turned into a
! platform-specific equivalent at the far end. But surely a {\tt
! java.util.Calendar} object could be sent over the wire, as it
! apparently maps so well to the {\tt xsd:dateTime} type in XML Schema?
  
! We can certainly send such times. They are readable on the wire, and
! are mapped into whatever a remote endpoint uses to represent
! time. Unfortunately, due to differences in expectations between Java
! and .NET date/time classes, we cannot guarantee that the same time
! will be received at the far end. If both client and server are in the
! UTC time zone all works well, but if either of them are in a different
! location, hours appear to get added or removed. Clearly a different
! expectation regarding time processing is taking place.
  
  This is an insidious defect as it is not apparent on any
--- 144,161 ----
  expect to be able to have a SOAP runtime serialise a database
  connection instance and have it reconstituted in working order at the
! far end, for example. One might hope that a {\tt java.util.Hashtable}
! could be translated into some XML structure that could be turned into
! a platform-specific equivalent at the far end. But surely a {\tt
! java.util.Calendar} object could be sent over the wire, with its
! obvious relationship to the {\tt xsd:dateTime} type in XML Schema?
  
! We can certainly attempt to send such times. They are readable on the
! wire, and are mapped into whatever the remote endpoint uses to
! represent time. Unfortunately, in this case, differences in
! expectations between Java and .NET date/time classes prevent the same
! time being received at the far end. If both client and server are in
! the UTC time zone all works well, but if either of them are in a
! different location, hours appear to get added or removed. Clearly a
! different expectation regarding time processing is at work.
  
  This is an insidious defect as it is not apparent on any
***************
*** 170,178 ****
  
  XML is a hierarchical data structure, and can only describe trees or
! lists or lists of data. Java classes almost invariably refer to other
! objects, often creating cyclic graphs of objects. If such a cyclic
! graph is to be mapped into XML, the mapping infrastructure must
! recognise the cycle, otherwise the it would enter a non-terminating
! loop. Once the cycle is recognised, it must be addressed. The options
  appear to be:
  \begin{enumerate}
--- 169,177 ----
  
  XML is a hierarchical data structure, and can only describe trees or
! lists of data. Java classes almost invariably refer to other objects,
! often creating cyclic graphs of references. If such a cyclic graph is
! to be mapped into XML, the mapping infrastructure must recognise the
! cycle (a naive implementation would enter a non-terminating
! loop). Once the cycle is recognised, it must be addressed. The options
  appear to be:
  \begin{enumerate}
***************
*** 187,192 ****
  The only one of these solutions which seamlessly marshals cyclic
  graphs of objects is the second: inserting cross references into the
! XML. The SOAP solution for this is SOAP Section 5 encoding, as
! documented in \cite{spec:SOAP1.1}. This linking mechanism is only
  supported in RPC/encoded messages; the document/literal message format
  does not allow it.
--- 186,191 ----
  The only one of these solutions which seamlessly marshals cyclic
  graphs of objects is the second: inserting cross references into the
! XML. The SOAP solution for this is described in section 5 of the
! specification \cite{spec:SOAP1.1}. This linking mechanism is only
  supported in RPC/encoded messages; the document/literal message format
  does not allow it.
***************
*** 220,226 ****
  \begin{enumerate}
  \item Mapping an incoming message to a web service object requires
! guessing the namespace of either the operation itself or its
! parameters. This guessing can be wildly inaccurate when the web
! service's Java interface was generated from WSDL using package
  renaming.
  \item When dynamic invocation is desired (service invocation without
--- 219,225 ----
  \begin{enumerate}
  \item Mapping an incoming message to a web service object requires
! that either the namespace of either the operation itself or its
! parameters be guessed. This guessing can be wildly inaccurate when the
! web service's Java interface was generated from WSDL using package
  renaming.
  \item When dynamic invocation is desired (service invocation without
***************
*** 239,248 ****
  \label{objections:o-x:validation}
  
! When a message is received, the serialised form is generated and
! passed to the handlers for processing. No validation of the incoming
! XML against the message schema is performed, and in particular any
! restrictions on the number of times an item is required are not
! checked. This forces the implementation code to follow one of two
! paths:
  \begin{enumerate}
  
--- 238,247 ----
  \label{objections:o-x:validation}
  
! hen a message is received, the serialised form is generated and
! passed to the handlers for processing. In typical web service stacks,
! no validation of the incoming XML against the message schema is
! performed, and in particular any restrictions on the number of times
! an item is required are not checked. This forces the implementation
! code to follow one of two paths:
  \begin{enumerate}
  
***************
*** 252,309 ****
  only surfacing when a third party attempts to use the service.
  
! \item The developers could write procedural logic to verify that
! the Java classes representing a deserialised message have a
! structure that matches their expectation based on the schema. This
! requires an understanding of the schema, knowledge of the
! serialisation mapping and potential trouble spots, the willingness to
! write the tests to validate this extra logic, and most of all, time.
  
  \end{enumerate}
  
  We suspect that most services err on the side of ignorance, and do not
! validate their incoming messages adequately. This brings into question
! their interoperability.
  
  \subsubsection{Inadequate Mixing of XML and Serialised Data}
  \label{objections:o-x:mixing}
  
! JAX-RPC and JAXM are two different views of the world. What does JAX-RPC
! do when it encounters a piece of random XML in a message? It creates a
! SAAJ {\tt Node} to describe that part of the tree.
! 
! From that point on, the tree below the node is permanently isolated
! from the JAX-RPC model: the developer has sailed off the edge of the
! JAX-RPC world, and fallen into the universe of XML. Any O/X mappings
! which may exist for data within this piece of the message are now
! inaccessible, all that is left is the low-level JAXM API. 
  
! This behaviour makes it appear that incorporating arbitrary XML within
! a SOAP message is not an approved action, yet the ability to easily
! incorporate such XML is a key aspect of SOAP's flexibility and a key
! to its being more extensible and less brittle than its predecessors.
  
  \subsubsection{Fault processing}
  \label{objections:soap-not-rmi:faults}
  
! JAX-RPC tries to marshal Java faults over the network in such a way
! that they can be reconstituted at the far end into the same fault.
! This is a somewhat complex process to manage, as the class name of the
! fault must be exchanged as the fault code. Since faults are often
! immutable, the standard serialisation mechanism of named getter and
! setter methods must be replaced by a more exotic one: getter methods
! are used to extract the contents of a fault, a fault which must offer
! a constructor that takes every attribute in a parameter of the same
! name\footnote{This implicitly requires code to be built with debugging
! information, so that the bytecode can be analysed to determine
! parameter names.}.
! 
! We believe that attempting to seamlessly marshal faults is a mistaken
! approach.  By propagating the still controversial ``declare all
! possible faults'' rule of Java into remote interfaces, it exposes
! platform implementation details. If a service could only raise a
! normal {\tt SOAPFault} unless its developers explicitly declared and
! implemented custom WSDL fault elements, service definition would be
! platform-neutral.
  
  
  Exposing implementation details in the service interface makes ensuring
--- 251,308 ----
  only surfacing when a third party attempts to use the service.
  
! \item The developers could write procedural logic to verify that the
! Java classes representing a deserialised message have a structure that
! matches their expectations given the schema. This requires an
! understanding of the schema, knowledge of the serialisation mapping
! and its potential trouble spots, the willingness to write the tests to
! validate this extra logic, and most of all, the time to do so.
  
  \end{enumerate}
  
  We suspect that most services err on the side of ignorance, and do not
! validate their incoming messages adequately. This brings their ability
! to operate in a heterogeneous environment into serious question.
  
  \subsubsection{Inadequate Mixing of XML and Serialised Data}
  \label{objections:o-x:mixing}
  
! JAX-RPC and JAXM are two different views of the world. When JAX-RPC
! encounters a piece of XML which cannot be deserialised within a
! message, it creates a SAAJ {\tt Node} to describe that part of the
! document tree.  From that point on, the tree below the node is
! permanently isolated from JAX-RPC processing (in some sense the
! developer has sailed off the edge of the JAX-RPC world, and fallen
! into the universe of XML.) Any O/X mappings which may exist for data
! within this piece of the message are now inaccessible: all that is
! left is the low-level JAXM API.
  
! This behaviour implies that incorporating arbitrary XML within a SOAP
! message is not an approved action, yet the ability to easily
! incorporate such XML is a key aspect of SOAP's flexibility and a major
! part of enabling it to be more extensible and less brittle than its
! predecessors.
  
  \subsubsection{Fault processing}
  \label{objections:soap-not-rmi:faults}
  
! JAX-RPC makes an attempt to marshal Java faults over the network in
! such a way that they can be reconstituted at the far end into the same
! fault.  This is a somewhat complex process to manage, as the class
! name of the fault must be exchanged as the fault code. Since faults
! are often immutable, the standard serialisation mechanism of named
! getter and setter methods must be replaced by a more exotic one:
! getter methods are used to extract the contents of a fault, a fault
! which must offer a constructor that takes every attribute in a
! parameter of the same name\footnote{This implicitly requires code to
! be built with debugging information, so that the bytecode can be
! analysed to determine parameter names.}.
  
+ We believe that attempting to seamlessly marshal faults is a
+ problematic approach.  Furthermore, by propagating the still
+ controversial ``declare all possible faults'' Java requirement into
+ remote interfaces, it exposes platform implementation details. If a
+ service could only raise a normal {\tt SOAPFault} unless its
+ developers explicitly declared and implemented custom WSDL fault
+ elements, service definition would be platform-neutral.
  
  Exposing implementation details in the service interface makes ensuring
***************
*** 316,326 ****
  
  SOAP's parentage includes XML-RPC \cite{winer:xmlrpc} and (indirectly)
! COM/DCOM \cite{dbox:SoapHistory,dbox:com}and CORBA \cite{vinoski:CORBA}. It was clearly
! designed at its outset to be a form of remote procedure call in XML,
! over HTTP. Over time, the world-view that lead to that choice has
! changed. Though it is often presented as a form of RPC, it is coming
! to be seen that it is more powerful when viewed as a system where
! arbitrary XML documents are exchanged between parties, potentially
! asynchronously, and potentially via intermediaries.
  
  In this world, the programming paradigms that seemed appropriate for
--- 315,326 ----
  
  SOAP's parentage includes XML-RPC \cite{winer:xmlrpc} and (indirectly)
! COM/DCOM \cite{dbox:SoapHistory,dbox:com}and CORBA
! \cite{vinoski:CORBA}. It was clearly designed at its outset to be a
! form of remote procedure call in XML, over HTTP. Over time, the
! world-view that lead to that choice has changed. Though it is often
! presented as a form of RPC, we would argue that it is coming to be
! seen as more powerful when viewed as a system where arbitrary XML
! documents are exchanged between parties, potentially asynchronously,
! and potentially via intermediaries.
  
  In this world, the programming paradigms that seemed appropriate for
***************
*** 333,342 ****
  
  When we begin to work over long-haul connections, however, or with
! large content (e.g.\ fifteen megabyte attachments), the limitations of
  RPC become clear. The greatest of these is that RPC is
  synchronous. Although asynchronous behaviours can, with some
  difficulty, be introduced, this is not the natural way for RPC to
  behave. As content becomes larger and the network latency increases,
! the problems posed by synchronous calls become much more acute.
  
  Currently, our only option is to split network communication into a
--- 333,342 ----
  
  When we begin to work over long-haul connections, however, or with
! large content (e.g.\ several megabyte attachments), the limitations of
  RPC become clear. The greatest of these is that RPC is
  synchronous. Although asynchronous behaviours can, with some
  difficulty, be introduced, this is not the natural way for RPC to
  behave. As content becomes larger and the network latency increases,
! the problems posed by synchronous calls become more and more acute.
  
  Currently, our only option is to split network communication into a
***************
*** 344,360 ****
  provides the programmer no way to give the user effective feedback or
  control over the communications. There is no way to receive progress
! notifications or cancel an active call, even though the underlying
! transport code invariably permits such features. This has caused
! problems when one of the authors wrote a GUI front end to a service
! that could accept 15-30MB CAD files: while multithreading could keep
! the UI responsive, there was no way to present an upload progress
! indicator or offer a cancel button. These are both features one
! expects in a web browser.
  
  Again, following our principle that SOAP technologies should uphold
  the same desiderata as SOAP itself, we note that one reason SOAP was
! adopted was to make working over long haul connections simpler. By
! making it both difficult and complicated to work over a long
! connection, JAX-RPC fails to meet these criteria for a SOAP
  technology.
  
--- 344,361 ----
  provides the programmer no way to give the user effective feedback or
  control over the communications. There is no way to receive progress
! notifications or cancel an active call, despite the face that the
! underlying transport code invariably permits such features. This can
! cause problems when working with file transfers, foe example: one of
! the authors wrote a GUI front end to a service that could accept
! 15-30MB CAD files, and whilst multithreading could keep the UI
! responsive, there was no way to present an upload progress indicator
! or offer a cancel button. These are both features one expects in an
! application of this kind.
  
  Again, following our principle that SOAP technologies should uphold
  the same desiderata as SOAP itself, we note that one reason SOAP was
! adopted was to simplify the task of working over long haul
! connections. By making it both difficult and complicated to work over
! a long connection, JAX-RPC fails to meet this criterion for a SOAP
  technology.
  
***************
*** 368,406 ****
  IDL-free communication mechanism, which relies on introspection to
  create proxy classes and to marshal classes. It works because the
! systems at both ends are Java, usually different pieces of a single
! larger application. Even then, it works best if both ends are running
! the same version of all classes.
  
! With synchronised versions of common code, objects can be trivially
! serialised and sent over a network connection. Exceptions are just
! another type of object, and so too can be sent over the wire. There is
! no need for an IDL, as Java interface declarations can perform much of
! the same role. And as the recipient is a remote object, state is
! automatic.  One can even keep code synchronised by using a special
! class loader, one that fetches code from jointly-accessible URLs.
  
  JAX-RPC tries to reuse many of the programming patterns of RMI. For
! example, the runtime will attempt to serialise classes marked as
! {\tt Serializable}, ignoring those fields marked as
! {\tt transient}. It will even serialise complex compound objects where
! possible. The user appears to have a reference to something like an
! object, though one that represents the current conversation with an
! endpoint, not a direct endpoint proxy.
  
  SOAP strove to overcome many of the failings of precursor technologies
  like CORBA and DCOM. These technologies work well over local area
  networks, and enable rich bidirectional communications, but are not
! completely cross platform\footnote{Arguably for political rather than
! technical reasons}, and ended up being used to produce distributed
! object systems that were too tightly coupled. Recall that one of our
! key hopes from adopting SOAP (section \ref{introduction}) was to
! enable loose coupling between components of a distributed system.
  
! While Java RMI provides convenience, the one thing it does not provide in any way
! is loose coupling. Interacting systems typically run from the same
! codebase, and each element of the distributed system usually contains many 
! implicit assumptions about the rest of the system. By trying to turn SOAP into RMI,
! we imitate this architecture, and risk losing
! the very things we turned to SOAP for in the first place.
  
  % Tight coupling has proven to be a bad thing in a distributed
--- 369,410 ----
  IDL-free communication mechanism, which relies on introspection to
  create proxy classes and to marshal classes. It works because the
! systems at both ends are running on the Java platform, typically
! different pieces of a single larger application. Even then, it is
! most effective when both ends are using the same versions of all
! classes.
  
! With the kind of versions synchronisation of common code described
! above, objects can be trivially serialised and transmitted across a
! network connection. Exceptions become just another type of object, and
! so too can be sent over the wire. There is no need for an IDL, as Java
! interface declarations can perform much of the same role. And as the
! recipient is a remote object, state is automatic. One can even keep
! code synchronised by using a special class loader, one that fetches
! code from jointly accessible URLs.
  
  JAX-RPC tries to reuse many of the programming patterns of RMI. For
! example, the runtime will attempt to serialise classes marked as {\tt
! Serializable}, ignoring those fields marked as {\tt transient}. It
! will even serialise complex compound objects where possible. The user
! appears to have a reference to something like an object, though one
! that represents the current conversation with an endpoint, not a
! direct endpoint proxy.
  
  SOAP strove to overcome many of the failings of precursor technologies
  like CORBA and DCOM. These technologies work well over local area
  networks, and enable rich bidirectional communications, but are not
! completely cross platform\footnote{Admittedly for arguably political
! rather than technical reasons}, and ended up being used to produce
! distributed object systems that were too tightly coupled. Recall that
! one of our key hopes in adopting SOAP (section \ref{introduction}) was
! to enable loose coupling between the components of a distributed
! system.
  
! While Java RMI provides convenience, the one thing it does not provide
! in any way is loose coupling. Interacting systems typically run from
! the same codebase, and each element of the distributed system contains
! many implicit assumptions about the rest of the system. By trying to
! turn SOAP into RMI, we imitate this architecture, and risk losing the
! very things we turned to SOAP for in the first place.
  
  % Tight coupling has proven to be a bad thing in a distributed

Index: jaxrpc.tex
===================================================================
RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/jaxrpc.tex,v
retrieving revision 1.16
retrieving revision 1.17
diff -C2 -d -r1.16 -r1.17
*** jaxrpc.tex	25 Jan 2005 22:54:48 -0000	1.16
--- jaxrpc.tex	28 Jan 2005 20:32:43 -0000	1.17
***************
*** 7,11 ****
  
  % paper title
! \title{What's wrong with the Java SOAP API?}
  
  % author names and affiliations
--- 7,11 ----
  
  % paper title
! \title{Rethinking the Java SOAP Stack}
  
  % author names and affiliations
***************
*** 26,31 ****
  \input{abstract}
  
- \IEEEPeerreviewmaketitle
- 
  %\tableofcontents
  
--- 26,29 ----
***************
*** 41,46 ****
  %bibliographystyle{alpha}
  %\bibliography{bibliography}
! \bibliographystyle{IEEETran.bst}
! \bibliography{IEEEabbrv}
  
  \end{document}
--- 39,44 ----
  %bibliographystyle{alpha}
  %\bibliography{bibliography}
! \bibliographystyle{IEEEtran}
! \bibliography{IEEEabrv,bibliography}
  
  \end{document}

Index: alpine.tex
===================================================================
RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/alpine.tex,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -d -r1.12 -r1.13
*** alpine.tex	8 Nov 2004 12:08:57 -0000	1.12
--- alpine.tex	28 Jan 2005 20:32:43 -0000	1.13
***************
*** 24,42 ****
  unwanted implementation dependencies and hampers interoperability.
  
! What will Alpine consist of then? With so much stripped out, a SOAP
! stack gets reduced to its essentials: a system for managing the flow
! of messages through a set of handlers, and libraries to handle
! transport across supported the protocols. Core compliance with the
! SOAP protocol will be provided, namely envelope validation and
! \verb|mustUnderstand| processing of headers. Developers will be
! expected to use XPath specifications to work with contents of the
! message; we are considering basing our design upon the ``XOM'' XML framework.
! \cite{harold:xom}.
  
! This is not going to be a SOAP stack
! for use by anyone who wants to make SOAP look like RMI, nor for anyone
! who wants to ignore the format of the messages sent or over the wire.
! Instead, Alpine will provide the basic housekeeping and handler
! chain management to make life simpler for web service developers.
  
  \subsection{Design Goals}
--- 24,42 ----
  unwanted implementation dependencies and hampers interoperability.
  
! With so much stripped out, Alpine will be a SOAP stack reduced to its
! essentials: a system for managing the flow of messages through a set
! of handlers, and libraries to handle transport across supported the
! protocols. Core compliance with the SOAP protocol will be provided,
! namely envelope validation and \verb|mustUnderstand| processing of
! headers. Developers will be expected to use XPath specifications to
! work with contents of the message; we are considering basing our
! design upon the ``XOM'' XML framework.  \cite{harold:xom}.
  
! This will not be a SOAP stack that attempts to make SOAP look like
! Java RMI, nor will it prevent developers from being aware of the
! format of the messages sent over the wire. Instead, Alpine will just
! provide the basic housekeeping and handler chain management to make
! simplify web service development, leaving the interpretation and
! mapping of the XML messages to the applications themselves.
  
  \subsection{Design Goals}
***************
*** 70,142 ****
  \label{alpine:validation}
  
! Although we are still unsure as to how complete our WSDL support will be, 
! we note that doc/literal SOAP messages can be validated simply by comparing
! the incoming messages to the XML Schema that describes it. 
  
  Mainstream SOAP stacks do not do this, usually for performance
! reasons. This means that the set of XML documents which an endpoint can receive
! is significantly larger than the set of XML documents which its XML
! schema considers valid. With no built-in validation, developers must
! either write both validation logic and corresponding tests themselves,
! or ignore the problem. Given that there is no warning that the problem
! occurs, we suspect that ignorance is the common process. 
  
! Not writing the logic to recognise and reject illegal documents is
! unlikely to show up in development, especially if a test-centric
! process is not followed, but is inevitable once a service goes live,
! and callers using other languages invoke the service. Such insidious
! defects, defects that only show up in production, are never welcome.
  
! There is a trivial solution to this problem, one that is common to other XML
! stacks. It is: validate incoming messages against the XML schema of the service.
! We aim to implement a handler which will do this, which, if included on a
! handler chain, will reject invalid messages. It will also be able to validate
! outbound messages , which should be useful during development.
  
  \subsection{A Community SOAP Stack}
  \label{alpine:community}
  
! From the open source perspective, JAX-RPC creates many problems. Because the API
! hides all the XML, it creates a gulf between the implementation code and the end
! user code. This makes it hard for end users to become developers, something that
! open source platforms depend on.
  
  An open source project succeeds from the contributions of its users,
! and so depend upon users who are able and willing to understand the
! implementation. JAX-RPC, by its very nature, places too firm a divide
! between end users and developers.
  
- % We can see the consequences of this on the user mailing list for
- % Apache Axis. All too often, someone is confused by the errors that
- % occur when they try to do something that they expect to work like
- % Java RMI, such as sending low-level classes like a \verb|java.io.File|
- % instance, or a \verb|javax.swing.JPanel|. The latter is serialisable
- % in RMI, yet clearly does not make sense for an interoperable web
- % service.
- % 
- % While it would be easy to laugh at their na\"{i}ve and unrealistic
- % expectations, we have to recognise that these users have been led to
- % such expectations through a combination of marketing ("Web Services!
- % They're easy!") and the fact that JAX-RPC creates the illusion of
- % being just like RMI. It is often easy to write code that looks like a
- % SOAP service, only to try and deploy it and find at runtime that the
- % introspection system rejects Java classes as unacceptable, or that the
- % serialisation logic raises deserialisation exceptions when inbound
- % messages are processed. A quick perusal of the Apache Axis user list
- % \footnote{{\small \tt http://mail-archives.apache.org/eyebrowse/SummarizeList?listId=209}}
- % will demonstrate that these are amongst the most common problems.
- 
- With Alpine, we hope to avoid creating such a split, because the XML runs all
- the way through the toolkit. 
  
  \subsection{The Implications of Alpine}
  \label{alpine:implications}
  
! If Alpine succeeds, it will be a SOAP stack that requires advanced
! knowledge of XML before it can be used. This might appear to be a
  barrier to the widespread adoption of the tool, and perhaps it will
! prove so. Unlike commercial SOAP vendors, we have no fiscal benefit in
  making our product broadly usable. We will, however, have a SOAP
! implementation that all users should be able to understand and
  maintain.  Furthermore, we believe that a good understanding of XML is
  needed for any robust web service, and by forcing developers to
--- 70,127 ----
  \label{alpine:validation}
  
! Although we are still unsure as to how complete our WSDL support will
! be, we note that document/literal SOAP messages can be validated
! simply by comparing the incoming messages to the XML Schema that
! describes them.
  
  Mainstream SOAP stacks do not do this, usually for performance
! reasons. This means that the set of XML documents which an endpoint
! can receive is significantly larger than the set of XML documents
! which its XML schema considers valid. With no built-in validation,
! developers must either write both validation logic and corresponding
! tests themselves, or ignore the problem. Given that there is no
! warning that the problem occurs, we suspect that many developers
! remain unaware of the problem.
  
! Errors caused by the absence of logic to detect and reject illegal
! documents are unlikely to show up in development, especially if a
! test-centric process is not followed, but become inevitable once a
! service goes live, and callers using other languages invoke the
! servi...
 
[truncated message content]