Beginning execution of the connector

When the connector is started, the connector framework instantiates the associated connector class and then calls the connector class methods in Table 60..

Table 60. Beginning execution of the connector
Initialization task For more information
1. Initialize the connector to perform any necessary initialization for the connector, 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 Java business object handler

Initializing the connector

To begin connector initialization, the connector framework calls the initialization method, agentInit(), in the connector base class, CWConnectorAgent. This method performs initialization steps for the connector's application-specific component.

Important:
As part of the implementation of your connector class, you must implement an agentInit() method for your connector.

As discussed in Initializing the connector,, the main tasks of the agentInit() initialization method include:

In addition to the above topics, this section provides an example Java agentInit() method in Example Java initialization method.

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 agentInit() initialization method is to establish a connection to the application. It executes successfully if the connector succeeds in opening a connection. If the connector cannot open a connection, the initialization method must throw the ConnectionFailureException exception to indicate the cause of the failure. The connector might also need to log into the application. If this logon attempt fails, the initialization method must throw the LogonFailedException to indicate the cause of the failure. The steps in Table 64 outline how to throw either of these initialization exceptions.

Note:
For an overview of the steps in an initialization method, see Establishing a connection..

Checking the connector version

The getVersion() method returns the version of the connector's application-specific component.

Note:
For a general description of getVersion(), see Checking the connector version..

In the Java connector library, the getVersion() method is defined in the CWConnectorAgent class. This class provides a default implementation of getVersion() that obtains the version from the Java manifest file. You can override getVersion() to provide a different implementation.

For example, the following code sample implements getVersion() to return a string indicating the version of the connector.

public String getVersion(){
 // get version from manifest file, or from string
 
  String version = "1.0.0";
  return version;
}

Recovering In-Progress events

The Java connector library provides the CWConnectorEventStore class to represent an event store. To recover In-Progress event records in the event store, the Java connector library provides the method in Table 61..

Table 61. Method for recovering In-Progress events
Java connector library class Method
CWConnectorEventStore recoverInProgressEvents()

The recoverInProgressEvents() method implements the recovery behavior for In-Progress events. However, the CWConnectorEventStore class does not provide a default implementation for this method. One possible recovery behavior is based on the InDoubtEvents connector configuration property and is outlined in Table 23..

Note:
For a general discussion of how to recover In-Progress events, seeRecovering In-Progress events..

If the recovery process fails, the initialization method must throw the InProgressEventRecoveryFailedException to indicate the cause of the failure. The steps in Table 64 outline how to throw this initialization exception.

Figure 56 shows a fragment of the agentInit() method that uses recoverInProgressEvents() to recover the In-Progress events.

Figure 56. Recovering in-progress events
   // instantiate event-store factory 
   evtFac=new MyEventStoreFactoryInstance();

   // instantiate event store
   Object evto=evtFac.getEventStore();
   CWConnectorEventStore evts=(CWConnectorEventStore)evto;

   // check for any leftover In-Progress events
   String inDoubtEvents=CWConnectorUtil.getConfigProp(
      "InDoubtEvents");

   // In case the InDoubtEvents property is not set, use 
   // FailOnStartup as default.
   if (inDoubtEvents == null || inDoubtEvents.equals(""))
      inDoubtEvents="FailOnStartup";

   // recover In-Progress events
   if (evts.recoverInProgressEvents() == FAIL
         || inDoubtEvents.equals("FailOnStartup") ) {

         // log a fatal error

         // throw an exception to terminate agentInit()
         throw new InProcessEventRecoveryFailureException()
      }
   }

In Figure 56,, the MyEventStoreFactoryInstance class is an example of an extension of the CWConnectorEventStoreFactory class, whose getEventStore() method provides access to the event store.

Example Java initialization method

For a Java connector, the agentInit() method provides the initialization for the connector's application-specific component. This method does not return a value but throws special exceptions to indicate common initialization errors. Figure 57 shows a simple agentInit() method that obtains connector properties and establishes a connection to the application.

Figure 57. Initializing a Java connector
public agentInit()
   throws PropertyNotSetException, ConnectionFailureException,
   InProgressEventRecoveryFailedException, LogonFailedException
{

   CWConnectorUtil.traceWrite(CWConnectorLogAndTrace.LEVEL4,
      "Entering Connector agentInit()");

   int status = CWConnectorConstant.SUCCEED;
   connectorProperties =
      CWConnectorUtil.getAllConnectorAgentProperties();

   ExampleConnection userConnect = new Connection();

   // get Connector Configuration Properties to establish Connection
   String connectString =
      (String)connectorProperties.get("ConnectString");
   String userName =
      (String)connectorProperties.get("ApplicationUserName");
   String userPassword =
      (String)connectorProperties.get("ApplicationPassword");

   if(connectString == null || connectString.equals("") 
         || userName==null || userPassword==null )
      {
      throw new PropertyNotSetException();
      }

   // Use Configuration Values to log into Application
   try
   {
      boolean loginSuccessful = userConnect.login(connectString,
         userName, userPassword);

      if(loginSuccessful)
         CWConnectorUtil.generateAndLogMsg(30000,CWConnectorLogAndTrace.XRD_INFO,);
   }
   catch(ExampleAppException se)
   {
      CWConnectorUtil.generateAndLogMsg(30001,
             CWConnectorLogAndTrace.XRD_ERROR,0,1,path);
   }

}

Note:
For agentInit() code fragment that recovers In-Progress events, see Figure 56..

Obtaining the Java business object handler

In a Java connector, the business-object-handler base class is CWConnectorBOHandler. To obtain an instance of a business object handler for a supported business object, the connector framework calls the getConnectorBOHandlerForBO() method, which is defined as part of the CWConnectorAgent class.

Note:
For general information about the getConnectorBOHandlerForBO() method, see Obtaining the business object handler.. For a general discussion of how to design business object handlers, see Designing business object handlers..

The default implementation of getConnectorBOHandlerForBO() in the CWConnectorAgent class returns a business object handler for a business-object-handler base class named ConnectorBOHandler. If you name your extended business-object-handler base class ConnectorBOHandler, you do not need to override the getConnectorBOHandlerForBO() method. However, if you name your extended business-object-handler base class some other than ConnectorBOHandler, you must override getConnectorBOHandlerForBO() to return an instance of your extended business-object-handler base class.

The number of business object handlers that the connector framework obtains through its calls to the getConnectorBOHandlerForBO() method depends on the overall design for business object handling in your connector:

Important:
During execution of the getConnectorBOHandlerForBO() method, the business object class methods are not yet available.

Figure 58 calls the constructor for the ExampleConnectorBOHandler class to instantiate a single business-object-handler base class that handles all the business objects supported by the connector.

Figure 58. The getConnectorBOHandlerForBO() method for generic business object handler
public CWConnectorBOHandler getConnectorBOHandlerForBO(String BOName){
   return new ExampleConnectorBOHandler();
}

Copyright IBM Corporation 1997, 2004. All Rights Reserved.