Processing flow

As described in Connector architecture, the connector, the runtime component of the adapter for TCP/IP, is designed as a general purpose conduit to route data transmitted directly over TCP/IP networks under well-known protocols, such as the HL7 protocol in the health care industry, into and out of the WebSphere business integration system.

The nature of the WebSphere business integration business object in this flow is completely dependent on the data handler, a data transformation plug-in that the connector calls based on settings in the connector configuration file. The data handler, and not the adapter itself, translates the messages to and from the appropriate WebSphere business integration business object form.

PIMO framework processing

The PIMO framework is used in both service call request processing and event processing.

The PIMO framework provides an abstract mechanism for performing certain kinds of object manipulation inside the connector. In the adapter for TCP/IP, this mechanism is used to provide pre- and post-processing of message data.

Overview

The PIMO framework uses a set of specially designed meta-objects to do its work. At the top of the adapter's PIMO hierarchy is the BIA_MO_Tcpip_MapSubscriptions object. Figure 3 shows a sample BIA_MO_Tcpip_MapSubscriptions meta-object. Figure 26 shows what this object looks like in the Business Object Designer.

This object designates both the inbound (event pre-processing) and outbound (service call request post-processing) paths that data will take. It contains two objects:

Each object contains a reference to one or more PIMO maps.

Figure 3. BIA_MO_Tcpip_MapSubscriptions object
An illustration of BIA_MO_Tcpip_MapSubscriptions, showing three Inbound maps and two Outbound maps.

PIMO objects consist of three basic attributes: Port, Declaration, and Action.

Figure 4 shows the structure of a BIA_MO_Tcpip_MapSubscriptions meta-object that contains three inbound maps and two outbound maps.

Figure 4. PIMO map structure
An illustration of BIA_MO_Tcpip_MapSubscriptions, with the maps expanded.
Port

Each Port is made up of two attributes:

These attributes indicate the expected type of the source object (for example, a BIA_InputMessage object, which is the internal wrapper object for event processing) and the destination object (for example, a BIA_LLPMessage List object).

Note: The BIA_LLPMessageList map is a sample map provided by default with the connector; however, the adapter for TCP/IP can be used for more than just HL7 message processing. Customize the provided sample maps to meet the needs of your industry.

Figure 5 shows two input maps chained together, the first separating multiple messages into single messages, and the second stripping away the LLP information from the actual HL7 message.

Separating the process into multiple steps can produce more complex types of processing. If chained maps are used, it is essential that the oPort type of the first step be exactly the same as the iPort type of the second step, and so forth.

Figure 5. iPort and oPort declarations
An illustration of BIA_MO_Tcpip_MapSubscriptions, showing that the oPort of BIA_InputMessage_CheckComplete is the iPort of BIA_InputMessage.
Declaration

The declaration attribute is optional. It contains names for temporary variables to be used during processing.

Action

Each Action attribute consists of one or more defined actions. The Application Specific Information (ASI) for each defined action provides the information the PIMO needs to invoke the message handler, a native Java class designed to perform the actual data transform that is required. The message handler provides methods for parsing (unwrapping) or constructing (wrapping) the TCP/IP messages based on a certain protocol.

An example ASI follows:

type=nativeStatic; class=com.ibm.adapters.tcpip.messagehandlers.LLPMessagingProtocoHandler; method=parseInputMessageToLLPMessages; target=contentText;IPort;Oport

The ASI is described in PIMO framework meta-objects. This section provides a general description of the actions.

The method at the heart of this set, parseInputMessageToLLPMessages, separates the LLP-specific wrapper data and then returns a list that stores the individual parts of the LLPMessage (the header, the message itself, and the trailer) so that the message (as a BIA_ContentBO) can be handed off to the data handler. A set of these HL7 message handlers is included in the TCP/IP installation, but others can be developed as the need arises.

Note: LLP and HL7 are examples of protocols that can be processed by the adapter for TCP/IP. The adapter can actually be customized to process many protocols over the TCP/IP stack. All the presentation/protocol layers above TCP/IP can be processed by message handlers and data handlers.

Service call request processing follows the same stages except in reverse: the PIMO framework wraps messages in their protocol- specific data before sending them to be forwarded to the remote host.

PIMO maps

This section lists the default PIMO maps that are provided with the adapter for TCP/IP. If you need to write a custom message handler, you can use a default map and change the value against the Action attribute.

