Transaction Handling

Transaction Service Interfaces

Oracle8i supports a version of the JTS. The JTS is a Java mapping of the OMG Object Transaction Service (OTS). There are two classes that the application developer can use:

TransactionService
UserTransaction, implemented by oracle.aurora.jts.client.AuroraTransactionService

The section below describes the TransactionService interface. Because it is used with EJBs, the UserTransaction class is described in "AuroraUserTransaction".

TransactionService

Use the TransactionService to initialize a transaction context on the client. Include the AuroraTransactionService package in your Java client source with the following import statements:

import oracle.aurora.jts.client.AuroraTransactionService;
import javax.jts.*;
import oracle.aurora.jts.util.*;

These classes are included in the library file aurora_client.jar, which must be in the classpath when compiling and executing all source files that use the JTS.

There is only one method in this package that you can call:

public synchronized static void initialize(Context initialContext,
                                           String serviceName)

This method initializes the transaction context on a client. The parameters are:

serviceName

The complete service name. For example sess_iiop://localhost:2481:ORCL

An example of using initialize() is:

Hashtable env = new Hashtable();
env.put(Context.URL_PKG_PREFIXES, "oracle.aurora.jndi");
env.put(Context.SECURITY_PRINCIPAL, "scott");
env.put(Context.SECURITY_CREDENTIALS, "tiger");
env.put(Context.SECURITY_AUTHENTICATION, ServiceCtx.NON_SSL_LOGIN);
Context initialContext = new InitialContext(env);
AuroraTransactionService.initialize
          (initialContext, "sess_iiop://localhost:2481:ORCL");

See also the complete example in "clientside".

Using The Java Transaction Service

The JTS package itself contains methods that a client-side or server-side object uses to begin transactions, commit or roll back a transaction, and perform utility functions such as setting the transaction timeout. The JTS methods should be used in CORBA or EJB clients, or in CORBA server objects. Developers implementing EJBs, and who need fine-grained transaction control within beans should use the UserTransaction interface in a bean-managed state. See "Transaction Management for EJBs" for more information.

To use the JTS methods, code the following import statements in your source:

import oracle.aurora.jts.util.TS;
import javax.jts.util.*;
import org.omg.CosTransactions.*;

The oracle.aurora.jts.util package is included in the library file aurora_client.jar, which must be in the classpath for all Java sources that use the JTS.

You use the static methods in the TS class to get the transaction service.

Java Transaction Service Methods

The JTS includes the following methods:

public static synchronized TransactionService getTS()

getTS() returns a transaction service object. Once a transaction service has been obtained, you can invoke the static method getCurrent() on it to return a Current pseudo-object, the transaction context. Then you can invoke methods to begin, suspend, resume, commit, or roll back the current transaction on the Current pseudo-object.

Here is an example that begins a new transaction on a client, starting with getting the JNDI initial context:

import oracle.aurora.jndi.sess_iiop.ServiceCtx;
import oracle.aurora.jts.client.AuroraTransactionService;
import javax.naming.Context;
import javax.naming.InitialContext;
import java.util.Hashtable;
...
Context ic = new InitialContext(env);
...
AuroraTransactionService.initialize(ic, serviceURL);
...
Employee employee = (Employee)ic.lookup (serviceURL + objectName);
EmployeeInfo info;
oracle.aurora.jts.util.TS.getTS().getCurrent().begin();

If there is no transaction service available, then getTS() throws a NoTransactionService exception.

Current Transaction Methods

The methods that you can call to control transactions on the current transaction context are the following:

public void begin()

Begins a new transaction.

Can throw these exceptions:

NoTransactionService--if you have not initialized a transaction context.
SubtransactionsUnavailable--if you invoke a begin() before the current transaction has been committed or rolled back.

See the section "TransactionService" for information about initialization.


public Control suspend()

Suspends the current transaction in the session. Returns a Control transaction context pseudo-object. You must save this object reference for use in any subsequent resume() invocations. Invoke suspend() in this way:

org.omg.CosTransactions.Control c =
          oracle.aurora.jts.util.TS.getTS().getCurrent().suspend();

suspend() can throw these exceptions:

NoTransactionService--if you have not initialized a transaction context.
TransactionDoesNotExist--if not in an active transaction context. This can occur if a suspend() follows a previous suspend(), with no intervening resume().

If suspend() is invoked outside of a transaction context, then a NoTransactionService exception is thrown. If suspend() is invoked before begin() has been invoked, or after a suspend(), the a exception is thrown.


public void resume(Control which)

Resumes a suspended transaction. Invoke this method after a suspend(), in order to resume the specified transaction context. The which parameter must be the transaction Control object that was returned by the previous matching suspend() invocation in the same session. For example:

org.omg.CosTransactions.Control c = 
             oracle.aurora.jts.util.TS.getTS().getCurrent().suspend();
...   // do some non-transactional work
oracle.aurora.jts.util.TS.getTS().getCurrent().resume(c);

resume() can throw:

InvalidControl--if the which parameter is not valid, or is null.
```
public void commit(boolean report_heuristics)
```

Commits the current transaction. Set the report_heuristics parameter to false.

(The report_heuristics parameter is set to true for extra information on two-phase commits. Because this release of JServer does not support the two-phase commit protocol for distributed objects, use of the report_heuristics parameter is not meaningful. It is included for compatibility with future releases.)

commit() can throw:

HeuristicMixed--if report_heuristics was set true, and a two-phase commit is in progress.
HeuristicHazard--if report_heuristics was set true, and a two-phase commit is in progress.

The HeuristicMixed and HeuristicHazard exceptions are documented in the OTS specification. See "For More Information" for the location of the OTS specification.

If there is no active transaction, commit() throws a NoTransaction exception.


public void rollback()

Rolls back the effects of the current transaction.

Invoking rollback() has the effect of ending the transaction, so invoking any JTS method except begin() after a rollback() throws a NoTransaction exception.

If not in a transaction context, rollback() throws the NoTransaction exception.


public void rollback_only() throws NoTransaction {

rollback_only() modifies the transaction associated with the current thread so that the only possible outcome is to roll back the transaction. If not in a transaction context, rollback_only() throws the NoTransaction exception.


public void set_timeout(int seconds)

This method is not supported, and has no effect if invoked. The default timeout value is 60 seconds in all cases.


public Status get_status()

You can call get_status() at any time to discover the status of the current transaction. Possible return values are:

javax.transaction.Status.StatusActive
javax.transaction.Status.StatusMarkedRollback
javax.transaction.Status.StatusNoTransaction

The complete set of status ints is defined in javax.transaction.Status.


public String get_transaction_name() {

Invoke get_transaction_name() to see the name of the transaction, returned as a String. If this method is invoked before a begin(), after a rollback(), or outside of a transaction context, it returns a null string.