Comparison of the IBM Content Manager web service interfaces

IBM® Content Manager offers the same web service functionality through two different interfaces: CMBGenericWebService and CMWebService according to the different requirements for integrating IBM Content Manager web services into customer applications.

The CMWebService interface defines all its operations in detail in the WSDL. The WSDL references XML schemas that define the request and response messages for each operation and the constructing elements for these messages. When the WSDL and XML schemas are translated into proxy classes of a particular programming environment, the proxy classes can provide APIs to help build request messages and decompose the response messages for client applications. Therefore, the client developers do not need to assemble or disassemble the XML messages manually. The proxy class APIs are also strongly typed, which prevents the errors that can occur when assembling or disassembling the XML message manually. These proxy classes are referred to as the generator style of a web services interface.

Optionally, you can use XML schemas for specified IBM Content Manager item types to generate client proxy classes. These client proxy class APIs are detailed so that the client application developers do not need to know the syntax of the XML messages. Developers can follow the object-oriented programming guidelines to use these proxy classes to assemble request XML messages and disassemble response XML messages, which facilitates client application development. However, if the item types are changed, added, or removed from the definition, the developers must obtain the new XML schema for the item types, regenerate the proxy classes, and recompile the application with the new classes.

If the XML schema for the specific item types are not included when generating the proxy classes with the CMWebServices WSDL, the client application developers must write their own code to serialize the XML elements for the item types in the request messages and de-serialize the XML elements for the item types in the response messages. By not including the specific item types in the proxy classes, client applications have the flexibility to work with any item types.

The WSDL of the CMBGenericWebServices interface defines the generic style of web service interfaces. It does not define the web service operations and the request and response message. Instead, it provides a generic API so that any form of request XML messages can be sent to the IBM Content Manager web service server, and it can receive any form of response XML messages from the server. This generic, or late-binding, style of web service interfaces grants the IBM Content Manager web service server the ability to add, change, or remove the web service operations and their parameters in the future, but does not force the client application developers to use the new WSDL and recompile their application.

However, because of this flexibility of the CMBGenericWebServices interface, client application developers must have full knowledge of the web service operations and the request and response XML messages. Developers must assemble or disassemble the message manually. Developers can use the following references: the CMBGenericWebServices WSDL, the XML schema for messages defined in cmbmessages.xsd, the XML schema for elements defined in cmdatamodel.xsd for constructing item type XMLs (both XML schema definition files are inIBMCMROOT/config, where IBMCMROOT is the directory in which IBM Content Manager is installed), and the web services samples that are included with IBM Content Manager.

In terms of SOAP message style, both CMWebService and CMBGenericWebService use document/literal, which means the request and the response are document-style messages and are not encoded.

For a particular application, consider the SOAP attachment capacity when choosing the web service endpoint.

CMWebServices supports the following attachment types:

• Message Transmission Optimization Mechanism (MTOM)
• Direct Internet Message Encapsulation (DIME)
• Multipurpose Internet Mail Extensions (MIME).

At run time, only one of the three SOAP attachment formats is enabled by configuration. The attachment type supported by CMBGenericWebServices is MIME.

Many of the tools for web services development generate client code, sometimes called proxy classes, to represent the web service interface and operations supported by the web service. This allows such details as building SOAP messages to be hidden so that the client only needs to build and send requests to a local proxy version of the web service.

The IBM Content Manager web service server responds to any request messages that comply with the interfaces. Response messages are also based on the interfaces. Client application developers decide how to generate and understand the messages, including choosing which web service endpoints to visit and what development environment and programming language to use. The following list shows which client development tools are supported by each attachment type:

• MTOM: Microsoft .NET Framework SDK version 4.6 and Web Services Enhancements (WSE) SDK version 3.0
• DIME: Microsoft .NET Framework SDK version 1.1 and Web Services Enhancements (WSE) SDK version 1.0 sp1
• MIME: IBM WebSphere® client tools

Among non-IBM web services software, Apache Axis supports both DIME and MIME and Apache Axis2 supports both MIME and MTOM. Therefore, depending on your client development environment, you must choose the matching web service endpoint (CMWebService or CMBGenericWebService) to connect to based on the SOAP message capacity. (Content Manager Enterprise Edition V8.7 has deprecated support for web services applications that use Apache Axis 1.4.)

To see the code differences between the two interfaces, see the sample programs that are included with IBM Content Manager.