The way PIMO maps are used by the adapter for TCP/IP is described in Service call request processing and Event processing. Reference information about these maps is provided in PIMO framework meta-objects.

Inbound

The Inbound attribute indicates the set of maps used by PIMO in event mode processing. Three inbound maps are provided with the adapter:

Outbound

The Outbound attribute indicates the set of maps used by PIMO in service call request mode processing. Two outbound maps are provided with the adapter:

Note that the iPort for any of the default maps provided with the adapter is predetermined. The iPorts are the business objects (for example, BIA_InputMessage) shipped with the adapter. The oPorts usually do not have any requirements except that they wrap the content in the Content attribute of type BIA_ContentBO. See Map usage rules for details.

You can add to this list of maps, and you can bypass maps that are not needed. See Bypassing all maps.

Service call request processing

In service call request processing, a business object is sent by the broker to the adapter. After it is transformed, it is sent over the network.

The business object sent by the broker to the adapter in synchronous processing typically has two attributes:

This structure is not required, however. You can have the broker send information in the first and second attribute or any other attributes. You can have other attributes in the business object structure that can be ignored during request processing.

Figure 6. Structure of the business object sent by the broker
A sample business object, showing a Request attribute and a Response attribute.

When a request business object arrives, the Adapter Framework invokes the Protocol Handler Framework, and the following flow occurs:

  1. The Protocol Handler Framework passes the incoming business object to Message Processor.
  2. Message Processor reads the following properties from the connector configuration file:
  3. Message Processor invokes the appropriate data handler class, using information in DataHandlerMimeType, and the method of the data handler class, using information in ServiceRegistrationMO, for the mime type.
  4. The data handler reads the business object content and forms the application data. The data handler then returns the application data.

    Figure 7. Request processing flow - Part 1
    An illustration, showing an application business object being sent from the broker to the Protocol Handler framework and then being sent to Message Processing. Properties in the configuration file determine which data handler is used.
  5. Message Processor wraps the application data returned by the data handler in a business object (BIA_ApplicationMessage).
  6. Message Processor reads the map information contained in a BIA_ApplicationMessage child attribute contained in the Outbound attribute of BIA_MO_Tcpip_MapSubscriptions.
  7. Message Processor invokes the PIMO framework, passing the map information related to the business object, BIA_ApplicationMessage.

    Figure 8. Request processing flow - Part 2
    An illustration, showing how Message Processing uses the Outbound map in BIA_MO_Tcpip_MapSubscriptions to determine the map information to be sent to the PIMO framework.
  8. The PIMO framework uses the map information to invoke the appropriate message handler, which transforms the BIA_ApplicationMessage to the appropriate business object.

    The advantage of using the PIMO framework and maps is that you can control different application data. For example, the PIMO framework could invoke an LLP message handler that accepts BIA_ApplicationMessage as an input parameter and wraps the data contained in the BIA_ApplicationMessage in LLP protocol headers and trailers. The LLP message handler could then wrap the resultant content into a business object and return the business object to the PIMO framework.

  9. The PIMO framework returns the business object, returned by the message handler configured in the map, to the Message Processor.

    Figure 9. Request processing flow - Part 3
    An illustration, showing how Message Processing sends a BIA_ApplicationMessage to the PIMO framework, which calls a message handler. An application business object is returned to Message Processing.
  10. The Message Processor receives the business object from the PIMO framework and again reads the map information contained in the Outbound attribute of BIA_MO_Tcpip_MapSubscriptions for the particular business object name. If further maps are configured for the business object, the Message Processor invokes the PIMO framework again.
  11. The final application data is returned to the Protocol Handler Framework. The Protocol Handler Framework, using the client configuration details in the connector configuration file, connects to the remote server and sends the application data to the remote server.

    Figure 10. Request processing flow - Part 4
    An illustration, showing that the Protocol Handler Framework uses information in the Clients section of the configuration file to send the message to the remote server.

The way response from the server is processed depends on whether this is an asynchronous or a synchronous transaction.

Asynchronous processing

In asynchronous request processing, no response is expected by the adapter from the destination TCP/IP socket server. If the message can be delivered over the socket to the destination, the adapter sends back a success indicator to the broker.

Synchronous processing

