raiseException()

Prepare a collaboration exception to raise to the next higher level of execution.

Syntax

void raiseException(String exceptionType, String message)
 void raiseException(String exceptionType, int messageNum, 
       String parameter[,...])
 void raiseException (String exceptionType, int messageNum, 
       Object[] paramArray)
 void raiseException(CollaborationException exceptionObject)
 

Parameters

exceptionType
The exception type for the exception to be raised. Specify this exception type as one of the following exception-type static variables, which identify the cause of the collaboration exception:

AnyException
Any type of exception

AttributeException
Attribute access problem. For example, the collaboration called getDouble() on a String attribute or called getString() on a nonexistent attribute.

JavaException
Problem with Java code in collaboration logic.

ObjectException
Business object passed to a method was invalid or a null object was accessed.

OperationException
Service call was improperly set up and could not be sent.

ServiceCallException
Service call failed. For example, a connector or application is unavailable.

SystemException
Any internal error within the InterChange Server system.

TransactionException
Error related to the transactional behavior of a transactional collaboration. For example, rollback failed or the collaboration could not apply compensation.

message
A text string that contains the exception message.

messageNum
The message number of a message in the collaboration's message file, which is indexed by message number. For information on how to set up a message text file, refer to Creating a message file.

parameter
A value for a single message parameter. There can be up to five message parameters, separated by commas. Each is sequentially resolved to a parameter in the message text.

paramArray
An array of message-parameter values. Each is sequentially resolved to a parameter in the message text.

exceptionObject
The name of a CollaborationException exception-object variable.

The following explanations and code examples need to be provided in the Collaboration API:

Notes

The raiseException() method prepares a collaboration exception to raise to the next higher level of execution. When the collaboration runtime environment executes the raiseException() call, it changes the collaboration's execution to the Exception state, then proceeds with the logic of the activity diagram. How the activity diagram responds to the raised exception depends on the termination node of its execution path, as follows:

It is best to explicitly raise an exception when one occurs, rather than to just end in failure. When the code explicitly raises the exception to the collaboration runtime environment, the administrator can use the Flow Manager to view the exception text as part of the unresolved flow. For more information, see Raising the exception.

The raiseException() method has several forms:

Note:
All forms of the method that take a messageNum parameter require the use of a message file indexed by message number. For information on how to set up a message text file, refer to Creating a message file.

Examples

This section provides examples of each of the forms of the raiseException() method:

  1. The following example uses the first form of the method to raise an exception of ServiceCallException type. The text is passed directly into the method call.
    raiseException(ServiceCallException, "Attempt to validate 
     Customer failed.");
     
  2. The next example uses the second form of the method to raise an exception of OperationException type, whose message appears in the message file is as follows:
    23
     Customer update failed for CustomerID={1} CustomerName={2} 
     

    This raiseException() call retrieves message 23 and retrieves the values of the message's two parameters (customer ID and name) from the fromCustomer variable to generate the exception message:

    raiseException(OperationException, 23, 
        fromCustomer.getString("CustomerID"),
        fromCustomer.getString("CustomerName"));
     
  3. The following example uses the third form to send message-parameter values as an array of Objects.

    For example, assume the message file includes the following message text:

    2000
     Collaboration Message: BOName: {1} with Verb: {2} encountered 
     an undefined error.
     

    The following code creates a parameter array of Objects, loads values into it, and calls the raiseException() method:

    Object[] myParamArray = new Object[2];
      
     myParamArray[0] = triggeringBusObj.getType();
     myParamArray[1] = triggeringBusObj.getVerb();
      
     raiseException(AnyException, 2000, myParamArray);
     
  4. The final example uses the fourth form of the method to raise a previously handled exception. The system-defined variable currentException is the exception object that contains the exception.
    raiseException(currentException);
     

Copyright IBM Corp. 2003, 2004