Transaction Handling

Java Transaction Service

With JTS, you demarcate the transaction off of a transaction context, which you can retrieve from the TransactionService object. The transaction context contains the begin, commit, rollback, suspend, and resume methods. One of the disadvantages to JTS is that you cannot use a two-phase commit engine to coordinate changes to multiple databases. The advantage to JTS is that you can suspend and resume the transaction. Also, because it is specific to CORBA, you can use either Java or non-Java languages in your application.

This implementation of JTS does not manage distributed transactions. Transaction control distributed among multiple database servers, with support for the required two-phase commit protocol, is only available within the JTA implementation.

The JTS transaction API supplied with Oracle8i JServer manages only one resource: an Oracle8i database session. A transaction exists within only a single server, which means that it cannot span multiple servers or multiple database sessions in a single service. Transaction contexts are never propagated outside a server. If a server object calls out to another server, the transaction context is not carried along. However, a transaction can involve one or many objects. The transaction can encompass one or many methods within these objects.

Whether you demarcate the transaction on the client or the server, the following must occur:

Initialize the TransactionService object.

Oracle8i automatically initializes this object for any server objects; thus, only the client must explicitly initialize this object. The initialization is accomplished through the AuroraTransactionService.initialize method.
Retrieve the TransactionService object through the static TS.getTS method.
Retrieve the current transaction context through the TransactionService.getCurrent method.
Manage the transaction through the following transaction context (Current class) methods: begin, commit, rollback, rollback_only, suspend, resume.

JTS Client-Side Demarcation

The only difference between client and server-side demarcation is that the client must initialize the TransactionService object before retrieving it. The client initializes a TransactionService object on the intended server. Since JTS can only manage a transaction within a single server, the client should invoke server objects that exist only on that single server. In addition, any SQL statements executed against the database should also be solely applied to the same server.

The following example demonstrates the steps required for a client-side demarcation:

Initialize the TransactionService object. The initialization is accomplished through the AuroraTransactionService.initialize method.
Retrieve the TransactionService object through the static TS.getTS method.
Retrieve the current transaction context through the TransactionService.getCurrent method.
Manage the transaction through the following transaction context (Current class) methods: begin, commit, rollback, rollback_only, suspend, resume.

Example 7-5 Client-Side Demarcation for JTS Example

import employee.*;
import oracle.aurora.jndi.sess_iiop.ServiceCtx;
import oracle.aurora.jts.client.AuroraTransactionService;
import oracle.aurora.jts.util.*;
import javax.naming.Context;
import javax.naming.InitialContext;
import java.util.Hashtable;

public class Client
{
  public static void main (String[] args) throws Exception {
    if (args.length != 4) {
      System.out.println ("usage: Client serviceURL objectName user password");
      System.exit (1);
    }
    String serviceURL = args [0];
    String objectName = args [1];
    String user = args [2];
    String password = args [3];

    //The environment must be setup with the correct authentication 
    //and prefix information before you create the initial context
    Hashtable env = new Hashtable ();
    env.put (Context.URL_PKG_PREFIXES, "oracle.aurora.jndi");
    env.put (Context.SECURITY_PRINCIPAL, user);
    env.put (Context.SECURITY_CREDENTIALS, password);
    env.put (Context.SECURITY_AUTHENTICATION, ServiceCtx.NON_SSL_LOGIN);
    Context ic = new InitialContext (env);

    //provide the intial context and the service URL of the server
    AuroraTransactionService.initialize (ic, serviceURL);

    //Since JTS can only manage transactions on a single server, the
    //destination server object exists on the same server as the transaction
    //service. Thus, you use the same service URL to retrieve the object.
    Employee employee = (Employee)ic.lookup (serviceURL + objectName);
    EmployeeInfo info;

    //Use the static method getTS to retrieve the TransactionService and the
    //static method getCurrent to retrieve the current transaction context.
    //Off of the Current object, you can start the transaction with the begin
    //method. All three methods have been combined as follows:
    TS.getTS ().getCurrent ().begin ();

    //invoke a method on the retrieved server object. Since the object exists
    //on the transaction server, it is included in the transaction.
    info = employee.getEmployee ("SCOTT");
    System.out.println (info.name + " "  + " " + info.salary);
    System.out.println ("Increase by 10%");
    info.salary += (info.salary * 10) / 100;
    employee.updateEmployee (info);
    info = employee.getEmployee ("SCOTT");
    System.out.println (info.name + " "  + " " + info.salary);

    //Finally, commit the transaction with the Current.commit method.
    TS.getTS ().getCurrent ().commit (true);
  }
}

