SoapyBeans 2.0

It is clear that the original motivation behind the SoapyBean approach of contract first web service development has become the bedrock of interoperability. However, there have been some advances in technology and standards since that time (late 2003) that allow a sort of "code first" approach to be mixed in to the recipe when it comes to writing updates to existing services.

SoapyBean recap

The core of the SoapyBean recipe was to use the WSDL contract to generate java classes to program with. The only useable web services stack at the time was Apache Axis, however it was clear even at this time that the beans that Axis created were not particularly elegant to work with, an some of the authors opted for using a separate dedicated "XML Binding" tool to create the beans and then pass them to Axis. The package that was chosen for the bean generation was Castor, as it seemed the most mature at the time.

This principle of the separation of the XML Binding from the Web Services stack, allows the business logic that is encoded in the beans to be further separated from the exact details of the web service transport, and was another pioneering aspect for the SoapyBeans approach. Indeed most modern web services stacks do allow a choice of different binding tools to be used. In practice this use of Castor with Axis was not optimal however as a hand coded layer had to be created to translate from the Castor Beans to the Axis beans, as the Axis 1.0 architecture did not make it easy to plug in a different marshalling framework.

Problems with the SoapyBean approach

SoapyBean as we practised it in the early days when the schema and WSDL for services were rapidly changing was useful in ensuring that the details were not hand coded on either side of the web services - and could be rapidly regenerated when the WSDL changes. The landscape changes, however, when the web service WSDL has matured and becomes less rapidly changing, and version 2.0 of the service is released. During the period of version 1.0 of the service the beans will have been stable, and that will be much business logic code written using them - if when version 2.0 of the WSDL is released a completely new set of beans is generated, then all of that business logic code that will need to be altered, which would be very disruptive. I think that a hybrid form of "contract first" and "code first" approach to web services is best in this scenario. The original beans that were generated from the version 1.0 WSDL are retained and manually annotated to allow them to work with the 2.0 WSDL.

To some extent this hybrid approach depends on the 2.0 service being an "extension" of the original 1.0 service where for many of the objects the only change is the change of namespace that is required for validation as the schema changes (as an aside James Clark has some ideas on this topic of schema versioning and validation)

So, in summary, the problems with the original SoapyBean approach

  • Beans regenerated for each change in the schema
  • Beans not directly used in the WS stack

Tools Available today

XML Binding

There is a somewhat out of date (but comprehensive at the time) comparison of XML binding tools at - it does however list the major tools that are still active which are (IMHO)

These toolkits all have the following qualities,

  1. capable of two way transformation XML->Bean and Bean->XML.
  2. fully schema aware and validating.
  3. have code generation from schema.

There is another worth mentioning - JiBX, though this does not seem to have the same level of development effort behind it as those above.

As mentioned above for the "hybrid" beans- the binding framework must be capable of mapping existing beans to a schema. This is necessary to allow for the bulk of business logic (from an existing set of beans) to be reused, rather than having to generate a whole new set of beans when a web service interface undergoes minor additions. This excludes XMLBeans from being suitable, because although it is widely acknowledged as having the best fidelity in XML Schema support, this is at the expense of the generated beans being too closely tied to the schema - (in addition all beans are derived from a common subclass, which makes reuse difficult).

WS Stacks

It is clear that Apache Axis 1 has reached "end of life" as far as Web services stacks are concerned, although it is still in widespread use. The Xfire stack had gained a good reputation as being a relatively compact and easy to use stack, but unfortunately development on this toolkit stopped about a year ago as the developers moved on to work on the (heavier weight) Apache CXF.

A summary of some of the currently available ws stacks is available on the apache WS wiki. The only contender that I think is not listed there is the Spring Web Services package, which whilst relatively new does have the weight of the whole Spring Framework behind it and that has a very good track record in creating an alternative implementation to the standard J2EE framework.

These modern WS stack are much more "adaptable" that Axis 1, in that they allow you to use them in a variety of styles "contract first" or "code first" or crucially the form of hybrid fashion that I am advocating on this page. In addition most of the stacks allow you (or promise to allow you) to plug in your favourite marshalling framework, or deal with the raw XML message.

Coding for an Updated Web Service

Development Sequence

  1. Original WSDL contract created
  2. Beans auto-generated from WSDL
  3. Business logic created with beans
  4. WSDL contract updated
  5. Original beans annotated or a mapping created to fit the new Contact

WSDL Styles

Although the original motivation for SOAP was a form of remote procedure call (RPC) , interoperability (WS-I) studies established that this style of WSDL was open to much misinterpretation on different platforms and as such the RPC style has become deprecated with "Document" style and "Literal" use becoming the established norm. Although "Document Literal" removed interoperability issues, by its nature it made mapping to programming language interfaces less natural as they are typically described as operations with parameters. Microsoft adopted a convention within the "Document Literal" usage that is known as "wrapped" parameters, which allows a more natural mapping onto programming language interfaces. This "wrapped" style for parameters is supported within newer Java frameworks also (e.g. JSR 181).

Tool combinations that work.

Because the more modern toolsets make use of Java 1.5 annotations both for XML Binding (JSR 222: JavaTM Architecture for XML Binding (JAXB) 2.0 and JSR 181: Web Services Metadata for the JavaTM Platform, it makes supporting Java 1.4 very difficult. Astrogrid is still committed to supporting Java 1.4 on the client side, which means that there is only one tool combination that I can see that fulfils all of the requirements

  • Xfire
  • Castor

Xfire has an implementation of JSR 181 that makes use of Apache commons attributes that will work under java 1.4.

-- PaulHarrison - 25 Jan 2008

Topic revision: r3 - 2008-01-25 - 13:35:14 - PaulHarrison
AstroGrid Service Click here for the
AstroGrid Service Web
This is the AstroGrid
Development Wiki

This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback