Tuesday, August 21, 2007

How to make a JAX-WS client reuse existing classes for data binding (1).

This tutorial describes how one can configure a JAX-WS client to reuse already existing classes for web service data binding, i.e. as a java representation of in/out parameters communicated with a web service via XML.

There exists followings use cases for which you may need this ability:
  • Reuse the same parameter/result classes on the server and client. You can introduce a common javabean package for representing entities in both client and server components. Additionally you can implement some methods on the top of the javabeans. The functionality will be in turn available on both server and client side. This approach keeps general web service interoperability based on WSDL contract for 3'rd party clients, while your own clients can benefit from functional code reuse.
  • Reuse the same binding classes among more clients. If yours clients serve the same ws endpoint, or your new client serves a superset of an existing one, then you can consider introducing a common package for data representation and reuse it for data binding from all your clients.
  • You have been given classes for data presentation on your client. In that case you can benefit from the JAX-WS toolkit capabilities to provide xml <->java binding right to designated classes, instead of manually coding some adaptors.

Requirements: This tutorial assumes that you use
JAX-WS 2.1 and JAXB 2.1 compliant toolkits. Part of this scenario relies on proprietary tools and features of the reference implementation provided by java-net community.

The standard way to create a JAX-WS client is to get the WSDL description of a web service and let the JAX-WS toolkit automatically generate web service interface and classes for its local proxy which provides communication with remote web service endpoint. The JAX-WS simultaneously generates classes for data binding, e.g. classes that represents data which are sent to and received from a web service in an XML form. All those classes are generated according standardized procedure described in the JAX-WS 2.1 specification, chapter WSDL 1.1 to Java Mapping (packaging, naming, structure). The JAX-WS specification in turn defers data binding to the JAXB specification and its default rules for java class generation from XML schema. The standard procedure how classes are generated can be customized. In the following text I describe how to create and use a particular customization which tells JAX-WS to use existing classes for XML data presentation instead of generating new ones.

The exact way how the customization works is described in the JAX-WS 2.1 specification, chapter Customization. Put succinctly the customization is based on binding declarations provided to the JAX-WS toolkit at the time of client generation. Binding declarations are expressed in XML based binding language. They can be directly included in the WSDL document which java mapping they customize or reside in an external file that points to the related WSDL file. Binding customization can include any JAXB 2.1 binding declaration in order to customize data binding.