Monitoring Workflow Exceptions

This section explains how to monitor workflow exceptions, including the following topics:

• Overview of Exception Handling

• Creating a Workflow Exception

• Getting Workflow Exception Information

• Invoking a Workflow Exception Handler

For information about monitoring workflow exceptions using the WebLogic Integration Studio, see Handling Workflow Exceptions in Using the WebLogic Integration Studio.

 

---

Overview of Exception Handling

The BEA WebLogic Integration exception handling facility enables you to generate, trap, and respond to generated exception conditions at run time. Exception handling is performed at the workflow level, rather than the task level.

The following sections describe workflow exceptions and exception handlers. For more information about exception handling, see Handling Workflow Exceptions in Using the WebLogic Integration Studio.

Workflow Exception

Workflow exceptions are either abnormal conditions that you define within a workflow, or typical run-time server exceptions that you trap and handle accordingly. A workflow exception may be thrown in response to one of numerous conditions, each of which is associated with an appropriate severity level.

The following table describes the levels of severity defined for workflow exceptions, including the severity code integer equivalents.

Table 24-1 Workflow Exception Severity Levels  

Severity Level	Severity Code	Description
System error	ERROR_SYSTEM (1)	Fatal exception occurred during processing of a user request.
Workflow error	ERROR_WORKFLOW (2)	Fatal, illegal condition occurred, such as inconsistent workflow state.
Workflow warning	WARNING_WORKFLOW (3)	Nonfatal workflow condition occurred; the user can rectify it manually.
Unknown error	ERROR_UNKNOWN (0)	System-specific error occurred; information about it is available for internal use only.
Custom error	ERROR_CUSTOM (4)	Custom error raised either by an application calling the com.bea.wlpi.server.worklist.Worklist.invokeWorkflowExceptionHandler() method or by the Invoke Error Handler action within the Studio.

The com.bea.wlpi.common.WorkflowException object encapsulates a workflow exception that has occurred during the execution of a remote EJB call.

Exceptions are sent to the wlpiError JMS topic. For more information about connecting to JMS, see Establishing JMS Connections.

Workflow Exception Handler

All workflow template definitions specify at least one exception handler, the system exception handler. The system exception handler is, by default, the initial exception handler; it is invoked whenever an exception occurs. You can also define custom exception handlers. The active exception handler for a workflow template definition can be changed repeatedly in the course of the workflow.

 

---

Creating a Workflow Exception

The following table lists the constructors for creating a new WorkflowException object.

Table 24-2 WorkflowException Object Constructors

This Constructor	Creates a . . .
public WorkflowException (java.lang.Exception e)	Workflow exception containing a nested exception. The specified exception is assigned the ERROR_SYSTEM severity, unless it belongs to the WorkflowException class, in which case the new exception inherits its severity from the nested exception.
public WorkflowException (java.lang.Exception e, int severity)	Workflow exception containing a nested exception with the specified severity. For a list of valid severity levels, see the table Workflow Exception Severity Levels.
public WorkflowException( java.lang.Exception e, int msgNum, int severity)	Workflow exception containing a nested exception with the specified message code and severity. For a list of valid message codes, see the com.bea.wlpi.common.Messages Javadoc. For a list of valid severity levels, see the table Workflow Exception Severity Levels.
public WorkflowException( java.lang.Exception e, int msgNum, java.lang.Object[] args)	Workflow exception containing a nested exception with the specified message code and a list of arguments for substitution into a localized message string. For a list of valid message codes, see the com.bea.wlpi.common.Messages Javadoc.
public WorkflowException( java.lang.Exception e, int msgNum, java.lang.Object[] args, int severity)	Workflow exception containing a nested exception with the specified message number, a list of arguments for substitution into a localized message string, and a message severity. For a list of valid message codes, see the com.bea.wlpi.common.Messages Javadoc. For a list of valid severity levels, see the table Workflow Exception Severity Levels.
public WorkflowException(int msgNum)	Workflow exception with the specified error code. The specified exception is assigned the ERROR_SYSTEM severity, by default. For a list of valid message codes, see the com.bea.wlpi.common.Messages Javadoc.
public WorkflowException(int msgNum, java.lang.Object[] args)	Workflow exception with the specified error code and list of arguments for substitution into a localized message string. The specified exception is assigned the ERROR_SYSTEM severity, by default. For a list of valid message codes, see the com.bea.wlpi.common.Messages Javadoc.
public WorkflowException(int msgNum, int severity)	Workflow exception with the specified error code and severity level. For a list of valid message codes, see the com.bea.wlpi.common.Messages Javadoc. For a list of valid severity levels, see the table Workflow Exception Severity Levels.
public WorkflowException(int msgNum, java.lang.Object[] args, int severity)	Workflow exception with the specified error code, a list of arguments for substitution into a localized message string, and a message severity. For a list of valid message codes, see the com.bea.wlpi.common.Messages Javadoc. For a list of valid severity levels, see the table Workflow Exception Severity Levels.
public WorkflowException(int msgNum, java.lang.Object[] args, int severity, java.lang.String origin)	Workflow exception with the specified error code, a list of arguments for substitution into a localized message string, a message severity, and message origin. For a list of valid message codes, see the com.bea.wlpi.common.Messages Javadoc. For a list of valid severity levels, see the table Workflow Exception Severity Levels.

 

 

