How the connector works

The following sections describe how the connector processes business objects, how meta-objects are used for configuration, and how the connector handles event notification.

Business object processing

The connector uses request/response operations to pass data between it and a URL. The connector receives business object requests from an integration broker and converts the requests into XML streams. The request stream is passed to a URL by using the POST method, and a response stream is returned that may or may not have similar content. The response stream is converted into a response business object and returned with the original top-level business object to the integration broker. Note that the type of business object request can differ from that of the business object response.

The complete request-response cycle is illustrated in Figure 2.

Figure 2. Business object event processing

Request

When the connector receives a business object request from an integration broker, it must convert it into a request stream that can be passed by using the appropriate protocol. The protocol handler and the XML data handler are used to convert and send a request business object to a URL. Figure 3 illustrates the request process.

Figure 3. Request processing

Specifically, when the connector receives a top-level business object from the integration broker, the following process flow occurs:

  1. The connector calls getAttrValue ("URL") and retrieves the URL. It also calls getAttrValue ("MimeType") and getAttrValue ("BOPrefix") to retrieve the MimeType and BOPrefix attributes values from the business object.
  2. The connector extracts the request business object from the top-level business object.
  3. The connector calls the appropriate protocol handler (HTTP or HTTPS) based on the protocol specified in the URL field of the top-level business object, and the protocol handler package name specified.
  4. The protocol handler calls the appropriate data handler based on the MimeType and BOPrefix attributes of the top-level business object (as configured in the top-level meta-object).
  5. The data handler converts the business object into a request stream and then passes it back to the protocol handler.
  6. The protocol handler sends the request stream to the destination URL specified in the top-level business object or passes the return code.

Response

If you are using a synchronous protocol handler, then when the response business object is returned from a URL, it is returned in the form of a response stream. If you are using an asynchronous protocol handler, then return code is simply passed back. The response processing is similar to the request processing, except the response stream must be translated back into a business object.

Note:
The response stream may not always be represented by the same business object type as the request stream.

Figure 4 illustrates the process flow of the response business object returning to the connector.

Figure 4. Process flow of data returning from a URL

Specifically, when the protocol handler receives a response stream from a URL, the following process flow occurs if the MIME type is text/xml:

  1. The protocol handler calls the getContentType ()method to retrieve the MIME type value to determine which data handler to use.
  2. The protocol handler calls the DataHandler class to create an instance of the XML data handler.

    Note that the data format in the response stream can be different from the data format in the original request business object.

  3. The protocol handler converts the response stream into a string, which the protocol handler passes to the XML data handler.
  4. The XML data handler obtains the business object name based on the message content and extracts the data from the request stream (XML document) into a business object.
  5. The XML data handler passes the completed request business object to the protocol handler.
  6. The protocol handler passes the request business object to the connector, which adds it to the original top-level business object.
  7. The connector passes the original top-level business object containing the request business object back to the integration broker.

Event notification

For event notification, the connector uses business objects to retrieve events from a URL. The connector polls a URL by sending a request XML document that is returned as a response XML document. The response contains child business objects that the connector passes to the integration broker as events. Each child business object is processed as a single event. The asynchronous protocol handler does not support event notification.

Note:
Poll for events processing is the same as business object request processing except that there is an additional step to extract event objects from the response business object and send them to the integration broker.

An event notification business object follows the same business object processing operations as the request and response business objects of an XML business object. All unsubscribed events are archived to a file in the standard business object dump format.

To enable event notification, you need to define event notification business objects and set up your URL (such as a Web servlet or cgi-bin script) to handle these business objects. The connector uses the POST method to send an XML event request document as a stream to the URL. The URL should read the XML document as a stream from STDIN and write an XML document which contains one or more event objects as a stream to STDOUT.

Figure 5 illustrates the basic process of event notification.

Figure 5. Event notification process

For more information on defining business objects, see Developing business objects for the connector

Processing locale-dependent data

The connector has been internationalized so that it can support double-byte character sets, and deliver message text in the specified language. When the connector transfers data from a location that uses one character code to a location that uses a different code set, it performs character conversion to preserve the meaning of the data. The Java runtime environment within the Java Virtual Machine (JVM) represents data in the Unicode character code set. Unicode contains encodings for characters in most known character code sets (both single-byte and multibyte). Most components in the WebSphere business integration system are written in Java. Therefore, when data is transferred between most integration components, there is no need for character conversion. To log error and informational messages in the appropriate language and for the appropriate country or territory, configure the Locale standard configuration property for your environment. For more information on configuration properties, See Appendix A, Standard configuration properties for connectors.

Copyright IBM Corp. 2003