Create 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.

Use the client API to construct the message simplifies the business logic by providing a programming friendly interface. It also promotes portability because the client API can be deployed independently of WebSphere Commerce. 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:

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

  1. Ensure that the message format (XSD schema) is defined and imported into the WebServicesRouter project in WebSphere Commerce Developer.

  2. Generate the SDOs, follow the directions provided in steps 0 to 2 in the topic Generating an EMF Model using XML Schema (XSD). 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. Use these models.

  3. Create two new classes that extend the AbstractSDOInvocationServiceObjectImpl class. These objects are instances of InvocationServiceObject and handle the XML marshalling and unmarshalling of the Java objects into an XML byte array. 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.

  4. 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;
}

  5. Create the MyCompanyMyServiceNameFacadeClient class to transmit the request message.

    1. Right-click on your customization package.

    2. Select New > Class.

    3. In the Name field, type: MyCompanyMyServiceNameFacadeClient

    4. Click Finish.

  6. 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();
}

  7. 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' );

  8. Assign a message type to a transport method for a site or store.

Related concepts

Understanding the WebSphere Commerce Web service framework

WebSphere Commerce Web services with JSP pages

Related tasks

Customizing the Web service client invocation XML file

Customizing existing outbound service requests

Enabling WebSphere Commerce as a service consumer

Related reference

Additional information about Web services