Using a Custom Exception Handler

 

In this section we focus on the Studio's exception handling facility, by showing an example of a user-defined exception handler used by the Order Fulfillment workflow. After an overview that describes all the nodes in the workflow, this section describes how to:

• Define a custom exception handler and its actions

• Invoke a custom exception handler

• Evaluate a condition to catch a specific exception

• Send an XML message to a client to correct run-time errors

In this section of the tutorial, it is assumed that you have imported the Order Fulfillment workflow, the Create OrderBean and Calculate Total Price business operations, and the cancelledorder event key, as described in Importing Workflow Objects: Importing the Tutorial Package File.

 

---

Overview of the Order Fulfillment Workflow

The Order Fulfillment workflow, called by the Order Processing workflow, contains tasks to handle the shipping and invoicing of the ordered item. Because both tasks in the workflow are to be executed in parallel, both are connected directly to the start node. To ensure that both tasks are executed before the workflow terminates, an AND node joins them together.

The workflow also defines and invokes a custom exception handler to prompt a Worklist user to correct the invalid state abbreviation that was provided in the original XML document in the Order Processing Trigger workflow.

A detailed view of the Order Fulfillment workflow is shown in the following figure. The numbered steps in the figure are described in a table following the figure. The table maps the real-world processes to the actual implementation in the sample workflow.

Figure 6-1 Order Fulfillment Workflow: Detailed View

 

Table 6-1 Order Fulfillment Workflow Summary

Process	Implementation
If the inventory is sufficient, the order is forwarded simultaneously to a shipping agent who arranges shipment, and an accounting agent who instructs the system to generate an invoice for the order.	1. The start node is defined as Called, and the workflow is set off when the Start Order Fulfillment task of the Order Processing workflow is executed.
	2. A manual task is assigned to the Shipping role, with a comment providing shipping information for the order. Once the task is marked done, the Watch for Cancellation event is also cancelled so that the order (and the workflow) can no longer be cancelled.
If the system encounters an error in processing the input necessary to calculate the total price for the invoice, including state sales tax, the accounting agent who initiated the billing process is notified and prompted to provide the correct information.	3. A manual task is assigned to the Accounting role. The workflow exception handler is set to a custom-defined exception handler, which sends an XML message to the accounting agent, prompting him/her to enter the correct state to which this order should be shipped. The response is sent back in an XML message, and passed as a parameter to an EJB method that calculates the total price, including the sales tax.
	4. A Join node ensures that the workflow proceeds only when both the Ship Order and Generate Invoice tasks are marked done.
	5. The workflow terminates, and the corrected state data and the total price are returned to the variables of the Order Processing workflow.
At any point in the transaction before shipping, the order can be cancelled by notification from the customer. In a real-world implementation, an event would be set up to react to an XML message posted to an external JMS queue by a servlet.	6. An event and event key are set up to react to a hypothetical <cancelledorder> XML message including the relevant order ID. If the event is triggered, the workflow proceeds to the done node and is terminated.

 

 

---

About the Exception Handlers

All WebLogic Integration workflow template definitions contain a default exception handler: the system exception handler. The system exception handler responds to exceptions that occur at run time by marking the active transaction for rollback only and rethrowing the exception to the client.

You can also define custom exception handlers to perform workflow actions upon the occurrence of an exception. You can configure the custom exception handler to catch any exceptions that occur at run time, or to handle specific exceptions that have been defined in called EJBs. To define your custom exception handler, you specify commit and rollback actions to be performed for the active transaction. (See About Exception Handler Actions.)

An exception handler exists at the workflow level, so that it can be called from within any node. After you have defined an exception handler, you use one of two actions to invoke it from within a node:

• Set Workflow Exception Handler—This deactivates the system exception handler and sets the exception handler to the one you specify for the duration of the workflow. The exception handler actions will only be invoked if an exception is actually thrown. If desired, you can use this action to reset the exception handler to the system exception handler.

• Invoke Exception Handler—This invokes the actions defined in the exception handler that you specify, at that point in the workflow, regardless of whether an exception actually occurs. The system exception handler is reset when control returns to the main workflow.

You can create and view existing exception handlers from both the folder tree and on the Exception Handlers tab of the template definition's Properties dialog box.

To view the exception handler defined for the Order Fulfillment workflow in the folder tree:

1. In the folder tree, expand the Order Fulfillment template, right-click the template definition, and from the pop-up menu, select Open to open the workflow.

2. In the folder tree, expand the Exception Handlers folder. It appears as shown in the following figure.

   Figure 6-2 Order Fulfillment Workflow: Exception Handlers

   
    

   This workflow contains one user-defined exception handler: Bad Data to OrderBean.

