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" |
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.
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".
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.
The getVersion() method returns the version of the connector's application-specific component.
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; }
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..
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.
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); } }
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.
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:
Figure 58 contains an implementation of the getConnectorBOHandlerForBO() method that returns a metadata-driven business object handler. It calls the constructor for the ExampleBOHandler class, which instantiates a single business-object-handler base class that handles all the business objects supported by the connector.
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(); }