A TRUE benefit of using web services document style messaging over remote procedure call (RPC) style
Before reading this post, if you are not familiar with web services check out
http://www.ibm.com/developerworks/webservices/library/ws-docstyle.html
or
http://www.java-tips.org/java-ee-tips/enterprise-java-beans/document-handling-in-web-services-applica.html
or even
http://en.wikipedia.org/wiki/Web_service
The top three benefits of document over RPC are validation, asynchronous processing, and a less rigid contract between the client and the server. The first two benefits are more of a coding convenience than an added benefit and don’t really impress me. To me the third benefit is really the power of document style. But until my current project, I have yet to have a situation where I was able to utilize this powerful benefit. I want to explain my case for why a less rigid contract is the only powerful benefit and then I want to share with you a situation where documents style messaging is really the only option. (Note: there is this idea of using document style to save state, but my disagreement with this idea will soon become a completely separate post on Make Great Software. For right now, just trust me. For most systems, don’t try to save state through web services.)
Validation in XML This benefit uses the power of XML. Document style uses the power of XML to validate the message where as with RPC the code behind the operation does the validating. So either the code does the validating of the XML. No big deal. (except that it allows you to have a less rigid contract, but that’s more than just validation)
Asynchronous Processing Ok another feature of document style, but I can name many other ways to get my RPC style call to be asynchronous for the client. Again, no big deal.
A Less Rigid Contract Now this benefit is cool. The idea here is when a client uses an RPC style web service; the client application relies on that specific method signature. Any change by the client of the parameters will break the client application. In other words, the interface cannot ever change unless it changes on the client as well. With documents style, this isn’t the case. Changes to the server interface that in RPC would change the interface, in document style only change the schema and therefore will not break the calling application.
So if you are like me, the last benefit sounds really cool, but where would you need it. I mean, I have used documents style in the past, but only to help future efforts that might need to make changes to the interface. …well, actually I used it only for the sake of using a documents style, RPC would have done the trick just as well. Besides, I’m really not quite sure how I could later change the schema without hurting any client applications. If they are relying on some data being in the Document message and I remove that data from the schema, won’t this cause them to have errors? This whole idea of using document for “great” benefits over RPC has really escaped me. …until now.
My current project is enhancing a really cool application for the Air Force Research Lab. The need is for the system to be able to act as a standalone application (i.e. the client and the server are all on the same machine acting as a single application) and also act as a service and a client. (i.e. the client will be located on one machine and the server be on another machine handling service requests from whom ever is calling it).
The reason document style is needed for this design is because of the services that the server is exposing to the client. There is a ton of them (for this post we have N of them). Each service has its own set of parameters. In order to handle direct and web service mode, at first we thought we needed N times 2 handlers for each service (one to handle calls to the service directly and one to handle the call through web services). (See Diagram 1 below) Instead, if we use document style messaging for the web services, we can define the parameters for each service in the schema. We can have 1 handler for all calls thought web services and one handler for all calls to the services directly (See Diagram 2 below).
Diagram 1 A quickly made diagram of the system using RPC style messages
Diagram 2 A quickly made diagram of the system using document style messages
Before, the reason we needed N web service handlers was different parameters for each service. With document style, the parameters are defined in the schemas that define the structure of the XML document. The service proxies are needed to gather the required data for each service. Once the proxies have gathered the data, they can pass on the single parameter to the web service handler. The web service handler now only needs to make a single generic call that passes in the single parameter.
This design is simpler and contains fewer dependencies. It should also cut down on the time needed to build the system. I hope this now gives you a concrete real world use of web service document style messaging.
