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.
Each connector has a connector startup script to begin its execution. This startup script invokes the connector framework.
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.
When InterChange Server is the integration broker, the connector framework takes the following steps to invoke 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.
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:
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.
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 |
---|---|
CWConnectorAgent
|
agentInit()
|
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:
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:
Use the getConfigProp() method to obtain the value of a connector configuration property. For more information, see "Using connector configuration property values".
In a Java connector, the agentInit() method should throw the ConnectionFailureException exception if the connection fails or the LogonFailureException exception if the connector is unable to log into the application. For information on these conditions, see Exceptions.
The getVersion() method returns the version of the connector. It is called in both of the following contexts:
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
For a Java connector, the CWConnectorEventStore class provides the recoverInProgressEvents() method to obtain event records with an In-Progress status from the event store and take the appropriate recovery action. The connector developer can implement this method to take actions based on the value of InDoubtEvents. In t his method, the connector developer can also change the status of in-progress events to the ready-for-poll status.
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 getConnectorBOHandlerForBO() 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.
To instantiate the business object handler (or business object handlers), the connector framework takes the following steps:
The number of business object handlers that are instantiated depends on the overall design of your connector's business object handling:
A metadata-driven connector handles all business objects in a single, generic business object handler, called a metadata-driven business object handler. Therefore, the getConnectorBOHandlerForBO() method can simply instantiate one business object handler, regardless of the number of business objects the connector supports. It can create a business object handler the first time it is called and return a pointer to the same handler for each subsequent call.
If your connector requires a separate business object handler for each business object, the getConnectorBOHandlerForBO() method can instantiate the appropriate business object handler, based on the name of the business object being passed in. In this case, getConnectorBOHandlerForBO() instantiates multiple business object handlers, one for each business object definition that requires a separate business object handler. Each time the business-object-handler retrieval method is called, it instantiates a separate business object handler.
For more information on how to implement the getConnectorBOHandlerForBO()method, see Obtaining the Java business object handler. For information on how to implement business object handlers, see Request processing.
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 Java connector library, the pollForEvents() method is defined in the CWConnectorAgent class. Typical return codes used in pollForEvents() are SUCCEED, FAIL, and APPRESPONSETIMEOUT. For more information on return codes, see Java return codes.
For a more thorough discussion of event notification and the implementation of pollForEvents(), see Event notification.
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.