3. To identify the location from which the Bad Data to OrderBean exception handler is invoked, right-click its folder in the folder tree, and from the pop-up menu, select Usage. The Exception Handler Usage dialog box appears.

   Figure 6-3 Exception Handler Usage Dialog Box

   
    

   As the window shows, the custom exception handler is invoked from the Generate Invoice node. We will now examine this node more closely before viewing the Bad Data to OrderBean exception handler's properties in detail.

4. Click OK to close the Exception Handler Usage dialog box.

 

---

Viewing the Generate Invoice Task

Let us first view the actions that make up the Generate Invoice task, including the calls to business operations and to the Bad Data to OrderBean custom exception handler.

To view the Generate Invoice task properties:

1. In the workflow design window, double-click the Generate Invoice task to open the Task Properties dialog box. The Activated tab contains an action that assigns the task to the role Accounting.

2. Select the Executed tab.

   Figure 6-4 Generate Invoice Task Properties Dialog Box: Executed Tab

   
    

The Executed tab contains the following actions:

• Set exception handler to "Bad Data to OrderBean"—This is an exception handling action that sets the user-defined exception handler for the duration of the workflow from this point on, until another exception handler is set by the workflow. The exception handler definition itself is described in detail in Defining a Custom Exception Handler: Viewing the Bad Data to OrderBean Exception Handler.

• Perform business operation "Create OrderBean"—This is the same integration action we used in Performing the Create OrderBean Business Operation before calling the checkInventory() method on the POBean. It creates an instance of the EJB on the server at run time.

• Perform Business Operation "Calculate Total Price"—This is an integration action that calls the calculate() method on the POBean and is described in more detail in Viewing the Calculate Total Price Business Operation.

• Set exception handler to "(system exception handler)"—This is an exception handling action that resets the workflow exception handler back to the system exception handler which is in effect, by default, for all workflows at execution time.

• Mark task "Generate Invoice" done—This is the task action that completes the Generate Invoice task. When the Shipping task is also marked done, the workflow proceeds to the done node and the workflow terminates.

 

---

Viewing the Calculate Total Price Business Operation

Double-click the Perform Business Operation "Calculate Total Price" action to display its properties.

Figure 6-5 Calculate Total Price: Perform Business Operation Dialog Box

 

The calculate() method returns the total price, including state sales tax, to the variable OrderTotalPrice.

To get more information about the calculate() method, let us look at the business operation configuration.

To view the Calculate Total Price business operation configuration:

1. Click Cancel to close the Perform Business Operation dialog box.

2. Click Cancel to close the Task Properties dialog box.

3. Choose Configuration—>Business Operations. The Business Operations dialog box appears.

4. In the list of business operations, double-click the Calculate Total Price business operation. The Define Business Operation dialog box appears.

   Figure 6-6 Calculate Total Price: Define Business Operation Dialog Box

   
    

   You can see that in the Method to Call field, the calculate() method throws an exception, BadStateException. In the EJB class file, this exception is defined to occur if invalid state data is passed to the method. In the source code, invalid state data is any text that does not match a valid two-letter abbreviation for a U.S. state name.

   To handle the possibility of this exception being thrown, the Bad Data to OrderBean exception handler is set up in the workflow to correct the error at run time. We look at this exception handler in more detail in the following sections.

   Note: For more information on the POBean.jar EJB, see the BEA WebLogic Integration Javadoc.

5. Click Cancel to close the Define Business Operation dialog box.

6. Click Close to close the Business Operations dialog box.

 

---

Defining a Custom Exception Handler: Viewing the Bad Data to OrderBean Exception Handler

As you may recall from Understanding Workflow Objects and Properties, we simulated the occurrence of invalid data being passed to the POBean in the <shiptostate> value in the Neworder XML document that triggered the Order Processing workflow. That workflow set the ShipToState variable to an incorrect value, KK, which was passed by the Start Order Fulfillment task node to the Order Fulfillment workflow.

When the Generate Invoice task is executed, the Perform Business Operation action attempts to call the calculate() method with the wrong ShipToState variable value as input. Because the calculate() method of the POBean throws the BadStateException when the invalid state data is passed to it, the server invokes the custom-defined exception handler, Bad Data to OrderBean.

Let us now view the Bad Data to OrderBean exception handler and the actions defined within it.

To view the Bad Data to Order Bean exception handler:

1. In the folder tree, expand the Exception Handlers folder, right-click the Bad Data to Order Bean exception handler, and from the pop-up menu, select Properties. The Exception Handler Properties dialog box appears.

   Figure 6-7 Exception Handler Properties Dialog Box

   
    
    

About Exception Handler Actions

The Actions on Commit and Actions on Rollback tabs allow you to specify workflow actions to be executed on the transaction's commit and rollback paths. In most cases, the transaction is committed unless it has been specifically marked for rollback only; in this case, the exception handler executes the actions specified on the rollback tab. Although the called EJB method may mark transactions for rollback only, it is a good idea to specify both types of actions.

