Overview

The Request-Response data handler is a data-conversion module whose primary role is to provide support for request and response data that is in different formats; that is, it enables a calling context (such as an adapter or the Server Access Interface) to call two different data handlers:

With other data handlers, the calling contexts assumes that the data has the same format when sent to and received from the application or access client; therefore, the calling context is configured to call a single data handler to handle the conversion of both request and response business objects.

However, you might have a legacy application that accepts XML as an input and returns some custom-formatted document as output. Existing data handlers cannot easily handle this situation. However, you can configure the adapter that communicates with this legacy application to call the Request-Response data handler. This data handler can be configured to call separate data handlers for input and output:

In request processing when the integration broker sends a request to this adapter, the adapter calls the Request-Response data handler, sending it the request business object. The Request-Response data handler checks its configuration to determine that it needs to invoke the XML data handler to convert this business object to an XML document. Once this business object has been converted, the Request-Response data handler returns XML document to the adapter, which in turn routes it to the legacy application.

Figure 33 shows an example of the business-object-to-string conversion as performed by the Request-Response data handler.

Figure 33. Business-object-to-string conversion with the Request-Response data handler

The adapter might later receive a response from the legacy application. This response would be in the legacy application's custom format. The adapter again calls the Request-Response data handler, sending it the response data. The Request-Response data handler checks its configuration to determine that it needs to invoke the custom data handler to convert this response data into a business object. Once this data has been converted, the Request-Response data handler returns business object to the adapter, which in turn routes it to the integration broker.

The Request-Response data handler is also to enable the ICS integration broker to post one business object type to a collaboration port and receive one or more different business objects in return. For example, an access client can send a customer object to a collaboration and receive an array of pending order objects for that customer in return.

The Request-Response data handler supports serialized data with the text/requestresponse MIME type. That serialized data may be either text or binary data. However, the default top-level meta-objects (MO_DataHandler_Default or MO_Server_DataHandler) do not support the text/requestresponse MIME type. Therefore, for an access client or connector to be able to call the Request-Response data handler, you must modify the appropriate top-level meta-object to support the text/requestresponse MIME type. For more information, see Configuring the top-level meta-object.

This overview provides the following information about the Request-Response data handler:

Request-Response data-handler components

A data handler can receive serialized data in one of two ways:

The Request-Response data handler uses a name handler to create the name of the top-level business object it creates. Figure 34 illustrates the Request-Response data handler components and their relationship to one another.

Figure 34. Request-Response data-handler components

The data handler invokes an instance of the name handler based on the value of the NameHandlerClass attribute in the Request-Response data handler child meta-object:

The NameHandlerClass attribute in the version of the meta-object delivered with the product is blank. Therefore, the Request-Response name handler uses its default name handler.

Features of the Request-Response data handler

The Request-Response data handler is useful in both of the following cases:

Support for event processing

Event processing involves the notification of the integration broker that some event, which indicates a change to application business entities, has occurred. In event notification, the calling context of a data handler calls a data handler: the data handler to convert the serialized data to a business object (which is then routed to the integration broker). This string-to-business-object conversion is performed by the request data handler, because this data handler handles conversion from the request (input) format to a business object.

