Handling errors and status

This section provides the following information about how the methods of the connector class library indicate error conditions:

Note:
You can also use error logging and message logging to handle error conditions and messages in your connector. For more information, see Message logging

Java return codes

In the Java connector library, the outcome-status constants in the CWConnectorConstant class define the Java return codes. Table 104 lists these Java outcome-status constants.

Table 104. Java outcome-status codes

Return code Description
CWConnectorConstant.SUCCEED
The operation succeeded.
CWConnectorConstant.FAIL
The operation failed.
CWConnectorConstant.APPRESPONSETIMEOUT
The application is not responding.
CWConnectorConstant.MULTIPLE_HITS
The connector found multiple matching records when retrieving using non-key values. The first record is returned with this status code.
CWConnectorConstant.BO_DOES_NOT_EXIST
The connector performed a Retrieve operation, but the entity that the business object represents does not exist in the application database.
CWConnectorConstant.RETRIEVEBYCONTENT_FAILED
The connector was not able to find matches for retrieve by non-key values.
CWConnectorConstant.UNABLETOLOGIN
The connector is unable to log in to the application.
CWConnectorConstant.VALCHANGE
At least one value in a business object has changed.
CWConnectorConstant.VALDUPES
The object in the application already has the requested data values.
CWConnectorConstant.CONNECTOR_NOT_ACTIVE
The connector is not active; it has been paused.
CWConnectorConstant.NO_SUBSCRIPTION_FOUND
No subscriptions were found for the event.

Outcome-status constants are provided for use in user implementations of many of the Java methods, as Table 105 shows. Although your code can return these values from within any method, some of the return codes were designed with specific uses in mind. For example, VALCHANGE informs the integration broker that the connector is sending a business object with changed values.

Table 105. Outcome-status values for Java connector methods

Connector method Possible outcome-status codes
archiveEvent() SUCCEED, FAIL
doVerbFor() SUCCEED, FAIL, APPRESPONSETIMEOUT, VALCHANGE, VALDUPES, MULTIPLE_HITS, RETRIEVEBYCONTENT_FAILED, BO_DOES_NOT_EXIST
gotApplEvent() SUCCEED, FAIL, CONNECTOR_NOT_ACTIVE, NO_SUBSCRIPTION_FOUND
pollForEvents() SUCCEED, FAIL, APPRESPONSETIMEOUT
terminate() SUCCEED, FAIL

The outcome-status constant that the connector framework receives helps to determine its next action, as follows:

Important:
The connector framework does not stop execution of the connector when it receives the FAIL outcome-status constant.

Exceptions

In addition to returning status codes, the methods of the Java connector library can throw exceptions to indicate certain predefined conditions. This section provides the following information about how to handle exceptions in a Java connector:

What Is a Java connector exception?

When a method of the Java connector library throws an exception, this exception object is a subclass of the CWException class, which is an extension of the Java Exception class. As Figure 68 shows, this exception object contains a message and status, as well as an exception-detail object with additional information about the exception.

Figure 68. The CWException exception object


Table 106 shows the accessor methods that the CWException class provides to obtain information in the exception object.

Table 106.

Information in the exception object
Member Accessor method
Message text getMessage()
Status getStatus(), setStatus()
Exception-detail object getExceptionObject()

Note:
For more information on the methods in the CWException class, see CWException class.

The exception-detail object is an instance of the CWConnectorExceptionObject class. As Figure 68 shows, an exception object contains an exception-detail object. This exception-detail object provides more detailed information about the Java connector library exception, as Table 107 shows.

Table 107.

Information in the exception-detail object
Member Description Accessor method
Message text The message text for the exception getMsg(), setMsg()
Message number The number in a message file that identifies the message getMsgNumber(), setMsgNumber()
Message explanation The detailed description of a message, which is also stored in the message file. This information might include a corrective action. getExpl(), setExpl()
Message type An integer constant that indicates the severity of a message getMsgType(), setMsgType()
Status An integer status that indicates the outcome of the method. getStatus(), setStatus()

Note:
For more information on the methods in the CWConnectorExceptionObject class, see CWConnectorExceptionObject class.

Exceptions from the Java connector library

When you write code for a Java connector, you can include Java try and catch statements to handle specific exceptions thrown by the methods of the Java connector library. The reference description for most Java connector library methods has a section entitled Exceptions, which lists the exceptions thrown by that method.

Figure 69 shows a code fragment from the default implementation of the pollForEvents() method that catches the exceptions that the getBO() method throws.

Figure 69. Catching exceptions from getBO()

