Custom marshalling is required for handling non-bean classes as well as types that are incompatible with JSR-172. Custom marshalling can be implemented for both Web Services providers and Web Services clients. Lotus® Expeditor Toolkit does automatically generate custom marshaller code for Web Services providers and for Web Services clients.
When custom marshalling is required, the developer is responsible for completing the code within the generated MarshalFactory
classes on the Web services client and Web services provider. However, the Lotus Expeditor Toolkit Web Services will provide complete custom marshalling code implementation for three non JSR-172 types - Calendar
This section describes the Application Program Interfaces (API) used in the serialization of data structures that cannot be automatically serialized by the OSGi Web Services engine.
The current Web Services engine uses Java reflection and conventions similar to the functionality described in JSR 101 to automatically generate a WSDL to describe services and to serialize data structures for wire transmission. However, in order for the conventions to work, the data structures must have a bean-like structure. Unfortunately, not all data structures have this structure and require specific logic to be serialized and described.
The serialization API has the following features:
- The programmer does not deal with XML processing
- Only the structures that need special processing need custom marshallers
Using the Lotus Expeditor Toolkit, it is easy to write classes that can automatically be serialized. However, when working with legacy classes and classes that contain logic, complications arise. Very few of the standard Java classes lend themselves to automatic serialization. For example, consider the java.util.Properties
class and the java.util.Calendar
class. Neither of these two classes follows the Lotus Expeditor Web Services conventions. Furthermore, there is a standard mapping of the Calendar
class into the XML Schema namespace, so even the namespace mapping conventions do not apply. The serialization API allows data structures to be introspected.
It has three parts:
- Class name to QName mapping
- Enumeration of the members that make up a class
- Extractions of members from an instance of a class
As it is an introspection API, the programmer does not need to be involved in the generation of XML for the WSDL or the SOAP messages. In fact, the actual encoding can be changed since none of the encoding constructs manifest themselves in the API.
Another design feature of the serialization API is that it is only needed for those classes that cannot be processed using the standard conventions. For example, when the marshaller of the Properties
class is written, it is represented as an array of PropertyEntry
objects where PropertyEntry
is a class that has two public members, a key and a value, both of type String. Because PropertyEntry
follows the normal convention for writing serializable data structures it is not necessary to write a custom marshaller for it.
Custom marshallers implement the ClassDescriberMarshalFactory
interface and are registered in the OSGi service registry. The Web services engine dynamically looks up the marshallers and invokes them when needed. This allows for easy deployment of new marshallers and non-disruptive removal of unnecessary marshallers.
Lotus Expeditor for Devices does not support custom marshalling.
Parent topic: Developing Mobile Web Services logic: XPD621