Creating a Web service client API for WebSphere Commerce

For each component that is to consume external Web services, a client API is required to construct different request messages and then call the invocation service. The client API is essentially a Java utility class that contains construction code to create the appropriate message and send it. No business logic is performed in the client API.

Using the client API to construct the message simplifies the business logic by providing a programming friendly interface. This allows other Java applications to use the same code to make remote calls as long as invocation service does not depend on the WebSphere Commerce runtime environment. The following code snippet demonstrates a simple example of CheckInventory where the request specifies the fulfillment center and product SKU and is expecting inventory information to be returned.

InventoryType inventory = InventoryClientFacadeImpl.check("SKU","FFC");

Although the preceding snippet is very simplistic, the client API can also provide more complex method signatures along with a set of Java objects. These can be used to create the underlying XML document that will be used to communicate with the target component.

A client API consists of the following assets:

MyCompanyMyServiceNameFacadeClient
- Uses MyCompanyMyServiceNameInvocationServiceObjectImpl to convert the request SDO to the request XML.
- Instructs the WebSphere Commerce messaging system to transmit the message.
- Uses MyCompanyMyServiceNameConfirmationInvocationServiceObjectImpl to convert the response XML to the response SDO.
MyCompanyMyServiceNameInvocationServiceObjectImpl
- Converts the request SDO to XML.
MyCompanyMyServiceNameConfirmationInvocationServiceObjectImpl
- Converts the response XML to the Confirmation SDO.

Tip: Creating a client API is also covered as part of the overall scenario in Tutorial: Creating an outbound web service client. This tutorial is highly recommended for developers working with outbound Web services.

Procedure

Ensure that the message format (XSD schema) is defined and imported into the WebServicesRouter project in WebSphere Commerce Developer.
Generate the SDOs. If you are extending the OAGIS 9 schema, or the WebSphere Commerce Foundation schema, the generated EMF models are located in the root of the WebServicesRouter project. You can use these models.
Create two new classes that extend the AbstractSDOInvocationServiceObjectImpl class. These objects are instances of InvocationServiceObject and transform the XML Java objects to XML byte arrays. To create the two classes:
1. Right-click on your customization package.
2. Select New > Class.
  1. In the Name field, type the name of the class, for example MyCompanyMyServiceNameInvocationServiceObjectImpl. This class will convert the request SDO to XML.
  2. Next to the Superclass field, click Browse.
  3. Enter AbstractSDOInvocationServiceObjectImpl in the Choose a type input field.
  4. Click OK.
  5. Click Finish.
3. Repeat step b once more, to create a second class, this time naming it MyCompanyMyServiceNameConfirmationInvocationServiceObjectImpl. This class will convert the response XML to the confirmation SDO.

On both of the InvocationServiceObject classes, implement the methods getResourceFactory() and getDocumentRoot() method to return the generated SDO Resource Factory implementation and DocumentRoot. For example:

/**
* Returns the resource factory of the
*/
protected Factory getResourceFactory() {
        return new OrderResourceFactoryImpl();
}

/**
* Returns the document root associated with the data object and
sets the data object inside the document root.
*/
protected Object getDocumentRoot() {
        DocumentRoot documentRoot = OrderFactory.eINSTANCE.createDocumentRoot();
        documentRoot.setGetOrder((GetOrderType)getDataObject());
        return documentRoot;
}

Create the MyCompanyMyServiceNameFacadeClient class to transmit the request message.
1. Right-click your customization package.
2. Select New > Class.
3. In the Name field, type: MyCompanyMyServiceNameFacadeClient
4. Click Finish.

In the facade client API, implement methods to create the outbound message. Have these methods delegate to a protected method to send the information. The send method should accept a Service Data Object (SDO) and return an output SDO object. In the following example, the For example:


protected ShowInventoryType send(GetInventoryType getInventory)
{
	InvocationServiceObject requestDataObject = new GetInventoryInvocationServiceObject();
	requestDataObject.setDataObject(getInventory);
        
	InvocationServiceObject responseDataObject = new ShowInventoryInvocationServiceObject();

	InvocationService service = new InvocationService("com.ibm.commerce.inventory", "GetInventory");
	service.invoke(requestDataObject, responseDataObject);

	return (ShowInventoryType) responseDataObject.getDataObject();
}

Create a new message type for the component ID used to create an instance of the invocation service object, for example com.ibm.commerce.inventory in the preceding code example. Add a row into MSGTYPES table assign a msgtype_id. Use a message type ID number above 1000. For example:
```
insert into MSGTYPES (MSGTYPE_ID, MSGTDIR, NAME, VIEWNAME,
DESCRIPTION) 
        VALUES (1001, 1, 'com.ibm.commerce.inventory' , '',
'Inventory Component' );
```
Assign a message type to a transport method for a site or store.