Thanks for the post.

The JISC emphasis derives from the work on e-Framework definitions that includes a section on Principle and Practices in Designing Services:

This is in alignment with most work that I have seen on SOA - promoting the exchange of documents between services rather than the passing of parameters using remote procedure calls.

So, you are right, - this would be a good time to review your use of RPC style services, and look at a document centric approach as an alternative.

Broadly speaking there are the main two approaches to the document approach - calling a URL address and returning a XML document rather than HTML (the REST approach) or invoking a SOAP based service and returning the XML document as a payload wrapped in the SOAP envellope. As you know, the REST approach is viewed as "simpler", whilst the SOAP, although viewed as having more "overhead"  includes implicit self-description of the service itself (through WSDL), implicit self-description of the document payload (through XML schema) and implicit support for other WS technologies (such as BPEL, security, transactions and so on).

If you decide to go with the SOAP approach,  it is recommended to use a particular design pattern called "document literal wrapped" style service - so this is the phrase to look out for on your web search - there used to be some great articles on the IBM developer works (if you are using Java). It is also very easy to implement in .NET if you are using MS technologies.

In Icodeon's experience, the steps requried for converting RPC to  "document literal wrapped" style services are as follows:

1. Design the documents that will be passed between services using XML schema - write an XSD. The XSD will become the "foundation stone" for all you do. Probably the input document (which was the parameter arguments in the RPC call) will be very simple, so focus on the schema XSD for the document that will be returned. (Its possible to "reuse" this document for the input anyway - can explain later).

2. Design the WSDL by hand, do not auto generate from code. The "document literal wrapped" style service has a particular design pattern that needs to be followed for WSDL design. The WSDL references the XSDs from step 1 to describe the documents it will accept as input requests or return as outout responses.

3. Now that you have document schema (XSD) and service interface description (WSDL)  - auto generate code from these documents. The XSDs will give you an object model, and the WSDL will give you the service interface. There are good code generators for for XSDs and WSDLs in Java and in .NET.

4. Hand code the business logic now that you have the classes for service interface and object model entities. If you find that the business logic cannot be supported with the interface and model as is, go back to the XSD and WSDL, change those, regenerate the service interface and object model classes, and then re-code the the business logic.

Best references that Icodeon have found for the document literal wrapped approach are:

IBM Developer Works - for example here. 

XML Schema by Eric van der Vlist (O'R'eilly)

Building Web Services with Java (Developers Library isbn 0 672 32641 8) 

Service Oriented Architecture by Thomas Erl (isbn 0 13 185858 0)

Comments ? 

Hi Warwick

Thanks for such a prompt and really informative response to my query. This looks extremely helpful, particularly the step by step guide you gave for re-thinking an RPC-style service as a document style one.

Incidentally, we are using PHP5 as our development language, so we'll need to dig around to find the implications of this.

I'll alert the developers to this thread you've started, and hope that we can all participate in it.

Best wishes

Carol Shergold
XMarks project, University of Sussex

Good point re: PHP5 - Icodeon have only looked at this RPC --> Document Literal Wrapped with the Java and the .NET technologies, so not sure how this would port to PHP5. You would need to check out:

XSD --> PHP generator (equivalent in .NET is xsd.exe)

WSDL --> PHP generator (equivalent in .NET is wsdl.exe)

and then confirm that the WSDL --> PHP generator supports the document literal wrapped style.

Comments ?