Running a connector

When the connector runs, it performs the tasks summarized in Table 20..

Table 20. Steps for executing a connector

Execution step For more information
1. Start the connector with the startup script to initialize the connector framework and application-specific component of the connector. "Starting up a connector"
2. If polling is turned on, the connector framework calls pollForEvents() at the interval defined by the connector's PollFrequency connector configuration property. "Polling for events"
3. If the connector implements request processing, call the business-object handler associated with the request business object that the connector receives. Request processing is implemented by the doVerbFor() method in the connector's business object handler. For more information, see Request processing.
4. When the connector is shut down, the connector framework calls terminate(). "Shutting down the connector"

The following sections provide more information about each of the execution steps Table 20..

Starting up a connector

Each connector has a connector startup script to begin its execution. This startup script invokes the connector framework.

Note:
For more information on how to create a connector startup script, see "Creating startup scripts"..

Once the connector framework is executing, it performs the appropriate steps to invoke the application-specific component of the connector, based on the integration broker.

Starting connectors with InterChange Server

When InterChange Server is the integration broker, the connector framework takes the following steps to invoke the application-specific component:

  1. Use the Object Request Broker (ORB) to establish contact with InterChange Server.
  2. From the repository, load the following connector-definition information into memory for the connector's process:
  3. Begin execution of the connector's application-specific component by instantiating the connector base class and calling methods of this base class that initialize the application-specific component.

    When the connector is started, the connector framework instantiates the connector base class and then calls the connector-base-class methods in Table 21..

    Table 21. Beginning execution of the connector

    Initialization task For more information
    1. Initialize the connector to perform any necessary initialization for the application-specific component, such as opening a connection to the application. "Initializing the connector"
    2. For each business object that the connector supports, obtain the business object handler. "Obtaining the business object handler"

    Once these methods have been called, the connector is operational.

  4. Contact the connector controller to obtain the subscription list for business objects to which collaborations have subscribed. For more information, see "Business object subscription and publishing"..

Starting connectors with other integration brokers

When a WebSphere message broker (WebSphere MQ Integrator, WebSphere MQ Integrator Broker, or WebSphere Business Integration Message Broker) or WebSphere Application Server is the integration broker, the connector framework takes the following steps to invoke the application-specific component:

  1. From the local repository, load the following connector-definition information into memory for the connector's process:
  2. Begin execution of the connector's application-specific component by instantiating the connector base class and calling methods of this base class that initialize the application-specific component.

    When the connector is started, the connector framework instantiates the connector base class and then calls the connector-base-class methods in Table 21.. Once these methods have been called, the connector is operational.

Initializing the connector

To begin connector initialization, the connector framework calls the initialization method of the connector base class. Table 22 shows the initialization method for the connector.

Table 22. Connector base class methods to initialize the connector

Class Method
GenGlobals
init

As part of the implementation of the connector class, you must implement an initialization method for your connector. The main tasks of the initialization method include:

Important:
During execution of the initialization method, business object definitions and the connector framework's subscription list are not yet available.
Establishing a connection

The main task of the initialization method is to establish a connection to the application. To establish the connection, the initialization method can perform the following tasks:

Checking the connector version

The getVersion() method returns the version of the connector. It is called in both of the following contexts:

Note:
A connector should keep track of which application versions it supports. It should check the application version when it logs on to the application.
Recovering In-Progress events

Processing an event during event notification includes performing a retrieve on the application entity, creating a new business object for the event, and sending the business object to the connector framework. If the connector terminates while processing an event and before updating the event status to indicate that the event was either sent or failed, the In-Progress event will remain in the event store. When a connector is restarted, it should check the event store for events that have an In-Progress status.

If the connector finds events with the In-Progress status, it can choose to do one of the tasks outlined in Table 23.. This behavior should be configurable. Several connectors use the InDoubtEvents connector configuration property for this purpose. Its settings are also shown in Table 23..

Table 23. Actions to take to recover In-Progress events

Event-recovery action taken Value of InDoubtEvents
Change the status of the In-Progress events to Ready-for-Poll so they can be submitted to the connector framework in subsequent poll calls. Note: If events are resubmitted, duplicate events might be generated. If you want to ensure that duplicate events are not generated during recovery, use another recovery response. Reprocess
Log a fatal error, shutting down the connector. If LogAtInterchangeEnd is set to True, this triggers an email notification about the error. FailOnStartup
Log an error without shutting down the connector. LogError
Ignore the In-Progress event records in the event store. Ignore

For a C++ connector, you must use the application-specific interface to obtain event records with an In-Progress status from the event store and take the appropriate recovery action.

Note:
For more information on event notification, the event store, and In-Progress events, see Event notification.

Obtaining the business object handler

As the final step in connector initialization, the connector framework obtains the business object handler for each business object definition that the connector supports. A business object handler receives request business objects from the connector framework and performs the verb operations defined in these business objects. Each connector must have a getBOHandlerforBO() method defined in its connector base class to retrieve the business object handler. This method returns a reference to the business object handler for a specified business object definition.

Important:
As part of the implementation of the connector base class, you must implement the getBOHandlerforBO() to obtain business object handlers for your connector.

To instantiate the business object handler (or business object handlers), the connector framework takes the following steps:

  1. During initialization, the connector framework receives a list of business object definitions that the connector supports. For more information, see "Starting up a connector".
  2. The connector framework then calls the getBOHandlerforBO() method, once for every supported business object.
  3. The getBOHandlerforBO() method instantiates the appropriate business object handler for that business object, based on the name of the business object definition it receives as an argument. It returns the business object handler to the connector framework.

    The number of business object handlers that are instantiated depends on the overall design of your connector's business object handling:

  4. The connector framework stores the reference to this business object handler in the associated business object definition (which resides in the memory of the connector's process).
Important:
Before you implement the getBOHandlerforBO() method, you want to complete the design for business object handling for your connector. For information on designing application-specific business object, see "Assessing support for metadata-driven design"..

For more information on how to implement the getBOHandlerforBO()method, see Obtaining the C++ business object handler.. For information on how to implement business object handlers, see Request processing.

Polling for events

If a connector is to implement event notification, it must implement an event notification mechanism. Event notification contains methods that interact with an application to detect changes to application business entities. These changes are represented as events, which the connector sends to the connector framework for routing to a destination (such as InterChange Server).

If the connector uses a polling mechanism for event notification, the connector must implement the pollForEvents() method to periodically to retrieve event information from the event store, which holds events that the application generates until the connector can process them. When polling is turned on, the connector framework calls the poll method pollForEvents(). The pollForEvents() method returns an integer indicating the status of the polling operation.

In the C++ connector library, the pollForEvents() method is defined in the GenGlobals class. Typical return codes used in pollForEvents() are BON_SUCCESS, BON_FAIL, and BON_APPRESPONSETIMEOUT. For more information on return codes, see C++ return codes.

Important:
The developer must provide an implementation of the pollForEvents() method. If the connector supports only request processing, you do not need to fully implement pollForEvents(). However, because the poll method is a required method, you must implement a stub for the method.

For a more thorough discussion of event notification and the implementation of pollForEvents(), see Event notification.

Shutting down the connector

The administrator shuts down a connector with by terminating the connector startup script. When the connector is shut down, the connector framework calls the terminate() method of the connector base class. The main task of the terminate() method is to close the connection with the application and to free any allocated resources.

Copyright IBM Corp. 1997, 2003