Adapter architecture

The IndusConnect Framework adapter is built using the WebSphere business Integration Adapter (WBIA) framework and WBIX adapter framework extensions. WebSphere Business Integration extensions (WBIX) are a set of modular components built on top of the WBIA framework and are configured and instantiated at runtime. The components are, at a high level, two transports and one or more logic modules. Logic modules process an internal business object enroute from the originating transport to the target transport. Logic modules can be chained together if necessary. A routing path defines a path for a particular business object from one transport through certain logic modules and into the other transport. The WBIX XML data handler is used to convert between generic business objects and their XML representation for processing by the XSLT logic module. Figure 1 is a high-level view of the architecture.

Figure 1. A high-level view of the adapter architecture

A high-level view of the architecture showing the flow of data through the adapter. Graphic illustrates data flow from the application to the adapter using the routing path, where the data passes through the application transport , through a logic module, through the broker transport, then finally to the hub or integration broker. The reverse data flow is also shown, where the data flow begins at the integration broker and ends at the application.

Figure 2 is a slightly more detailed view showing more of the components. Descriptions of each of these components follow.

Figure 2. Slightly more detailed view.

A slightly more detailed view of the architecture, showing the same data flow and the various adapter components.

The adapter components

The following are the adapter components:

Adapter Core
The adapter core controls the data and logic flows in the adapter.
Connector Profile
The connector profile describes the connector configuration and its properties. The Connector Configurator, which is a tool with a graphical user interface, enables you to define the configuration and properties.
WBIX XML Data Handler
The WBIX XML data handler provides conversion between generic business objects and their XML representation for processing by the XSLT logic module.
Event store
The event store provides persistence throughout adapter processing. Events are persisted within the queue, by default, until written to the event store. See Event life cycle and Event store file naming for additional details on the event store component.

The event store for this adapter is com.ibm.wbix.adapter.transports.FileSystemEventStore.

Transport
A transport encapsulates inbound, outbound, and persistent communications logic for the adapter and integration broker. The outbound component of the transport is the sender. The inbound component of the transport is the receiver. The persistence component is the event store.

Because an application might have a mix of different protocols as its integration interface (for example, an SQL database interface for some data and an MQ messaging interface for other data), multiple transports can be loaded with a single adapter to enable the adapter to communicate across disparate protocols. In addition, each transport can house multiple incoming (receivers) and outgoing (senders) endpoints, such as a single receiver or sender for each of the application messaging queues. Transports are provided for some common interfaces. See Transport modules for additional details on the transport component.

Logic Modules
Logic modules process data from an inbound transport receiver enroute to the outbound transport sender. These modules provide translation functionality between the application and integration broker data formats. For example, an XSLT logic module is provided for the situation where both inbound and outbound formats are in XML format.

You can create custom logic modules to provide processing specific to your requirements. For example, you could create a specific XSL file to define a specific grammar transformation. Logic modules can also be chained if you require that capability.

The logic module for this adapter is com.ibm.wbix.adapter.logicmodules.XsltLogicModule.

Transport modules

The standard WebSphere Business Integration sender and receiver transport modules are used for communication with the integration broker. They expect the body of the message to contain an XML format recognized by the adapter or the WBI transport, which then gets converted into a WebSphere Business Integration Java object and sent to the integration broker for processing. The transport component contains modules that communicate with the integration broker and modules that communicate with the application.

For this adapter, the WebSphere Business Integration transport consists of the following components:

com.ibm.wbix.datahandlers.XMLDataHandler
The data handler converts WBI business objects to and from the adapter's WBI XML.
com.ibm.wbix.adapter.transports.wbi.WBISender
This module does not require any configuration parameters.
com.ibm.wbix.adapter.transports.wbi.WBIReceiver
This module does not require any configuration parameters.

Adapter servlets

A set of servlets are provided for use in conjunction with the adapter and the IndusConnect Framework. These servlets are used as an abstraction for the IndusConnect external event table. The abstraction enables the adapter to interface with IndusConnect in a uniform manner over HTTP. The servlets enable the adapter to do the following:

