agentInit()

Initializes the connector.

Syntax

public void agentInit();

Parameters

None.

Return values

None.

Exceptions

ConnectionFailureException
Thrown if the connector fails to obtain a connection with the application.
InProgressEventRecoveryFailedException
Thrown if the connector is unable to perform in-progress event recovery.
LogonFailedException
Thrown if the connector is unable to log into the application.
PropertyNotSetException
Thrown if the connector retrieves any required connector configuration property that does not have a value set for it.

Notes

The agentInit() method performs all initialization functionality for the connector, including any of the following tasks required for the connector's application-specific component:

Important:
The CWConnectorAgent class does not provide a default implementation for the agentInit() class. Therefore, the connector class must implement this method.

The connector framework calls the agentInit() method to initialize the connector when it comes up. If agentInit() performs any of the conditions listed in Table 97,, it must check for the following conditions and throw the appropriate exception.

Table 97. Exceptions to throw from the agentInit() method
Condition Exception to throw
If the connector retrieves any required connector configuration property that is not set PropertyNotSetException
If the connector fails to obtain a connection with the application ConnectionFailureException
If the connector fails to log onto the application LogonFailedException
If the recoverInProgressEvents() method finds In-Progress events in the event store and some failure occurs during the recovery process InProgressEventRecoveryFailedException

To throw one of the exceptions in Table 97, take the steps outlined in Table 98:

Table 98. Handling an initialization error
Error-handling step Method or code to use
1. If an error has occurred, log an error message to the log destination to indicate the cause of the initialization error. CWConnectorUtil.generateAndLogMsg()
2. Instantiate an exception-detail object to hold the exception information. CWConnectorExceptionObject excptnDtailObj = new CWConnectorExceptionObject();
3. Set the status information within an exception-detail object:
  • set a message to indicate the cause of the initialization failure
excptnDtailObj.setMsg()
  • set the status to an outcome status that tells the connector framework the success of the initialization. If you want the initialization process (and the connector) to terminate, set the outcome status to CxConnectorConstant.FAIL.
excptnDtailObj.setStatus()
4.

Throw the agentInit() exception from Table 97 that indicates the initialization failure. This exception is how the agentInit() method tells the connector framework that a initialization error has occurred. This exception object contains the exception-detail object you initialized in Step 3.

When the low-level init() method (which calls agentInit()) catches this exception object, it copies the status from the exception-detail object into its own return status, which it returns to the connector framework.

Note:
If you do not set the exception status within the exception-detail object, the init() method returns an outcome status of FAIL and the connector framework terminates the connector.
throw new agentInitException( excptnDtailObj);

See also

generateAndLogMsg(), recoverInProgressEvents()

Copyright IBM Corp. 1997, 2004