try {
   bo = evts.getBO(evtObj);
 
   }catch (AttributeNotFoundException e) {
      CWConnectorUtil.generateAndLogMsg(10536,
         CWConnectorLogAndTrace.XRD_ERROR,
         0,2,"getBO","AttributeNotFoundException");
      return CWConnectorConstant.FAIL;
   }catch (SpecNameNotFoundException e) {
      CWConnectorUtil.generateAndLogMsg(10536,
         CWConnectorLogAndTrace.XRD_ERROR,
         0,2,"getBO","SpecNameNotFoundException");
      return CWConnectorConstant.FAIL;
   }catch (InvalidVerbException e) {
      CWConnectorUtil.generateAndLogMsg(10536,
         CWConnectorLogAndTrace.XRD_ERROR,
            0,2,"getBO","InvalidVerbException");
      return CWConnectorConstant.FAIL;
   }catch (WrongAttributeException e) {
      CWConnectorUtil.generateAndLogMsg(10536,
         CWConnectorLogAndTrace.XRD_ERROR,
         0,2,"getBO","WrongAttributeException");
      return CWConnectorConstant.FAIL;
   }catch (AttributeValueException e) {
      CWConnectorUtil.generateAndLogMsg(10536,
         CWConnectorLogAndTrace.XRD_ERROR,
         0,2,"getBO","AttributeValueException");
      return CWConnectorConstant.FAIL;
   }catch (AttributeNullValueException e) {
      CWConnectorUtil.generateAndLogMsg(10536,
         CWConnectorLogAndTrace.XRD_ERROR,
         0,2,"getBO","AttributeNullValueException");
      return CWConnectorConstant.FAIL;
   }

When a Java connector library method throws an exception, it does not usually provide message and status information in the exception object. However, you can choose to fill the exception object with additional information as needed.

Return-status descriptor

The return-status descriptor usually contains information about the success (or lack thereof) of the verb processing that the business object handler (the doVerbFor() method) has performed. The calling code can use this status information to determine how to proceed. When the business object handler for a particular business object is invoked, the doVerbFor() of its associated business-object-handler class executes. However, the actual method invoked is not the user-implemented doVerbFor() (which the connector developer implements as part of the business-object-handler class). Instead, the business object handler invokes a low-level doVerbFor() method, which is defined in this same class but which the connector developer does not implement.

This low-level doVerbFor() method performs the following tasks:

  1. Receive an empty return-status descriptor as an argument.
  2. Call the user-implemented doVerbFor() to perform the verb processing.
  3. Populate the return-status descriptor based on the verb-processing status when this user-implemented doVerbFor() completes (either successfully or otherwise).

Because the low-level doVerbFor() receives an instantiated return-status descriptor as an argument, any changes that it makes to this return-status descriptor are available to the calling code (which instantiated the return-status descriptor) once the low-level doVerbFor() exits. Therefore, the code that called the business object handler can access this return-status descriptor to obtain information about the status of the verb processing.

Access to this return-status descriptor can be performed in either of the following ways:

Implicitly accessing the return-status descriptor

In request processing, the connector framework uses the return-status descriptor to report the status of the verb processing back to the integration broker. When the connector framework receives a request business object, it locates the associated business-object-handler class and invokes its low-level doVerbFor() method. It passes to this low-level doVerbFor() an instantiated, empty return-status descriptor.

When the low-level doVerbFor() completes, it has populated the return-status descriptor with the verb-processing status from the user-implemented doVerbFor() method. The connector framework then includes this return-status descriptor as part of its response to the integration broker. For more information, see "Populating the return-status descriptor".

Explicitly accessing the return-status descriptor

In event notification, the poll method can use the return-status descriptor to determine the success of the retrieval of application data associated with an event. When the poll method, pollForEvents(), retrieves an event from the event store, the event usually contains only the key values of the associated application event. To obtain all application data, pollForEvents() must use the key value (or values) to query the application and retrieve the full set of values. For more information, see "Retrieving application data".

A common way to retrieve this application data is to call the business object handler with a RetrieveByContent verb in the business object. To facilitate this use of a business object handler, the CWConnectorBusObj class provides a version of the doVerbFor() method. When calling code calls this doVerbFor() method, it invokes the business object handler for the current business object by calling the low-level doVerbFor() method. The code that calls the CWConnectorBusObj version of doVerbFor() must first create a return-status descriptor and then pass this instantiated, empty return-status descriptor into doVerbFor().

The CWConnectorBusObj version of doVerbFor() passes the empty return-status descriptor to the low-level doVerbFor() method in the business-object-handler class. When the low-level doVerbFor() completes, it has populated the return-status descriptor with the verb-processing status from the user-implemented doVerbFor() method. The CWConnectorBusObj version of doVerbFor() passes this return-status descriptor back to the calling code. Because the calling code has instantiated this return-status descriptor, it can explicitly access its contents to determine the success of the verb processing.

For a Java connector, the return-status descriptor is a CWConnectorReturnStatusDescriptor object. Table 108 lists the status information that this structure provides.

Table 108. Information in the return-status descriptor

Return-status descriptor information Description Java accessor method
Error message A string to provide a description of the error condition getErrorString(), setErrorString()
Status An additional status value to further detail the cause of the error condition getStatus(), setStatus()

The CWConnectorEventStore class provides the getBO() method to retrieve application data associated with an event. The default implementation of the getBO() method calls the CWConnectorBusObj version of doVerbFor() to perform this retrieval. The default implementation of the pollForEvents() method includes a call to getBO(). Therefore, your pollForEvents() does not need to explicitly access the return-status descriptor for information about the retrieval status in either of the following cases:

The default implementation of getBO() automatically accesses the return-status descriptor and returns values (or throws exceptions) to indicate the retrieval status.

Note:
You can use the methods of the CWConnectorReturnStatusDescriptor method to access the collaboration status from a return-status descriptor after execution of the executeCollaboration() method.

Important:
Any status code that the doVerbFor() method sets in the return-status descriptor must have meaning to the collaboration. The collaboration developer and the connector developer must agree on the meaning of this status code.

Copyright IBM Corp. 1997, 2004