This section provides the following information about how the methods of the connector class library indicate error conditions:
In the Java connector library, the outcome-status constants in the CWConnectorConstant class define the Java return codes. Table 86 lists these Java outcome-status constants.
Outcome-status constants are provided for use in user implementations of many of the Java methods, as Table 87 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.
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:
When the connector framework receives this outcome status, it copies the APPRESPONSETIMEOUT status into the return-status descriptor and returns this descriptor to inform the connector controller that the application is not responding. Once it has sent this return-status descriptor, the connector framework stops the process in which the connector runs. A system administrator must fix the problem with the application and restart the connector to continue processing events and business object requests.
During request processing, the connector framework copies the outcome status into the status field of the return-status descriptor and includes this descriptor in its response to the integration broker. It continues execution of the connector. For some outcome-status values, the connector framework also includes a response business object in its response. For more information, see Updating the request business object.
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:
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 64 shows, this exception object contains a message and status, as well as an exception-detail object with additional information about the exception.
Table 88 shows the accessor methods that the CWException class provides to obtain information in the exception object.
Member | Accessor method |
---|---|
Message text | getMessage() |
Status | getStatus(), setStatus() |
Exception-detail object | getExceptionObject() |
The exception-detail object is an instance of the CWConnectorExceptionObject class. As Figure 64 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 89 shows.
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() |
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 65 shows a code fragment from the default implementation of the pollForEvents() method that catches the exceptions that the getBO() method throws.
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.
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:
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:
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.
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 90 lists the status information that this structure provides.
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.