In synchronous processing, the response from the server is processed, and the response is sent back to the broker, according to the following steps:

  1. The TCP/IP server returns the response to the connector. The connector passes this response to a configured message handler (the BIA_ResponseMessage map in the Outbound attribute of BIA_MO_Tcpip_MapSubscriptions).

    Figure 11. Response processing (synchronous mode)
    An illustration, showing how Message Processing uses the Outbound map in BIA_MO_Tcpip_MapSubscriptions to send map information to the PIMO framework.
  2. The message handler processes the response. This message handler could invoke a data handler to form the Response attribute business object.
    Note: The oPort of the BIA_ResponseMessage map conveys information to the connector (as described in steps 2a through 2f) and should have the following attributes:

    Figure 12. BIA_ResponseMessage map
    An illustration of BIA_ResponseMessage, with the oPort expanded.
    1. The message handler serializes, to a string, the response business object that will be sent back to the broker.
    2. The message handler populates the ResponseDataMimeType attribute of the oPort business object to convey the mime type used for serialization.
    3. The message handler populates the Content attribute of the oPort business object with the serialized string.
    4. The message handler uses the ResponseAttributeName of the oPort business object to convey to the adapter which attribute of the incoming request business object, from the broker, has to be populated with the de-serialized data.
    5. The message handler uses the CharSet attribute of the oPort business object to convey the character set of the data.
    6. The message handler communicates a status of VALCHANGE, in the Status attribute of the oPort business object of the BIA_ResponseMessage map, to the connector. This indicates to the connector that it needs to send back a status of VALCHANGE to the broker, indicating that the business object value, initially sent by the broker, has been changed.
      Note: Note that the processing logic of the Response business object is up to the message handler and the data handler that have been custom written for your business requirement. If the message handler is written to ignore the Response from the TCP/IP server, SUCCESS can be returned instead, in the Status attribute, to the broker.

      If you need to pass the Response back to the broker, the message handler needs to be written to handle the response from the TCP/IP server.

  3. The connector reads the oPort and de-serializes the data in the Content attribute of the oPort. The de-serialization is done using the mime type populated in the ResponseDataMimeType attribute.

    The de-serialized data is populated by the adapter in the ResponseAttributeName attribute of the request business object. The request business object is the business object that comes from the broker to the adapter.

Event processing

The Protocol Listener Framework receives data on a TCP/IP socket, and the following flow occurs:

  1. The Protocol Listener Framework passes the application data, incoming over a socket, to the Message Processor.
  2. The Message Processor forms a business object, BIA_InputMessage, from the application data. The application data contained in BIA_InputMessage at this moment might contain complete as well as incomplete application messages.
  3. This step is performed if the following two items are true:

    BIA_InputMessage_CheckComplete map filters complete messages from incomplete messages.

    If SupportMultipleMessages is false, only BIA_InputMessage map is invoked. The BIA_InputMessage map is for processing complete messages.

  4. The business object BIA_InputMessage is sent to the PIMO framework, which determines the appropriate message handler and invokes it. The message handler parses for complete messages and returns them to the Message Processor to be further processed by other message handlers.

    Figure 13. Event processing - Part 1
    An illustration of a message coming from the TCP/IP network and being received by the Protocol Listener Framework. The resulting BIA_InputMessage is sent to the PIMO framework and the appropriate message handler.
  5. The Message Processor receives the business object from the PIMO framework and reads the map information contained in the Inbound attribute of BIA_MO_Tcpip_MapSubscriptions for the particular business object name. If further maps are configured for the business object, the Message Processor invokes the PIMO framework again.

    Figure 14. Event processing - Part 2
    An illustration, showing how Message Processing uses the Inbound map in BIA_MO_Tcpip_MapSubscriptions to send map information to the PIMO framework.
  6. The Message Processor reads the DataHandlerMimeType, ServiceRegistrationMO, and DataHandlerMetaObjectName properties from the connector configuration file. The Message Processor invokes the appropriate data handler class, using information in the data handler meta-object for the mime type, and the method of the data handler class, using information in the Service Registration Meta Object for the mime type. The data handler returns the application business object for the application data sent to it.

    Figure 15. Event processing - Part 3
    An illustration, showing how Message Processing uses the properties in the configuration file to determine which data handler to use.
  7. The final application business object is sent to the broker in either synchronous or asynchronous mode. The response from the broker is sent to the data handler. The response from the data handler is wrapped in BIA_ApplicationMessage, and the BIA_ApplicationMessage map in the Inbound attribute is invoked. The Protocol Listener Framework sends the final application data back to the application server.

Copyright IBM Corporation 1997, 2005. All Rights Reserved.