From: Edmund S. <ic...@us...> - 2004-10-29 16:33:57
|
Update of /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv22085 Modified Files: alpine.tex implications.tex introduction.tex objections.tex wsdl.tex Log Message: Index: introduction.tex =================================================================== RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/introduction.tex,v retrieving revision 1.6 retrieving revision 1.7 diff -C2 -d -r1.6 -r1.7 *** introduction.tex 28 Oct 2004 15:05:28 -0000 1.6 --- introduction.tex 29 Oct 2004 16:33:47 -0000 1.7 *************** *** 29,63 **** Communication with SOAP can be viewed as XML-based remote procedure ! calls, or as a way of submitting XML documents to remote URLs ( with ! optional responses coming back as XML documents). These two different ! perspectives represent the RPC-centric and message-centric ! viewpoints. The RPC-centric model has become the primary ! model of SOAP APIs in Java. The Java APIs representing the two different underlying perspectives 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}. ! \subsubsection{JAXM} ! JAXM was written to support basic SOAP, and more complex scenarious ! such as asynchronous ebXML message exchange over SOAP, a requirement ! which introduces extra complexity to the design. ! Over time, the ebXML focus of JAXM has declined, while the API itself ! has been renamed SOAP with Attachments API for Java ---SAAJ \cite{spec:SAAJ-12}. ! In JAXM/SAAJ, the developer has a Java interface, bound to a ! class that represents the body of the message, with operations to ! manipulate the pieces. These operations include accessors and ! manipulators of the envelope, headers, the body and any binary attachments. In ! SAAJ, all these pieces of the model are accessed via interfaces which ! implement the DOM \cite{spec:DOM} model of navigating around XML nodes. ! 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 servlet is to ask a \verb|SOAPConnectionFactory| for a \verb|SOAPConnection| instance, and then make a blocking call of the endpoint. --- 29,63 ---- Communication with SOAP can be viewed as XML-based remote procedure ! calls, or as a way of submitting XML documents to remote URLs ! (optionally eliciting responses in the form of XML documents). These ! two different perspectives represent the RPC-centric and ! message-centric viewpoints. In Java, the RPC-centric model has become ! the primary model of SOAP APIs. The Java APIs representing the two different underlying perspectives 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} + \label{intro:jaxm} ! JAXM was written to support both basic SOAP, and more complex ! scenarious like asynchronous ebXML message exchange over SOAP. This ! flexibility introduces significant extra complexity to the design. Over time, the ebXML focus of JAXM has declined, while the API itself ! has been renamed SAAJ\footnote{SOAP with Attachments API for Java} ! \cite{spec:SAAJ-12}. ! In JAXM/SAAJ, the developer works with the SOAP message through Java ! interfaces derived from DOM\footnote{Document Object Model} ! \cite{spec:DOM}. These are bound to a class that represents the body ! of the message, which provides various operations to manipulate the ! pieces. These include accessors and manipulators for the envelope, ! headers, body and any binary attachments. ! 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 \verb|SOAPConnectionFactory| for a \verb|SOAPConnection| instance, and then make a blocking call of the endpoint. *************** *** 68,104 **** with SOAP in Java. - \subsubsection{JAX-RPC} ! In JAX-RPC, all the details of how the message was ! encoded are hidden, and the developer works with Java objects created ! automatically from the XML data using a semi-standardised mapping process. ! ! Java classes can be automatically turned into SOAP endpoints, with each ! public method in the class exported as a SOAPAction; an operation with a ! request message and a response message. The message structure is described in a WSDL file, which can be hand-written, or automatically ! extracted from the Java classes through intospection. Client side ! proxy classes can be generated from the WSDL files, proxy classes which ! again provide a method for every SOAPAction. 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}. ! A good architectural feature of JAX-RPC is its \emph{handler chain}; an ! ordered sequence of classes that are configured to handle requests and ! responses. It is through the handler chain that support for new SOAP ! headers can be added to existing services, or extra diagnostics applied. ! Dispatch of operations to java methods, EJB methods or other ! destinations is actually implemented in specific handlers, showing that ! the handler chain is the foundation for the rest of the system. ! JAX-RPC is widely implemented, both by open source projects (for example ! Apache Axis \cite{apache:axis}), and by commercial vendors like Sun, IBM ! and BEA. The SOAP toolkits do all implement the appropriate version of ! JAXM/SAAJ to go alongside the RPC model, but this feature is not broadly ! covered. All the \emph{evangelisation} of SOAP focuses on JAXRPC, as do ! most of the examples in the vendors' documentation. The bias is such that, for Java development, JAXRPC \emph{is} SOAP. --- 68,106 ---- with SOAP in Java. \subsubsection{JAX-RPC} + \label{intro:jax-rpc} ! In JAX-RPC, 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 semi-standardised mapping process.Java classes ! can be automatically turned into SOAP endpoints, with each public ! method in the class exported as a {\tt SOAPAction}; an operation with ! a request message and a response message. The message structure is described in a WSDL file, which can be hand-written, or automatically ! extracted from the Java classes through introspection. ! Client side proxy classes can be generated from the WSDL files, proxy ! classes which again provide a method for every {\tt SOAPAction}. 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}; ! 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, EJB 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 ! example Apache Axis \cite{apache:axis}), and by commercial vendors ! like Sun, IBM and BEA. These SOAP toolkits do all implement the ! appropriate version of JAXM/SAAJ to go alongside the RPC model, but ! this feature is neither broadly promoted nor used. All the ! \emph{evangelisation} of SOAP focuses on JAXRPC, as do most of the ! examples in the vendors' documentation. The bias is such that, for Java development, JAXRPC \emph{is} SOAP. *************** *** 107,131 **** \label{intro:experience} ! Both authors have recently been making independent implementations of ! a SOAP API for deployment. This API, specified in a set of XML Schema ! (XSD) \cite{spec:XSD} and Web Services Description Language (WSDL) ! files \cite{spec:WSDL-11} defines a service endpoint which providing ! seven operations. These operations permit suitably authenticated ! callers to deploy distributed applications to a grid 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 practice. However, the XSD file for the service messages is approximately 2000 lines, of which seventy-five percent is either comment or XSD annotations. 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 functional clients and servers, problems that we attribute to JAX-RPC. ! ! In section \ref{objections} we discuss a number of problems we believe ! this work highlighted with JAX-RPC. Section \ref{objections:wsdl-gen} outlines the particular problems we believe typical JAX-RPC oriented approaches to WSDL generation create. --- 109,133 ---- \label{intro:experience} ! The authors have recently been involved in developing independent ! implementations of a SOAP API for deployment \cite{draft:CDDLM}. This ! API, specified in a set of XML Schema (XSD) \cite{spec:XSD} and Web ! Services Description Language (WSDL) files \cite{spec:WSDL-11} defines ! a service endpoint which providing seven operations. These operations ! permit suitably authenticated callers to deploy distributed ! applications to a grid 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 practice. However, the XSD file for the service messages is approximately 2000 lines, of which seventy-five percent is either comment or XSD annotations. 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 functional clients and servers, problems that we attribute to JAX-RPC. ! In section \ref{objections} we discuss a number of the problems we ! believe this work highlighted. Section \ref{objections:wsdl-gen} outlines the particular problems we believe typical JAX-RPC oriented approaches to WSDL generation create. Index: objections.tex =================================================================== RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/objections.tex,v retrieving revision 1.9 retrieving revision 1.10 diff -C2 -d -r1.9 -r1.10 *** objections.tex 28 Oct 2004 15:05:29 -0000 1.9 --- objections.tex 29 Oct 2004 16:33:47 -0000 1.10 *************** *** 5,26 **** \label{objections:o-x} ! JAX-RPC attempts to turn an XML document into Java classes derived from the type ! information attached to nodes. This is distinct from the type of mapping ! performed by DOM implementations, in that the classes are ``serialised'' from ! the XML tree, not merely created to represent it (it is a semantic rather than ! syntactic mapping). This serialisation/deserialisation is an essential part of ! JAX-RPC, allowing method calls to be translated into SOAP requests, and responses translated back into Java objects. We believe that the term \emph{serialisation} downplays the nature of the problem, likening it to the more tractable problem of creating a ! non-portable persistence format for a class. ! ! We prefer to use the term \emph{O/X mapping} to emphasise the ! similarities it has with the heavily studied \emph{O/R mapping ! problem}\footnote{ \emph{"Object-relational mapping is the Vietnam of ! Computer Science"} - Ted Neward. He means that it's a problem you can ! never declare victory over, merely invest more and more effort in to ! get deeper into the quagmire. %{\small \tt http://www.neward.net/ted/weblog/index.jsp?date=20041003#1096871640048} }. --- 5,24 ---- \label{objections:o-x} ! JAX-RPC attempts to turn an XML document into Java classes, using the ! type information attached to nodes. This is distinct from the kind of ! mapping performed by DOM implementations, in that the classes are ! ``serialised'' from the XML tree, not merely created to represent it ! (it is a semantic rather than syntactic mapping). This ! serialisation/deserialisation is an essential part of JAX-RPC, ! allowing method calls to be translated into SOAP requests, and responses translated back into Java objects. We believe that the term \emph{serialisation} downplays the nature of the problem, likening it to the more tractable problem of creating a ! non-portable persistence format for a class. Instead, we prefer to use ! the term \emph{O/X mapping} to emphasise the similarities it has with ! the heavily studied \emph{O/R mapping problem}\footnote{ ! \emph{"Object-relational mapping is the Vietnam of Computer Science"} ! - Ted Neward. %{\small \tt http://www.neward.net/ted/weblog/index.jsp?date=20041003#1096871640048} }. *************** *** 32,50 **** 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 doc/lit 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. ! \subsubsection{Binding XML Elements to Java Classes} \label{objections:o-x:xml-classes} ! The language of XMLSchema is much richer than the object model of Java. In Java, inheritance can extend a type, and change some existing ! semantics, but derivation by restriction is not explictly supported. Java, in common with many object oriented programming environments, allows derived types to expand upon the capabilities of --- 30,48 ---- 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} \label{objections:o-x:xml-classes} ! The language of XML Schema is much richer than the object model of Java. In Java, inheritance can extend a type, and change some existing ! semantics, but derivation by restriction is not explicitly supported. Java, in common with many object oriented programming environments, allows derived types to expand upon the capabilities of *************** *** 54,108 **** This fundamental difference 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 %\todo{more entertaining example. something like `us-beer' is a %restriction of type `beer' where alcohol is a removed attribute} - \begin{verbatim} <simpleType name="UKPostcode"> ! <restriction base="xsd:string"> ! <pattern value="[A-Z]{2}\d \d[A-Z]{2}"/> ! </restriction> </simpleType> \end{verbatim} ! The actual result is going to be a simple class of type string; all restriction information ! will be lost in the transformation from WSDL to Java. ! ! This is a fundamental difference, and one which would appear to remain ! intractible except in special cases addressed on a case-by-case ! basis. \subsubsection{Mapping XML Names to Java Identifiers} \label{objections:o-x:names} ! Not all XML names can be turned into Java identifiers. ! XML names must begin with a letter in one of many Unicode languages, ! an ideograph or a an underscore (``\_'') . They can be followed by any of the same ! characters, and also a hyphen ``-'' or a full stop ``.''. Some examples ! are: {\tt schr\"odinger}, {\tt \_unknown.type-set}, and {\tt String}. ! ! Java identifiers are almost a proper subset of XML names ! \footnote{Java names are not a subset only because XML names beginning in "xml" (any case) are reserved}, ! which means that the system needs to map from the XML names to valid ! class and package names, package names being derived from namespace URLs ! if not overridden. This naming is inordinately complex. When a new version ! of Java is released, the mapping logic needs to be updated to add new ! reserved works (such as {\tt assert} and {\tt enum}), else the ! generated code will no longer compile in the enhanced language. Such an ! upgrade will break any existing code that linked to classes using these ! names. \subsubsection{Enumerations} One specific example that deserves special mention is how {\tt xsd:enumeration} declarations are mapped to Java. Prior to ! Java1.5, there was no explict {\tt enum} clause in the language, so workarounds were developed. The JAX-RPC solution is that of a common pattern: to declare a class with a public static instance representing --- 52,105 ---- This fundamental difference 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: %\todo{more entertaining example. something like `us-beer' is a %restriction of type `beer' where alcohol is a removed attribute} \begin{verbatim} <simpleType name="UKPostcode"> ! <restriction base="xsd:string"> ! <pattern value="[A-Z]{2}\d \d[A-Z]{2}"/> ! </restriction> </simpleType> \end{verbatim} ! The actual result is going to be a simple class of type {\tt String}: ! all restriction information will be lost in the transformation from ! XML Schema to Java. This is a fundamental difference, and one which ! would appear to remain intractable except in special cases. \subsubsection{Mapping XML Names to Java Identifiers} \label{objections:o-x:names} + Not all XML names can be turned into Java identifiers. XML names may + begin with a letter in one of many Unicode languages, an ideograph or + an underscore (``\_'') . They can be followed by any of the same + characters, and also a hyphen ``-'' or a full stop ``.''. Some + examples are: {\tt schr\"odinger}, {\tt \_unknown.type-set}, and {\tt + String}. ! Java identifiers almost comprise a proper subset of XML names ! \footnote{XML names beginning in "xml" (any case) are reserved}, ! which means that the system needs to perform a non-trivial mapping ! from the XML names to valid class and package names. Package names ! typically being derived from namespace URLs if not overridden. + The translation is inordinately complex and brittle: whenever a new + version of Java is released, the logic must be updated to avoid new + reserved words (like {\tt assert} and {\tt enum}), or the generated + code will no longer compile in the enhanced language. Needless to say, + such an upgrade will break any existing code that linked to old + classes which made use of these names. \subsubsection{Enumerations} + \label{objections:o-x:enum} One specific example that deserves special mention is how {\tt xsd:enumeration} declarations are mapped to Java. Prior to ! Java 1.5, there was no explicit {\tt enum} clause in the language, so workarounds were developed. The JAX-RPC solution is that of a common pattern: to declare a class with a public static instance representing *************** *** 111,117 **** value in the enumeration. ! This is a simple example of how O/X mapping should work. Except, what if the ! value of the one of the enumeration types is a reserved word? ! Take the lifecycle state machine we have: \begin{verbatim} --- 108,115 ---- value in the enumeration. ! 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:experiences} contains ! a lifecycle state machine like this: \begin{verbatim} *************** *** 127,158 **** \end{verbatim} ! One element in the enumeration is reserved, {\tt null}. The JAX-RPC ! specification states that the implementation must must now enumerate all ! states as {\tt value1}, {\tt value2}, and so on, for the entire list. ! This means the enumeration names in the Java source no longer contains ! any value at all, other than the position number in the set. This is ! inordinately brittle, as any change to the enumeration could reorder the ! values, without the code detecting a change. ! \subsubsection{Unportable types} \label{objections:o-x:types} ! Some Java types are explicitly unportable. One would not expect to be ! able to have a SOAP runtime serialise a database connection instance and ! have it read at the far end. One would hope that a hashtable could be ! translated to a structure that would be turned into a platform-specific ! equivalent at the far end. Yet surely, surely, a {\tt java.util.Calendar} ! object could be sent over the wire, as it maps so well to the ! {\tt xsd:dateTime} type in XML schema. ! Certainly we can send such times. They are readable on the wire, and ! they get mapped into whatever a platform has at the far end to represent ! time. Unfortunately, due to differences in expectations between Java and ! .NET date/time classes, we can not 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 class of defect as it is not apparent on any --- 125,156 ---- \end{verbatim} ! One element in this enumeration is reserved: {\tt null}. However, the ! JAX-RPC specification states that an implementation must now enumerate ! 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. This is inordinately brittle, as any change to the enumeration ! could reorder the values, without the code detecting a change. \subsubsection{Unportable types} \label{objections:o-x:types} ! Some Java types are by nature explicitly unportable. One would not ! expect to be able to have a SOAP runtime serialise a database ! connection instance and have it reconsituted 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 has to represent ! time. Unfortunately, due to differences in expectations between Java ! and .NET date/time classes, we can not 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 class of defect as it is not apparent on any *************** *** 161,192 **** different platforms, attempt to use the service. ! Our service API now uses UTC seconds since 1/1/1970, the classic {\tt time\_t} ! format, as our time representation. This is no longer human readable, ! but it works. \subsubsection{Message validation} \label{objections:o-x:validation} ! When a message is received, the serialised form is generated and passed ! to the handlers for processing. What does not take place is any ! validation of the incoming XML against the schema. 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. ! Firstly, it could ignore the problem. If the client code and functional ! tests do not generate invalid messages --as is likely if they are also ! all written in JAX-RPC-- then the problem not be noticed. It will only ! surface when a third party attempts to use the service. ! Secondly, the developers could write the procedural logic to verify that ! the java classes representing the deserialised message have a structure ! that matches the expectations of the schema. This requires an ! understanding of the schema, knowledge of the serialisation mapping and ! potential troublespots, the willingness to write the tests to validate ! this extra logic, and most of all, time. We suspect that most services err on the side of ignorance, and do not ! validate their incoming messages adequately. ! \subsubsection{Inadequate Mixing of XML and Serialised Data} --- 159,223 ---- different platforms, attempt to use the service. ! Our service API now uses UTC seconds since 1/1/1970, the classic {\tt ! time\_t} format, as our time representation. This is no longer human ! readable, but it works\footnote{It violates the spirit (if not the ! letter) of SOAP's aim to be self-describing, however.}. ! ! \subsubsection{XML Metadata and Namespaces} ! \label{objections:o-x:namespaces} ! ! As discussed in the previous sections, XML Schema provides a type ! system that is much richer than that of Java. One aspect not mentioned ! so far is the relationship between XML metadata, notably namespaces, ! and Java classes. ! ! The problem is essentially as follows: each node in an XML message can ! have attached to it a namespace. There is no related construct in Java ! which can model this accurately. The choice that is normally made is ! to model it innaccurately by package names (mapping namespaces to Java ! packages provides many of the problem discussed in section ! \ref{objections:o-x:names}). ! ! The problems that typically arise are of two kinds: ! \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 ! the use of pre-built stub classes) it can be very difficult to ! determine the correct namespaces for service invocations (the WSDL ! typically leaves this unspecified, meaning that for JAX-RPC services ! the WSDL is not a complete description of the service interface). ! \end{enumerate} \subsubsection{Message validation} \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. 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} ! \item It could ignore the problem. If the client code and functional ! tests do not generate invalid messages (as is likely if they are also ! all written in JAX-RPC) then the problem will not be noticed, only ! only surfacing when a third party attempts to use the service. ! \item The developers could write the procedural logic to verify that ! the Java classes representing the 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 ability to interoperate with general clients. \subsubsection{Inadequate Mixing of XML and Serialised Data} *************** *** 197,225 **** JAXM {\tt Node} to describe that part of the tree. ! From then on, the tree below that node is permanently isolated from the ! JAX-RPC; 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 JAX-M API. It is as if incorporating arbitrary XML ! within a SOAP message is not an approved action, yet this is the key ! aspect of SOAP's flexibility; a key to its aim of being more extensible ! and less brittle than its predecessors. \subsubsection{Fault processing} \label{objections:soap-not-rmi:faults} ! JAX-RPC tries to marshall Java faults over the network, in such a way ! that they can be reconstituted at the far end into the same fault. To ! manage this is a somewhat complex process, as the class name of the ! fault must be exchanged as the fault code. As faults are often immutable, the standard serialisation mechanism of named getter and ! setter methods is replaced by one more exotic. 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.}. ! We believe attempting to seamlessly marshall faults is a mistaken approach. By propagating the still controversial ``declare all possible faults'' rule of Java into remote interfaces, it exposes --- 228,258 ---- JAXM {\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 marshall 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 marshall faults is a mistaken approach. By propagating the still controversial ``declare all possible faults'' rule of Java into remote interfaces, it exposes *************** *** 235,239 **** Exposing implementation details in the service interface makes ensuring interoperability much more difficult. We recall that interoperability ! was yet another reason for adopting SOAP initially, and that this is yet another capability of SOAP's which JAX-RPC fails to deliver upon. --- 268,272 ---- Exposing implementation details in the service interface makes ensuring interoperability much more difficult. We recall that interoperability ! was a major reason for adopting SOAP initially, and that this is yet another capability of SOAP's which JAX-RPC fails to deliver upon. *************** *** 242,263 **** SOAP's parentage includes XML-RPC \cite{winer:xmlrpc} and indirectly ! COM/DCOM \cite{dbox:com}; ! was clearly designed at its outset to be a form of remote procedure call ! in XML, over HTTP. ! ! Over time that world-view has changed. While it is often presented as ! a form of RPC, it can also be viewed as a system where arbitrary XML documents ! are exchanged between parties, potentially asynchronously, and potentially ! via intermediares. ! ! In this world, a programming paradigm that seemed appropriate for an RPC ! infrastructure, looks out of place. ! On a fast network, RPC invocation is often a good choice as a ! communication paradigm. Other models of communication are harder to ! code, and the benefits are not apparent. When working over long-haul ! connections, however, or with large content (eg fifteen megabyte ! attachments), the limitations of RPC become clear. Currently, our only option is to split network communication into a --- 275,299 ---- SOAP's parentage includes XML-RPC \cite{winer:xmlrpc} and indirectly ! COM/DCOM \cite{dbox:com}. 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 + an RPC infrastructure look out of place. On a fast network, RPC + invocation is often a good choice, as other models of communication + are harder to code, and their benefits are not readily apparent. When + we begin to work over long-haul connections, however, or with large + content (eg fifteen megabyte attachments), the limitations of RPC + become clear. ! The greatest of these is that RPC is implicity 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 *************** *** 280,290 **** JAX-RPC suffers from a greater flaw than those classically associated with RPC invocation: it tries to make the communications look like ! Java RMI. Java RMI is a simple and effective mechanism for connecting ! Java classes running on different machines. It is an IDL-free ! communication mechanism, which relies on introspection to create proxy ! classes and to marshall 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 --- 316,326 ---- JAX-RPC suffers from a greater flaw than those classically associated with RPC invocation: it tries to make the communications look like ! Java RMI. Java's RMI system is a simple and effective mechanism for ! connecting Java classes running on different machines. It is an ! IDL-free communication mechanism, which relies on introspection to ! create proxy classes and to marshall 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 *************** *** 294,298 **** the same role. And as the recipient is a remote object, state is automatic. One can even keep code synchronized by using a special ! classloader, one that fetches code from jointly-accessible URLs. JAX-RPC tries to reuse many of the programming patterns of RMI. For --- 330,334 ---- the same role. And as the recipient is a remote object, state is automatic. One can even keep code synchronized 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 *************** *** 331,340 **** % cannot be treated except as a whole. And in a sufficiently large % system, it is impossible to co-ordinate the whole \cite{deutsch, ! % jini}. The move towards SOAP and a service oriented architecture was % advocated as a means of dealing with loose organisational coupling, by % forcing a loose data coupling between applications. - - \input{wsdl} --- 367,374 ---- % cannot be treated except as a whole. And in a sufficiently large % system, it is impossible to co-ordinate the whole \cite{deutsch, ! % JINI}. The move towards SOAP and a service oriented architecture was % advocated as a means of dealing with loose organisational coupling, by % forcing a loose data coupling between applications. \input{wsdl} Index: implications.tex =================================================================== RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/implications.tex,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** implications.tex 28 Oct 2004 15:05:28 -0000 1.1 --- implications.tex 29 Oct 2004 16:33:47 -0000 1.2 *************** *** 1,8 **** \section{Implications} ! \label{objections:implications} What are the implications of these problems? - 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 --- 1,7 ---- \section{Implications} ! \label{implications} What are the implications of these problems? 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 *************** *** 29,36 **** interoperability problems. ! ! On top of all of this, for users who do want to work with XML (typically those whose first project did not!) JAX-RPC is ! inappropriate because it hides everything.} Trying to integrate custom XML documents with JAX-RPC serialisations is possible, but very hard work. In Apache Axis, DOM trees get recreated when assigning or --- 28,34 ---- interoperability problems. ! On top of all of this, for users who do want to work with the XML (typically those whose first project did not!) JAX-RPC is ! inappropriate because it hides everything. Trying to integrate custom XML documents with JAX-RPC serialisations is possible, but very hard work. In Apache Axis, DOM trees get recreated when assigning or *************** *** 55,59 **** % faster and more reliable than the open source version. ! \subsubsection{The Future} \label{objections:implications:future} --- 53,57 ---- % faster and more reliable than the open source version. ! \subsection{The Future} \label{objections:implications:future} *************** *** 80,87 **** 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 XML-based processing will be near-impossible. %Instead the developers will be left at the mercy of JAX-RPC and JAX-B. --- 78,86 ---- 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. %Instead the developers will be left at the mercy of JAX-RPC and JAX-B. Index: alpine.tex =================================================================== RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/alpine.tex,v retrieving revision 1.6 retrieving revision 1.7 diff -C2 -d -r1.6 -r1.7 *** alpine.tex 28 Oct 2004 15:05:27 -0000 1.6 --- alpine.tex 29 Oct 2004 16:33:47 -0000 1.7 *************** *** 10,16 **** Our goal is to create a SOAP stack that is easy to use, robust, and maintainable. In order to do this, we are adopting an XML centric ! approach. Alpine will make no attempt to map between XML and custom Java ! classes, instead providing access to the SOAP messages using modern XML ! support libraries, librarie that make it easy to navigate an XML document. By avoiding O/X mapping we greatly decrease the volume and complexity of our code. Some may argue this will make Alpine more --- 10,16 ---- Our goal is to create a SOAP stack that is easy to use, robust, and maintainable. In order to do this, we are adopting an XML centric ! approach. Alpine will make no attempt to map between XML and custom ! Java classes, instead providing access to the SOAP messages using ! modern XML support libraries, which make it easy to navigate an XML document. By avoiding O/X mapping we greatly decrease the volume and complexity of our code. Some may argue this will make Alpine more *************** *** 53,71 **** \item Adopt the the handler chain pattern of Axis/JAX-RPC \item Target SOAP1.2 (POST) only, WS-I 1.1 ! \item Document/literal only, not rpc/encoded \item Run server-side, client-side, and as an intermediary. \item No support for JAX-RPC or JAX-M/SAAJ APIs. ! \item Configurable only procedurally -or through JMX. \item Permit dynamic handler chain configuration during message processing. ! \item One supported parser: Xerces \item Java 1.5 or later ! \item No provision of side features such as a built in HTTP server , or ! declarative configuration mechanism. These are delegated to other products. \end{enumerate} ! The core this design is likely to resemble JAX-M/SAAJ in in terms of classes, ! integrated with a handler chain based on the JAX-RPC/Axis model. ! \subsection{XSD validation} --- 53,71 ---- \item Adopt the the handler chain pattern of Axis/JAX-RPC \item Target SOAP1.2 (POST) only, WS-I 1.1 ! \item Document/literal only, not RPC/encoded \item Run server-side, client-side, and as an intermediary. \item No support for JAX-RPC or JAX-M/SAAJ APIs. ! \item Configurable only procedurally or through JMX. \item Permit dynamic handler chain configuration during message processing. ! \item One supported parser %: Xerces \item Java 1.5 or later ! \item No provision of side features such as a built in HTTP server, or ! a declarative configuration mechanism. These are delegated to other products. \end{enumerate} ! We believe the core of this design is likely to resemble JAX-M/SAAJ in ! in terms of classes, integrated with a handler chain based on the ! JAX-RPC/Axis model. \subsection{XSD validation} *************** *** 80,95 **** while element occurence declarations are ignored. ! 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 validation logic themselves ! -and corresponding tests, 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 not likely 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. We note that there is a trivial solution to this problem, one that is --- 80,95 ---- while element occurence declarations are ignored. ! 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. We note that there is a trivial solution to this problem, one that is *************** *** 98,122 **** the effect is to hide defects. - \subsection{A Community SOAP Stack} \label{alpine:community} ! From the perspective of an open source project, JAX-RPC creates ! many problems as it isolates all the XML in the implementation, it creates a huge gulf between the exceedingly complex implementation code (low level SAX and DOM processing, code generation from WSDL metadata, WSDL generation from introspection, fault processing) and the end user code. This makes it hard for end users to become ! developers, which is exactly what open source platforms need. Open ! source projects succeed from the contributions of the 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 this on the user mailing list for Apache ! Axis. All too often, someone is confused by the errors displayed when ! they try and do something that they expect to work like RMI, such as ! send an low level class such as \verb|java.io.File| instance, or a ! \verb|javax.swing.JPanel|. The latter is serializable 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 --- 98,123 ---- the effect is to hide defects. \subsection{A Community SOAP Stack} \label{alpine:community} ! From the perspective of an open source project, JAX-RPC creates many ! problems as it isolates all the XML in the implementation. This creates a huge gulf between the exceedingly complex implementation code (low level SAX and DOM processing, code generation from WSDL metadata, WSDL generation from introspection, fault processing) 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 serializable ! 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 *************** *** 124,153 **** 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 even relatively easy to write the ! code that looks like a SOAP service, and then try and deploy it, only ! to find at runtime that the introspection system rejects Java classes ! as unacceptable, or the serialization logic raises deserialization ! exceptions when inbound messages are processed. A quick perusal of the ! Apache Axis user list ! \footnote{http://mail-archives.apache.org/eyebrowse/SummarizeList?listId=209} ! will demonstrate that these (along with deployment failures) are the ! most common problems. With Alpine, we hope to avoid reaching a similar situation, where a small core of developers maintain a codebase for a much larger user base, for whom the operation of the stack is essentially ``black ! magic''. \subsection{The implications of Alpine} ! If Alpine succeeds, it will be a SOAP stack that requires advanced knowledge of ! XML before it can be used. This would seem a barrier to the success of ! the tool, and it may be so. Unlike commercial SOAP vendors, we have no ! fiscal benefit in making our product broadly usable. What we will do is ! have a SOAP implementation that all users should be able to maintain. ! Furthermore, we believe that a good understanding of XML is needed for ! any robust web service, and by forcing developers to acquire that skill ! early on, we avoid them having to learn it just before their shipping deadlines ! are missed. This may seem somewhat ruthless: to deny the right to write web --- 125,153 ---- 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 reaching a similar situation, where a small core of developers maintain a codebase for a much larger user base, for whom the operation of the stack is essentially ``black ! magic''. \subsection{The implications of Alpine} ! 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 ! acquire that skill early on, we avoid them having to learn it just ! before their shipping deadlines are missed. This may seem somewhat ruthless: to deny the right to write web Index: wsdl.tex =================================================================== RCS file: /cvsroot/smartfrog/core/extras/alpine/doc/jaxrpc/wsdl.tex,v retrieving revision 1.6 retrieving revision 1.7 diff -C2 -d -r1.6 -r1.7 *** wsdl.tex 28 Oct 2004 15:05:30 -0000 1.6 --- wsdl.tex 29 Oct 2004 16:33:47 -0000 1.7 *************** *** 3,25 **** The role of an Interface Definition Language (IDL) has always been ! twofold. ! The primary output of the process is a definition of \emph{the ! interface} of the remote system. This is ``interface''in the sense of ! \emph{the implementation independent signature of the service}, and does ! not imply that the implementation language needs an explicit notion of ! interfaces. The interface is inherently implementation independent, ! and can be frozen or carefully managed with respects to versioning. ! The act of writing the IDL inherently forces the author to define ! portable datatypes and operations in its restricted language of the ! IDL. This effectively guarantees portability. The implementation ! languages invariably contain constructs which are not portable, but as ! these are excluded from the Interface language, a portability issue is ! the exception, rather than the rule. ! 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 often generated from the implementation classes, using Java's Reflection API. We shall term this process \emph{WSDL-last development}. --- 3,32 ---- The role of an Interface Definition Language (IDL) has always been ! twofold: ! \begin{enumerate} ! \item Firstly, an IDL allows the creation of a definition of \emph{the ! interface} of the remote system, independent of any particular ! implementation, programming language or environment. This is ! ``interface'' in the sense of \emph{the implementation independent ! signature of the service}, and does not imply that an implementation ! 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 ! forces the author to define the system in terms of the portable ! 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 practice for working with JAX-RPC discards all ! these notions. Instead of generating implementation classes from the ! WSDL, the WSDL is often generated from the implementation classes, using Java's Reflection API. We shall term this process \emph{WSDL-last development}. *************** *** 33,37 **** remains constant over time. Every redeployment of the service, every upgrade of the SOAP stack or even the underlying Java runtime may ! change the WSDL. \item --- 40,44 ---- remains constant over time. Every redeployment of the service, every upgrade of the SOAP stack or even the underlying Java runtime may ! change the WSDL, and hence the interface. \item *************** *** 62,66 **** The alternative to WSDL-last development is clearly, \emph{WSDL-first development}. Although this is the better approach from the perspective ! of portability and interface stability, Web Service developers are not pushed in this direction. --- 69,73 ---- The alternative to WSDL-last development is clearly, \emph{WSDL-first development}. Although this is the better approach from the perspective ! of portability and interface stability, web service developers are not pushed in this direction. *************** *** 68,82 **** XML Schema and WSDL. The XSD type system bears minimal resemblence to that of current object oriented languages, and WSDL itself is ! over-verbose and under-readable. As evidence of this, ! consider the broad variety of products that aim to make authoring XSD ! and WSDL documents easier, and recall that such products were never ! necessary 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 sacrifies --- 75,89 ---- XML Schema and WSDL. The XSD type system bears minimal resemblence to that of current object oriented languages, and WSDL itself is ! over-verbose and under-readable. As evidence of this, consider the ! broad variety of products that aim to make authoring XSD and WSDL ! documents easier, and recall that such products were never necessary ! 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 sacrifies |