• Actions on Commit—You can specify any workflow action you like on this tab, including the Exit Exception Handler action, with the following options:

  • Exit and rollback

  • Exit and stop (do not process remaining operations)

  • Exit and retry (retry the failed operation)

  • Exit and continue (resume at the next operation)

• Actions on Rollback—The only available actions are Set Workflow Variable, Integration actions, Exit Exception Handler and Rollback, Send E-mail, No Operation, Evaluate Condition, or Make Audit Entry.

As you can see in the Exception Handler Properties dialog box, the Bad Data to OrderBean exception handler defines the following actions:

• Commit

  • Evaluate Condition—A miscellaneous action that tests for a particular condition in which to apply the exception handling actions, and that specifies true or false actions depending on the test results. It is described in more detail in Viewing the Evaluate Condition Action.

  • Exit Exception Handler and Continue—An exception handling action that stops the exception handler and attempts to continue the execution of the workflow at the next operation (in this case, the action following the business operation that caused the exception).

• Rollback

  Exit Exception Handler and Rollback—An exception handling action that stops the exception handler, rolls back the active transaction to its state before the exception was thrown, and rethrows the exception to the client.

 

---

Viewing the Evaluate Condition Action

To view the Evaluate Condition action, in the Exception Handler Properties dialog box, double-click the Evaluate Condition action. The Evaluate Condition dialog box appears.

Figure 6-8 Evaluate Condition Dialog Box

 

The condition is defined with the following expression:

WorkflowAttribute("ExceptionType") = "com.bea.wlpi.tour.po.BadStateException"

In this case, this expression uses the workflow attribute ExceptionType to test whether the exception thrown equals the BadStateException specified by the POBean. Using a condition like this is a common way to set up an exception handler to catch specific exceptions. You can use the WorkflowAttribute function to identify the target exception, with a number of different exception attributes, including:

• "ExceptionType" (String)—The fully qualified Java class name of the exception

• "ExceptionText" (String)—The exception message text

• "ExceptionObject" (Exception)—The exception object itself

For a complete list of workflow functions and attributes, see Using Workflow Expressions in Using the WebLogic Integration Studio.

The Evaluate Condition action specifies actions to execute according to the test result, that is, whether the expression evaluates to true or false. In this example the action specifies the following actions:

• True

  Send XML to Client—An integration action that sends an XML message to a Worklist user to prompt him or her to correct the invalid data that was passed to the calculate() method, and re-executes the Generate Invoice task. This action is described in detail in Viewing the Send XML to Client Action.

• False

  No actions are specified here; if the condition evaluates to false, the exception handler executes the Rollback actions specified in the Exception Handler Properties dialog box.

 

---

Viewing the Send XML to Client Action

The Send XML to Client action sends a message to a Worklist user, requesting correction of the bad data that has been passed to the POBean and caused the BadStateException to occur. Then it re-executes the actions specified on the Executed tab of the Generate Invoice Task Properties dialog box so that the task can now complete successfully.

To view the Send XML to Client action, in the Evaluate Condition dialog box, select the True tab, and double-click the Send XML to Client action. The Send XML to Client dialog box appears.

Figure 6-9 Bad Data to OrderBean Exception Handler: Send XML to Client Dialog Box

 

This Send XML to Client action sends an XML document, based on the ClientSetVarsReq DTD, to the Worklist client, causing the Worklist to display a message box with a field in which the Worklist user types information. The XML document has the following structure.

Listing 6-1 ClientSetVarsReq XML Document Structure

<set-variables title="text">
text
   <actionid>provided by default	</actionid>
   <variable name="variable name" prompt="text" />
   [<variable name="variable name" prompt="text" />]
</set-variables>

The following figure shows the tags and values in the XML document that correspond to the message box displayed by the Worklist client.

Figure 6-10 Error Warning Message Box

 

To capture the response from the Worklist user, data is extracted from the XML document returned by the Worklist client, based on the ClientSetVarsResp.dtd, specifically from the <variable name> attribute, as shown in Listing 6-2.

Listing 6-2 ClientMsgBoxResp XML Document Structure

<set-variables>
   <variable name="variable name" /> 
   [<variable name="variable name" />] 
</set-variables>

To extract the desired information, the following XPath expression is defined:

XPath("/set-variables/variable[@name=\"ShipToState\"]/text()")

Then the result is assigned to the ShipToState variable in the Callback Variables tab of the Send XML to Client dialog box.

Finally, a callback action is specified.

This action re-executes all the actions listed on the Executed tab of the Generate Invoice Task Properties dialog box (see Viewing the Generate Invoice Task) after the Worklist user has entered valid data. Note that if the user enters invalid data, he or she is repeatedly prompted with the message box until acceptable data is provided.

When the task is marked done by the final action of the Generate Invoice task, the workflow proceeds to the AND node. When the Ship Order task is marked done, the workflow terminates. At this point variable values that have been collected during the workflow execution are passed back to the Order Processing workflow.