---

Getting Workflow Exception Information

The following sections explain how to get information about a workflow exception (such as severity, message text, message number, origin, and whether or not the workflow exception was caused by a deadlock) and how to print a stack trace.

Getting the Workflow Exception

To get the original or nested workflow exception, use the following com.bea.wlpi.common.WorkflowException methods, respectively:

public java.lang.Exception getOriginalException()

public java.lang.Exception getNestedException()

The first method returns the original workflow exception. The second method returns the nested workflow exception, or null, if no nested workflow exception exists.

For example, the following code gets the nested workflow exception for a given workflow exception:

try {
   // some methods;
}
catch(WorkflowException e) {
   Exception nested e.getNestedException();
}

For more information about the getOriginalException() and getNestedException() methods, see the com.bea.wlpi.common.WorkflowException Javadoc.

Getting the Severity

To get the message severity for a workflow exception, use one of the following com.bea.wlpi.common.WorkflowException methods:

Method 1

public java.lang.String getSeverity()

Method 2

public java.lang.String getSeverityDescription()

Method 3

public java.lang.String getLocalizedSeverityDescription()

The first method returns the message severity code as an integer value. The second method returns the message severity value as a string value. The third method returns the localized message severity code as a string value. For information about severity level values and codes, see the table Workflow Exception Severity Levels.

For example, the following code gets the message severity code for a given workflow exception:

try {
   // some methods;
}
catch(WorkflowException e) {
   String severity e.getSeverity();
}

For more information about the getSeverity() method, see the com.bea.wlpi.common.WorkflowException Javadoc.

Getting the Message Text

To get the message text associated with a workflow exception, use one of the following com.bea.wlpi.common.WorkflowException methods:

Method 1

public java.lang.String getMessage()

Method 2

public java.lang.String getLocalizedMessage()

The first method returns one of the following: the message text associated with a nested message, if available; the message text in the language of the system locale from which the exception was thrown; or null if no message text was created.

The second method returns the localized message text, if available, the message text in the language of the system locale from which the exception was thrown, or null, if no message text was created.

For example, the following code gets the message text for a given workflow exception:

try {
   // some methods;
}
catch(WorkflowException e) {
   String message e.getMessage();
}

For more information about the getMessage() or getLocalizedMessage() method, see the com.bea.wlpi.common.WorkflowException Javadoc.

Getting the Message Number

To get the message number for a workflow exception, use the following com.bea.wlpi.common.WorkflowException method:

public java.lang.String getMessageNumber()

For example, the following code gets the message text for a given workflow exception:

try {
   // some methods;
}
catch(WorkflowException e) {
   String number e.getMessageNumber();
}

For more information about the getMessageNumber() method, see the com.bea.wlpi.common.WorkflowException Javadoc.

Getting the Origin

To get the origin (workflow component) from which the workflow exception originated, use the following com.bea.wlpi.common.WorkflowException method:

public java.lang.String getOrigin()

For example, the following code gets the origin text for a given workflow exception:

try {
   // some methods;
}
catch(WorkflowException e) {
   String origin e.getOrigin();
}

For more information about the getOrigin() method, see the com.bea.wlpi.common.WorkflowException Javadoc.

Determining Whether a Workflow Exception Resulted from a Database Deadlock

To determine whether or not the workflow exception resulted from a deadlock, use one of the following com.bea.wlpi.common.WorkflowException methods:

Method 1

public boolean isDeadlock()

Method 2

public static boolean isDeadlock(java.lang.Exception e)

Each method returns true if the workflow exception resulted from a database deadlock, and false otherwise.

The second method calls the getOrginalException() method to retrieve the original exception. If the original exception is an instance of java.sql.SQLException, the method calls the getSQLState() method to determine whether the original problem was a database deadlock.

