Oracle8i CORBA Developer's Guide and Reference Release 3 (8.1.7) Part Number A83722-01 |
Library | Service | Contents | Index

## 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`

### 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");

### Using The Java Transaction Service

JTS 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. JTS methods should be used in CORBA clients server objects.

The following sections describe the JTS APIs:

- Required Import Statements

- Java Transaction Service Methods

- Current Transaction Methods

#### Required Import Statements

To use the JTS methods, include 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 retrieve the transaction service.

#### Java Transaction Service Methods

The JTS includes the following methods:

    public static synchronized TransactionService getTS()

1. The `getTS` method returns a transaction service object.

2. 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.

3. Finally, 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:

- `HeuristicMixe`d--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 `HeuristicMixe`d and `HeuristicHazard` exceptions are documented in 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.

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index