Event processing can be either synchronous or asynchronous. However, because in asynchronous event processing the adapter ((in particular, the connector component of the adapter) does not wait for a response from the integration broker , as follows:

Note:
For more information on the calling contexts of data handlers, see Contexts for calling data handlers.

For example, the following steps describe synchronous event processing. They describe how the Request-Response data handler allows the Server Access Interface (within ICS) to send data in one format (its request format) to the ICS and to receive a different form of data (its response format) in return. This allows an access client to complete a scenario such as sending a customer XML document and receiving an XML document containing pending orders for that customer in return.

  1. An access client sends an event (as data in the request format) to be executed by a collaboration within ICS.
  2. ICS creates a new instance of the Request-Response data handler and passes it request-format data.
  3. The Request-Response data handler calls its configured request data handler, which converts the request-format data to a business object.

    The Request-Response data handler uses its getBO() method to handle the serialized data it receives. It invokes the request data handler on this serialized data if either of the following conditions are true:

    In either of these cases, the Request-Response data handler creates an instance of the request data handler and uses this data handler to convert the request-format data to a request business object. To the request data handler, the Request-Response data handler passes the request-format data. The request data handler returns the corresponding request business object.

  4. The Request-Response data handler adds the request business object as a child of the top-level business object, as follows:
  5. The Request-Response data handler returns the top-level business object synchronously to the collaboration (which the access client has specified).
  6. The collaboration receives the top-level business object, extracts the child object (which contains the request business object) and executes some business process.
  7. The collaboration creates a new response business object and adds it to the top-level business object, then returns successfully.

    This top-level business object is the one that the collaboration has received from the Request-Response data handler. Once the collaboration has updated this business object, the business object contains both the original request business object and the newly created response business object.

  8. ICS passes the modified top-level business object to the Request-Response data handler.
  9. The Request-Response data handler calls its configured response data handler to convert the response business object to response-format data.

    The Request-Response data handler uses its getStringFromBO() method to handle the top-level business object it receives. If more than one child business object in the top-level business object is populated, the data handler assumes that the top-level business object contains both the original request business object and its response business object and consequently that the response business object must be converted. Therefore, it creates an instance of the response data handler to process the last defined child business object within the top-level business object as the response business object.

    Note:
    If only one child business object within the top-level business object that getStringFromBO() received is populated, the data handler assumes that the child object represents a new request. Therefore, it creates an instance of the request data handler to convert the request business object to serialized data (in the request format). For more information, see Support for request processing.
  10. The Request-Response data handler returns the response-format data to its caller (Server Access Framework in ICS).
  11. ICS returns the response-format data (which is based on the response business object) to the access client.

A connector can also perform synchronous event processing with the executeCollaboration() method. Generally, however, it performs asynchronous event processing using an event detection mechanism such as polling.

Support for request processing

Request processing involves the receipt of requests from the integration broker and to initiate the appropriate changes in the application business entities. Unlike event processing, which can be initiated by either an access client (synchronously) or a connector (asynchronously), request processing is initiated by an integration broker and involves communication with connectors only (not access clients).

In request processing, the calling context of a data handler calls a data handler to convert the serialized data to a business object (which is then routed to the integration broker). This string-to-business-object conversion

For example, the following steps describe request processing that involves a IBM WebSphere InterChange Server integration broker and a technology adapter. This technology adapter is configured to use the Request-Response data handler to handle request and response data. In this case, the request data is in one format and the response data in another.

  1. The collaboration creates a new instance of the top-level business object and adds the request business object as a child.
  2. The collaboration sends a request (in the form of the top-level business object) to the technology connector, which in turn passes the top-level business object to the Request-Response data handler.
  3. The Request-Response data handler calls its configured request data handler to convert the request business object to request-format data.

    The Request-Response data handler uses its getStringFromBO() method to handle the top-level business object it receives. If only one child business object within the top-level business object is populated, the Request-Response data handler assumes that the child object represents a new request. Therefore, it creates an instance of the request data handler to convert the request business object to serialized data (in the request format).

    Note:
    If more than one child business object in the top-level business object that getStringFromBO() received is populated, the data handler assumes that the top-level business object contains both the original request business object and its response business object and consequently that the response business object must be converted. Therefore, it creates an instance of the response data handler to process the last defined child business object within the top-level business object as the response business object. For more information, see Support for event processing.
  4. The technology connector sends the request-format data to the application.
  5. The application performs some tasks and returns response-format data to the technology connector.
  6. The technology connector passes both the original top-level business object and the response-format data to the Request-Response data handler.
  7. The Request-Response data handler calls its configured response data handler to convert the response-format data to a business object.

    The Request-Response data handler uses its getBO() method to handle the top-level business object and the serialized data it receives. If any of the child business objects within the top-level business object are populated, the Request-Response data handler assumes that the child object represents the original request and consequently that the serialized data it received is in the response format. Therefore, it creates an instance of the response data handler to convert the serialized data to a response business object.

    Note:
    If all child business objects in the top-level business object that getBO() receives contain a value of CxIgnore (indicating that they are empty), the data handler assumes that the serialized data represents is a new request and creates an instance of the request data handler to process the data. For more information, see Support for event processing.
  8. The Request-Response data handler adds this response business object as a child of the top-level business object and then returns this top-level business object to its caller (the technology connector).
  9. The technology connector returns the updated top-level business object to the collaboration.
  10. The collaboration receives the top-level business object and incorporates the content of its response business object into the business process.

Processing request and response business objects

Use of the Request-Response data handler to convert a request business object to its appropriate request format, or to convert data in a response format to a response business object requires that the steps outlined in Table 50 occur.

Table 50. Using the Request-Response data handler

Step For more information
1. Business object definitions that describe the business-object structure must exist and be available to the Request-Response data handler (and its component data handlers) when it executes. Requirements for business object definitions
2. The Request-Response data handler must be configured for your environment. Configuring the Request-Response data handler
3. The Request-Response data handler must be called from a calling context (connector or access client) to perform the appropriate data operation:
a) Data operation: Receive the request from the component that initiates this request and convert it to the appropriate format. Converting business objects with the request data handler
b) Data operation: Receive the response from the component that responds to the request and convert it to the appropriate format. Converting business objects with the response data handler

Copyright IBM Corp. 1997, 2003