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.
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.
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.
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.
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).
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.
The declaration attribute is optional. It contains names for temporary variables to be used during processing.
ActionEach 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.
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.
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.
InboundThe Inbound attribute indicates the set of maps used by PIMO in event mode processing. Three inbound maps are provided with the adapter:
This map is invoked in event processing. It is used for complete messages.
This map is invoked in event processing. This map is used when, on a single socket read call, multiple messages arrive.
To switch on this map, set the SupportMultipleMessages in BIA_MO_Service to true for the mime type configured in the connector configuration file.
BIA_InputMessage_CheckComplete map filters complete messages from incomplete messages. The complete messages are passed to BIA_InputMessage for processing. For incomplete messages, the adapter waits on the socket for further data. The BIA_InputMessage_CheckComplete is then invoked again.
If SupportMultipleMessages is false, only BIA_InputMessage map is invoked. The BIA_InputMessage map is for processing complete messages.
This map is invoked in synchronous event processing, when the response from the broker comes to the adapter for the synchronous event.
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:
This map is invoked to process the data returned by the data handler. The processed data is then written by the adapter to the TCP/IP socket.
This map is invoked in synchronous request processing on the response data received by the adapter from the TCP/IP server during a synchronous request call.
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.
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.
When a request business object arrives, the Adapter Framework invokes the Protocol Handler Framework, and the following flow occurs:
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.
The way response from the server is processed depends on whether this is an asynchronous or a synchronous transaction.
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.
In synchronous processing, the response from the server is processed, and the response is sent back to the broker, according to the following steps:
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.
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.
The Protocol Listener Framework receives data on a TCP/IP socket, and the following flow occurs:
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.