Enterprise Java Contract-First vs. Contract-Last Web Services
This article will discuss two fundamentally different approaches to development of the enterprise Web Services (WS). Both approaches use SOAP over HTTP protocols and define endpoints and operations via a Web Services Definition Language (WSDL) file. The two methods are contract-first and contract-last. Even though the technology stack can be similar for both methods, they differ in both the methodology and the implementations. The examples will be in Java and cover the most common toolkits such as Spring-WS and Apache Axis, and some automation tools, like JBuilder 2007.
In the contract-first web service, the "contract" (a WSDL definition of operations and endpoints and XML schema of the messages) is created first, without actually writing any service code. In the contract-last web service, existing logic is "exposed" as a web service and the contract is created at the very end. I will present both advantages and disadvantages of each implementation and play the role of devil's advocate when analyzing them.
A Brief History of SOAP
The SOAP acronym originally meant Simple Object Access Protocol, but later it was dropped and now SOAP is an official name by itself. Coincidently, SOAP can also mean SOA Protocol or Service Oriented Architecture Protocol, but no one currently is using this definition. The SOAP-based WS are the bread and butter of some enterprise developers; since the original introduction of the standard, it has changed a lot. The current SOAP specification (XML) defines the envelope structure, encoding rules, and conventions for representing requests and responses.
Modern web-service tools and standards evolved from the initial RPC (Remote Procedure Call) methodology. The idea was that the automated systems will be invoking methods on the remote servers and the communications will be done via the SOAP protocol.* Because web services were also a way to make different legacy systems (developed on diverse platforms and in various languages) talk to each other, initial WS development often exposed existing APIs to be consumed by clients. The communication "contract" that the WS clients needed to uphold was created last, because the business logic code was already written.
* Semantically speaking, modern web services are RPC- and SOAP-based at the same time, but the distinction is Document vs. RPC style. There is also another protocol called REST, but it's beyond the scope of this article.
Tools automating the creation of enterprise web services appeared as early as 2004; I covered one way to expose existing Java code in one of my previous articles, "Developing Web Services with Borland JBuilder Enterprise and BEA WebLogic Server" (01/2006). These tools provided auto-generation of the server code including WSDL and under the hood, compliance with the SOAP and the xml schema—a sort of easy way to SOAP-ify the code. Similarly, tools automating client binding and stubs generation also emerged and eliminated the need for developers to concentrate on the protocols and the low-level plumbing of the services.
The Flow of SOAP Requests and Responses
To better understand both types of the web service methodologies, the communication flow needs to be discussed first. Because the web services XML standards are platform and language indifferent, the translation of parameter values (passed in the request and response) into the host system technology needs to take place on both the client and the server. This includes any complex types, such as custom objects.
For example, if the server is based on C# and the client on Java, C# structures are mapped into XML, which is passed to the client. Subsequently, the client needs to un-wrap XML into the Java object model. This process is called XML marshaling and un-marshaling (also knows as the plumbing of the web services). See Figure 1.
Figure 1: The diagram of XML request marshaling
For this process to work coherently, the set of objects corresponding to the XML elements on both server and clients needs to exist, and the communication XML (payload) needs to be generated dynamically and match the agreed schema format.
In many cases, the client-object model can be automatically generated with the use of the object-XML mapping tool or an IDE. Most popular object-XML mapping (OXM) toolkits for Java are:
These tools can create the XML from the object model, which then can be used by the web service toolkit such as Apache Axis, Xfire, or Spring-WS. (See the References section for more details.)
What Is a Web-Service Contract?
Even though there is no official definition of the web-service contract, the contract is assumed to be the WSDL file. The WSDL describes all operations that the service provides, locations of the end-points (where the service can be invoked), and simple and complex elements that can be passed in requests and responses.
Looking at the contract from the RPC methodology standpoint, the specification of only WS operations (and their signatures) is the contract. Analogous to the Java Interfaces, which define class methods and their signatures and establish object-oriented contract, the web service definition of operations is the contract between the server and the client. Accordingly, as long as the names of the methods and parameters are immutable, the underlining implementation changes do not affect clients. For example, a WSDL can define operations such as "getBalance" or "updateBalance".
Looking at the contract from the message (or document) standpoint, one also can define the contract in terms of the XML schema of the request and response messages. For example, assuming you are developing a service that returns chemical compositions of household products queried by name, you can define a request and response structure in XML, create a validation schema, and support only those elements by the service. The web service server's logic will decide what to do based on the message, and not on the operation invoked.*
* The operation name also can be imbedded in the request message, controlling what is executed on the server or a combination of the actual endpoint operation invoked. SOAP message contents [action] also can be used to define what is perfumed on the server.