Handling Aborted Transactions in Jaguar

Feb. 1, 1999 12:00 AM

In this article we'll examine how to handle a Jaguar CORBA_TRANSACTION_ROLLEDBACK exception that is thrown when a Jaguar transaction is aborted. We'll use the BTFBank sample application developed in an article I wrote for PBDJ in October 1999 (Vol. 6, issue10). This example is written in PowerBuilder, but the technique covered here is relevant for any Jaguar client (Java, Web, etc.) or Jaguar component that's involved in a transaction.

When developing a Jaguar component that uses Jaguar transactions, a CORBA_TRANSACTION_ROLLEDBACK exception is generated each time a transaction managed by the Jaguar server is aborted and rolled back. A transaction is marked as requiring a ROLLBACK by a PowerBuilder component's invoking the SetAbort function on the TransactionServer object.

This exception is thrown when the method that's called on a Jaguar component causes the transaction to be rolled back. In a PowerBuilder client this exception is captured by the connection object error event. If the exception isn't handled, the client application will terminate. As a result of throwing the exception, the method return value and any arguments passed by reference (output parameters) are unusable, making it difficult to handle such situations gracefully.

This situation is best illustrated with an example. In our BTFBank example we were able to deposit, withdraw and transfer money from a bank account. In this example a withdrawal of money was canceled if the account didn't have enough funds or wasn't found, or if the SQL to update the database failed. In all cases the SetAbort function was invoked to terminate the transaction. However, in the last article we didn't return a very useful message that would indicate to the client that called the withdrawal why it had failed. The code in Listing 1 modifies the function to accept by reference a string argument in which a message can be returned to be displayed to the user.

On the BTFBank client window we can make the following changes to the call to the withdraw method on the account component so the message returned by the method call is displayed with a MessageBox.

// Withdraw command button
int li_rc
int li_acct, li_tellerid
decimal ld_amount
string ls_msg
li_tellerid = Integer(sle_tellerid.text)
li_acct = Integer(sle_withdraw_account.text)
ld_amount = Real(sle_withdraw_amount.text)
li_rc=in_account.withdraw(li_acct, ld_amount, ls_msg)
IF li_rc <> 1 THEN
MessageBox("BTFBank",ls_msg)
END IF

After making these changes we can run the example. However, you'll notice that after attempting to withdraw too much money from an account, you don't get your error message. Instead, you get the CORBA_TRANSACTION_ROLLEDBACK exception as shown in Figure 1.
Figure 1: CORBA_TRANSACTION_ROLLEDBACK exception

Handling the Aborted Transaction
As a result of throwing the exception, the withdraw method return value and any arguments passed by reference (output parameters) aren't available, since the values aren't sent to the client. In order to allow return parameters to be marshaled and accessible by the client, we need to set a component property on the Jaguar server. The property, com.sybase.jaguar.component.tx_outcome, needs to be added to the account component through the Component Properties dialog on the All Properties tab, as shown in Figure 2.

The tx_outcome property isn't listed in the All Properties list, but is available to the component and set to "always" by default, which tells the Jaguar server to throw a CORBA TRANSACTION_ROLLEDBACK exception when a transaction is rolled back. In order to add the property click on the Add button, which will open the dialog shown in Figure 3, type com.sybase.jaguar.component.tx_ outcome into the Property Name field and type failed into the Property Value field.

A value of "failed" tells the Jaguar server not to throw a CORBA TRANSACTION_ROLLEDBACK exception when the component issues a SetAbort. This allows the component to raise a different exception or pass back values to the client.

Once the information is added, click the OK button. The tx_outcome property will be visible in the Component Properties dialog on the All Properties tab. Once the property is added, refresh the package or server through the Jaguar Manager and retest the application. When a withdrawal of too much money is attempted, the transaction is aborted and the error message is displayed on the client, as shown in Figure 4.

Conclusion
A method that results in an aborted transaction will throw the CORBA_ TRANSACTION_ROLLEDBACK exception. To avoid throwing the exception and to access the return value or output parameters on a method that's part of an aborted transaction, the Jaguar Component property com.sybase.jaguar.component.tx_outcome must be set to failed for each component on the Jaguar server using the Jaguar Manager. After setting the property, be sure to refresh the component. The BTFBank sample code used in this article is available on my Web site at www.erols.com/m.barlotta under Code Samples.