Adapter architecture

The IndusConnect Framework adapter is built using the WBI adapter framework. 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. 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.

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.

The adapter components

The following are the adapter components:

XML Profile
The adapter framework configuration is specified in an XML profile. Appendix D, XML rules lists the rules for developing a profile.

Adapter Core
The adapter core controls the data and logic flows in the adapter.

Transport
A transport provides the custom interface to the specific application. The outbound component of the transport from the application is the sender. The inbound component of the transport is the receiver. The persistence component is the eventstore. A different application might have different protocols for different portions of its interface (for example, an SQL database interface for some data and an MQ messaging interface for other data). Therefore, one transport can contain multiple senders and receivers. Transports are provided for some common interfaces.

Logic Modules
Logic Modules process data inbound from an inbound transport receiver enroute to the outbound transport sender. For example, an XSLT logic module is provided for the situation where both inbound format and outbound are in XML format. You can create a specific XSLT file to define a specific grammar transformation. Logic modules can be chained. The product package provides some logic modules. Custom logic modules may be written as well.

Adapter transport

The standard WBI sender and receiver transport modules are used for communication with ICS. They expect the body of the message to contain WBI XML, which gets converted into a WBI Java object and sent into ICS for processing. The WBI transport consists of the following components packaged with the adapter:

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 ICS 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, 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, it writes a new log file with the event contents. The naming convention of event records is "hashOfeventID_status". The class, by default, does a best effort to handle event IDs with special characters when writing to the file system. However, IDs with special characters can result in ID collisions.

If you use this event store, ensure that the eventIDs generated by the receivers contain no special characters that are disallowed by your file system. For the adapter for IndusConnect Framework, the eventID 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 and 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