JTS Server-Side Demarcation

Oracle8i initializes the TransactionService for any server object. In the same manner as the client, the server must invoke only other server objects on the same server. SQL statements should also only be applied to the same database.

The following example demonstrates the steps required for a client-side demarcation:

Retrieve the TransactionService object through the static TS.getTS method.
Retrieve the current transaction context through the TransactionService.getCurrent method.
Manage the transaction through the following transaction context (Current class) methods: begin, commit, rollback, rollback_only, suspend, resume.

Example 7-6 Server-Side Demarcation for JTS Example

package employeeServer;

import employee.*;
import java.sql.*;
import oracle.aurora.jts.util.*;
import org.omg.CosTransactions.*;

public class EmployeeImpl extends _EmployeeImplBase
{
  Control txn;
  
  public EmployeeInfo getEmployee (String name) throws SQLError {
    //When the client invokes the getEmployee method, the transaction is started
    //Retreive the Transaction service through the static getTS method.
    //Retrieve the current transaction context through the getCurrent method.
    //And start the transaction with the Current.begin method. These have
    //been combined into one statement....
    TS.getTS ().getCurrent ().begin ();

    //Retrieve the employee information given the employee name.
    int empno = 0;
    double salary = 0.0;
    #sql { select empno, sal into :empno, :salary from emp
                    where ename = :name };

    //At this point, we suspend the transaction to return the employee
    //information to the client.
    txn = TS.getTS().getCurrent().suspend();
    return new EmployeeInfo (name, empno, (float)salary);
  }

  public void updateEmployee (EmployeeInfo employee) throws SQLError {
    //After the client retrieves the employee info, it invokes the updateEmp
    //method to change any values.
    //The transaction is resumed in this method through the Current.resume,
    //which requires the Control object returned on the suspend method.
    TS.getTS().getCurrent().resume(txn);

    //update the employee's information.
    #sql { update emp set ename = :(employee.name), sal = :(employee.salary)
                    where empno = :(employee.number) };

    //Once finished, complete the transaction with the Current.commit method.
    TS.getTS ().getCurrent ().commit (true);
 }

JTS Limitations

The implementations of JTS that is supplied for this Oracle8i release is intended to support client-side transaction demarcation. It has limitations that you should be aware of when designing your application.

No Distributed Transactions

Resources

The JTS transaction API supplied with Oracle8i JServer manages only one resource: an Oracle8i database session. A transaction cannot span multiple servers or multiple database sessions in a single service.

Transaction contexts are never propagated outside a server. If a server object calls out to another server, the transaction context is not carried along.

However, a transaction can involve one or many objects. The transaction can encompass one or many methods of these objects. The scope of a transaction is defined by a transaction context that is shared by the participating objects. For example, your client can invoke one or more objects on the same server within a single session or several objects on the same server within multiple sessions.

Nested Transactions

Nested transactions are not supported in this release. If you attempt to begin a new transaction before committing or rolling back any existing transaction, the transaction service throws a SubtransactionsUnavailable exception.

Timeouts

Methods of the JTS that support transaction timeout, such as setTimeout(), do not work in this release. You can invoke them from your code, and no exception is thrown, but they have no effect.

Interoperability

The transaction services supplied with this release do not interoperate with other OTS implementations.