Implementing the poll method

Regardless of whether the application provides is an event store in a table, inbox, or other location, the connector must poll periodically to retrieve event information. The connector's poll method, pollForEvents(), polls the event store, retrieves event records, and processes events. To process an event, the poll method determines whether the event has subscribers, creates a new business object containing application data that encapsulates the event, and sends the business object to the connector framework.

Note:
If your connector will be implementing request processing but not event notification, you might not need to fully implement pollForEvents(). However, since the poll method is defined as a pure virtual method in the C++ connector library, you must at least implement a stub for this method.

This section provides the following information on how to implement the pollForEvents() method:

Basic logic for pollForEvents()

The pollForEvents() method typically uses a basic logic for event processing. Figure 53 shows a flow chart of the poll method's basic logic.

Figure 53. Flow chart for basic logic of pollForEvents()


For an implementation of this basic polling logic, see Polling for events.

Other polling issues

This section provides information on the following polling issues:

Archiving events

Once a connector has processed an event, it can archive the event. Archiving processed or unsubscribed events ensures that events are not lost. Archiving usually involves the following steps:

This section provides the following information about event archiving:

Creating an archive store

If the application provides archiving services, you can use those; otherwise, an archive store is usually implemented using the same mechanism as the event store:

Configuring a connector for archiving

Archiving can have performance impact in the form of the archive store and moving the event records into this store. Therefore, you might want to design event archiving to be configurable at install time, so that a system administrator can control whether events are archived. To make archiving configurable, you can create a connector-specific configuration property that specifies whether the connector archives unsubscribed events. IBM suggests a name of ArchiveProcessed for this configuration property. If the configuration property specifies no archiving, the connector application-specific component can delete or ignore the event. If the connector is performance-constrained or the event volume is extremely high, archiving events is not required.

Accessing the archive store

A connector performs archiving as part of the event processing in its poll method, pollForEvents(). Once a connector has processed an event, the connector must move the event to an archive store whether or not the event was successfully delivered to the connector framework. Events that have no subscriptions are also moved to the archive. Archiving processed or unsubscribed events ensures that events are not lost.

Your poll method should consider archiving an event when any of the following conditions occur:

Note:
If a connector uses an event table, an administrator might need to clean up the archive periodically. For example, the administrator may need to truncate the archive to free disk space.

Threading issues

By default, C++ connectors are single-threaded. Therefore, the connector framework does not accept business objects from InterChange Server while the poll method is running. The connector framework calls the poll method only when it is not processing request business objects or other messages. Therefore, the poll method should not take a long time to complete.

Because request processing is blocked when the poll method is processing events, you need to be careful implementing the poll method to process multiple events per poll:

Note:
If a connector is configured to run in parallel-process mode (with ParallelProcessDegree greater than 1), it consists of several processes, each with a particular purpose, as shown in Table 106. Such a connector does not block request processing while it executes the poll method.

Processing events by event priority

Event priority enables the connector poll method to handle situations where the number of events in the event store exceeds the maximum number of events the connector retrieves in a single poll. In this type of polling implementation, the poll method polls and processes events in order of priority. Event priority is defined as an integer value in the range 0 - n, with 0 as the highest priority.

To process events by event priority, the following tasks must be implemented in the event notification mechanism:

Note:
As events are picked up, event priority values are not decremented. In rare circumstances, this might lead to low priority events being not picked up.

The following example SQL SELECT statement shows how a connector might select event records based on event priority. The SELECT statement sorts the events by priority, and the connector processes each event in turn.

SELECT event_id, object_name, object_verb, object_key
  FROM event_table
  WHERE event_status = 0 ORDER BY event_priority 
  

The logic for a poll method is then the same as discussed in "Basic logic for pollForEvents()".

Event distribution

The event detection and retrieval mechanisms can be implemented so that multiple connectors can poll the same event store. Each connector can be configured to process certain events, create specific business objects and pass those business objects to InterChange Server. This can streamline the processing of certain types of events and increase the transfer of data out of an application.

To implement event distribution so that multiple connectors can poll the event store, do the following:

Copyright IBM Corp. 1997, 2003