The servlets are packaged as a J2EE Web application (a .warfile). This application must be installed on the application server hosting the IndusConnect application. The servlets' database access is configured using the IndusConnect apifw.properties file. To resolve this file location, the servlets must be passed a Java(TM) system property named "passPort_properties". The value of this property is the directory in which the apifw.properties file resides. This configuration ensures that IndusConnect and the servlets access the same database with the same parameters. See the application server documentation for instructions on how to install a Web application and supply a system property.

A description of the adapter servlets and their parameters follows:

printEventTable
Displays all events in the external event table (TIDAPIEV).
getEventXML
Gets full outbound event XML detail of event. Multiple documents can be returned.
eventID
Unique identifier (timestamp from above) to identify the event.
Note:
Not setting eventID returns XML for all documents in the table.
status
Filter by event status (all events have status equal to this argument).
Note:
The status and notStatus parameters are mutually exclusive.
notStatus
Reverse filter by event status (all events status not equal to this argument).
removeEvent
Removes event from the external event table (TIDAPIEV).
eventID
Unique identifier (timestamp from above) to identify an event. Specifying eventID = all removes all events in the table.
setStatus
Sets the status of an event in the event table.
eventID
Unique identifier (timestamp from above) to identify an event.
status
String value to set as status for this event.

Event life cycle

Events generated in the Indus PassPort component of the application are propagated to the integration broker as follows:

Note:
In the following description, remote event store refers to the Indus PassPort event table.
  1. Indus PassPort publishes the application events to the remote event store with status PRE_POLL_STATUS.
  2. The adapter servlet returns the published event to the adapter in the next poll.
  3. The adapter adds the event to the local event store with status EVENT_RECEIVED. See Table 1 for a list of the status constants.
  4. The adapter updates the status of the event in the remote event store to POST_POLL_STATUS
  5. Processing occurs on the event in the local event store which changes status:
  6. When the processing and polling completes, the local event status is changed to the appropriate status value, for example, WBIA polling results in ERROR_POSTING_EVENT or SUCCESS.
  7. If the final local status value is an error, the event in the remote event store is set to ERROR_COMPLETION_STATUS. If successful, the event in the remote event store is set to SUCCESS_COMPLETION_STATUS.
  8. The event is archived:

In the current configuration:

PRE_POLL_STATUS=R
POST_POLL_STATUS = 9
ERROR_COMPLETION_STATUS = 7
SUCCESS_COMPLETION_STATUS = 8

Event store file naming

The FileSystemEventStore component of the IndusEventStore uses the local file system as the provided default persistent event store implementation. When the adapter is started, it creates separate directories for the event store proper and the event store archive.

For each event added to store, the adapter writes a new log file with the event contents. Each event record uses a naming convention consisting of a unique ID, appended with an event status separated by an underscore (_), for example, uniqueID_status value. The unique ID is obtained by computing a hash function on the event ID of the message.

If you use this event store, ensure that the event IDs generated by the receivers contain no special characters that are disallowed by your file system. For the adapter for IndusConnect Framework, the event ID is the timestamp of an event outbound from the Indus PassPort event table.

For event status changes, the event store generally renames the file to reflect the updated status. However, for status changes that indicate a change in the event body, for example, IN_PROCESSING to READY_FOR_POLL, the event store rewrites the file contents.

The status constants are listed in Table 1. Error constants are listed in Table 2.

Table 1. Status constants

Status constant Value
EVENT_RECEIVED 2147483647
IN_PROCESSING 2147483646
EVENT_PROCESSED 2147483645
READY_FOR_POLL 0
IN_PROGRESS 1
SUCCESS 3

The error constants are:

Table 2. Error constants

Error constant Value
ERROR_IN_LOGIC_PROCESSING -2147483647
UNSUBSCRIBED 2
ERROR_PROCESSING_EVENT -1
ERROR_POSTING_EVENT -2
ERROR_OBJECT_NOT_FOUND -3

Copyright IBM Corp. 1997, 2003