For example, the following code determines whether a method is deadlocked for a given workflow exception:

try {
   // some methods;
}
catch(WorkflowException e) {
   String boolean e.isDeadlock();
}

For more information about the isDeadlock() methods, see the com.bea.wlpi.common.WorkflowException Javadoc.

Printing the Stack Trace

To print a stack trace, use one of the following com.bea.wlpi.common.WorkflowException methods:

Method 1

public void printStackTrace()

Method 2

public void printStackTrace(java.io.PrintStream stream)

Method 3

public void printStackTrace(java.io.PrintWriter writer)

Each method prints the workflow exception and its back-trace. The first method prints the information to the standard error stream (System.err); the second, to the specified print stream; and the third, to the specified print writer.

The first line of the output contains the result of calling the toString() method for this object. The remaining content represents the data previously recorded by the fillInStackTrace() method. If the workflow exception contains a nested workflow exception, the method prints its stack trace, as well.

For example, the following code prints the stack trace for a given workflow exception:

try {
   // some methods;
}
catch(WorkflowException e) {
   e.printStackTrace();
}

For more information about the printStackTrace() methods, see the com.bea.wlpi.common.WorkflowException Javadoc.

 

---

Invoking a Workflow Exception Handler

To invoke a workflow exception handler for a workflow instance, use one of the following com.bea.wlpi.server.worklist.Worklist methods:

Method 1

public java.lang.String invokeWorkflowExceptionHandler(
  java.lang.String templateDefinitionId,
  java.lang.String instanceId,
  java.lang.String handlerName,
  java.lang.String xml
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

Method 2

public java.lang.String invokeWorkflowExceptionHandler(
  java.lang.String templateDefinitionId,
  java.lang.String instanceId,
  java.lang.String handlerName,
  java.lang.String xml,
  java.lang.Object transactionId
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the invokeWorkflowExceptionHandler() method parameters for which you must specify values.

Table 24-3 invokeWorkflowExceptionHandler() Method Parameters  

Parameter	Description	Valid Values
templateDefinitionId	ID of the workflow template definition for which you are invoking the error handler.	Valid template definition ID. To get the template definition ID, use the following com.bea.wlpi.common.TemplateDefinitionInfo method: public final String getId() For more information about the methods available to the TemplateDefinitionInfo object, see TemplateDefinitionInfo Object.
instanceId	ID of the workflow instance.	ID of the workflow instance corresponding to the template definition. To get the instance ID, use the following com.bea.wlpi.common.TemplateDefinitionInfo method: public final String getInstanceId() For information about getting the TemplateDefinitionInfo object, see Getting Workflow Instances. For more information about the methods available to the TemplateDefinitionInfo object, see TemplateDefinitionInfo Object.
handlerName	Name of the error handler to invoke.	Valid error handler.
xml	User-defined subtree.	XML document defining a subtree.
transactionId	ID of the transaction. Note: This parameter is required only in a clustered environment.	Object specifying a unique transaction ID. To generate a unique transaction ID, create a new com.bea.wlpi.client.common.GUID object using the following constructor: GUID transactionId = new GUID(); For more information about the GUID class, see the com.bea.wlpi.client.common.GUID Javadoc.

This method returns an XML document that is compliant with the Client Request DTD, ClientReq.dtd, as described in Client Request DTD. The XML document contains information about the running instance, and can be accessed by parsing the document using an XML parser, such as a SAX (Simple API for XML) parser. For example implementations of a SAX parser, see Examples of Managing Run-Time Tasks.

For example, the following code invokes the error handler, MyErrorHandler, passes the user-defined tree via the myXml string variable, and stores the resulting XML document to the clientReq variable. In this example, worklist represents the EJBObject reference to the Worklist EJB.

String clientReq = worklist.invokeWorkflowExceptionHandler(
  definition.getId(), instanceID, "MyErrorHandler", myXml);

The template definition ID is obtained using the methods associated with the com.bea.wlpi.common.TemplateDefinitionInfo object, definition. An InstanceInfo object can be obtained using the methods described in Getting Workflow Instances. The instanceID can be obtained using the InstanceInfo object methods.

For more information about the com.bea.wlpi.common.TemplateDefinitionInfo methods, see TemplateDefinitionInfo Object. For more information about the com.bea.wlpi.common.InstanceInfo methods, see InstanceInfo Object.

For more information about the invokeWorkflowExceptionHandler() methods, see the com.bea.wlpi.server.worklist.Worklist Javadoc.