JTS Transaction Example

README

Overview
========

The serversideJTS example shows how to do transaction management for
CORBA server objects from the server object, using the XA JTS
methods.

Compare this example with the clientside example, in which all
transaction management is done on the client.

This example also shows a server object that uses SQLJ in its methods.



Source files
============

employee.idl
------------

The CORBA IDL for the example.  Defines:

An EmployeeInfo struct
A SQLError exception
An Employee interface, with
    EmployeeInfo getEmployee(in wstring name)
    EmployeeInfo getEmployeeForUpdate(in wstring name)
    void updateEmployee(in EmployeeInfo name)

The SQLError exception is used so that SQLException messages can 
be passed back to the client.  



Client.java
-----------

You invoke the client program from a command prompt, and pass it four
arguments, the

   - service URL (service ID, hostname, port, and SID if port is a listener)
   - name of the published server object to lookup and instantiate
   - username
   - password that authenticates the client to the Oracle8i database server

For example:
% java -classpath LIBs Client sess_iiop://localhost:2481:ORCL \
        /test/myEmployee scott tiger


where LIBs is the classpath that must include

$ORACLE_HOME/lib/aurora_client.jar
#If using Java 2, use classes12.zip instead of classes111.zip
$ORACLE_HOME/jdbc/lib/classes111.zip
$ORACLE_HOME/lib/vbjorb.jar
$ORACLE_HOME/lib/vbjapp.jar
$JAVA_HOME/lib/classes.zip

The client code is almost exactly the same as the code in
../clientside/Client.java, but without the JTS transaction calls.

The client code performs the following steps:

   - gets the arguments passed on the command line
   - creates a new JNDI Context (InitialContext())
   - initializes the Aurora transaction service
   - looks up the myEmployee CORBA published object on the server
       (this step also authenticates the client using NON_SSL_LOGIN and
        activates the server object)
   - gets and prints information about the employee SCOTT
   - decreases SCOTT's salary by 10%
   - updates the EMP table with the new salary by calling the updateEmployee()
        method on the employee object
   - gets and prints the new information

The printed output is:

Beginning salary = 3000.0
Decrease by 10%
Final Salary = 2700.0

Note that the starting value is taken from the EMP table when the 
example starts to run, so you may see a different salary amount. The new 
salary amount is written back to the database, and will be used as the 
new starting amount if you run this example again. 


employeeServer/EmployeeImpl.sqlj
--------------------------------

Implements the Employee interface.  This file implements the three
methods specified in the IDL: getEmployee(), getEmployeeForUpdate(),
and updateEmployee(), using SQLJ for ease of DML coding.

EmployeeImpl also adds two private methods, commitTrans() and
startTrans(), that perform XA JTS transaction management from the
server.

Note that on the server there is no need to call
AuroraTransactionService.initialize() to initialize the transaction
manager. This is done automatically by the server ORB. 

If the SQLJ code throws a SQLException, it is caught, and a 
CORBA-defined SQLError is thrown. This in turn would be 
propagated back to the client, where it is handled.



Compiling and Running the Example
=================================


UNIX
----

Enter the command 'make all' or simply 'make' in the shell to compile,
load, and deploy the objects, and run the client program.  Other
targets are 'run' and 'clean'.

Make sure that a shell environment variable ORACLE_HOME is set to
point to the home location of the Oracle installation. This is
operating system dependent, so see the Installation documentation that
came with your system for the location. Also, review the README file
for the Oracle database, and the README file for the CORBA/EJB server
(the Oracle8i ORB), for additional up-to-date information.


Windows NT
----------

On Windows NT, run the batch file makeit.bat from a DOS command prompt
to compile, load, and deploy the objects. Run the batch file runit.bat
to run the client program, and see the results.


Make sure that the environment variables %ORACLE_HOME%, %CLASSPATH%,
and %SERVICE% are set appropriately for the DOS command window. You
can set these as either user or system environment variables from the
Control Panel. Double click on System in the Control Panel then on
the Environment tab to set these variables. Start a new DOS window
after setting environment variable values.


See the Installation documentation that came with your Oracle8i system
for the values of these variables. Also, review the README file for
the Oracle database, and the README file for the CORBA/EJB server (the
Oracle8i ORB), for additional up-to-date information.

You can also set an environment variable %JAVA_HOME% to point to the
root of your Java JDK. For example, SET JAVA_HOME=C:\JDK1.1.6.

Employee.IDL

module employee {
  struct EmployeeInfo {
    wstring name;
    long number;
    double salary; 
  };

  exception SQLError {
    wstring message;
  };

  interface Employee {
    EmployeeInfo getEmployee (in wstring name) raises (SQLError);
    EmployeeInfo getEmployeeForUpdate (in wstring name) raises (SQLError);
    void updateEmployee (in EmployeeInfo name) raises (SQLError);
  };
};

Client.java

import employee.*;

import oracle.aurora.jndi.sess_iiop.ServiceCtx;

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];

    // get the handle to the InitialContext
    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);

    // This is using Server-side TX services, specifically, JTS/XA TX:

    // get handle to the object and it's info
    Employee employee = (Employee)ic.lookup (serviceURL + objectName);

    // get the info about a specific employee
    EmployeeInfo info = employee.getEmployee ("SCOTT");
    System.out.println ("Beginning salary = " + info.salary);
    System.out.println ("Decrease by 10%");
    // do work on the object or it's info
    info.salary -= (info.salary * 10) / 100;

    // call update on the server-side
    employee.updateEmployee (info);

    System.out.println ("Final Salary = " + info.salary);
  }
}

Server

package employeeServer;

import employee.*;
import java.sql.*;

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

public class EmployeeImpl extends _EmployeeImplBase 
{
  Control c;
 
  private void startTrans () throws SQLError {
    try {
      TS.getTS ().getCurrent ().begin ();
    } catch (Exception e) {
      throw new SQLError ("begin failed:" + e);
    }
  }

  private void commitTrans () throws SQLError {
    try {
      TS.getTS ().getCurrent ().commit (true);
    } catch (Exception e) {
      throw new SQLError ("commit failed:" + e);
    }
  }
  
  public EmployeeInfo getEmployee (String name) throws SQLError {
    try {
      startTrans ();

      int empno = 0;
      double salary = 0.0;
      #sql { select empno, sal into :empno, :salary from emp
	            where ename = :name };
      c = TS.getTS().getCurrent().suspend();
      return new EmployeeInfo (name, empno, (float)salary);
    } catch (SQLException e) {
      throw new SQLError (e.getMessage ());
    } catch (Exception e) {
      throw new SQLError (e.getMessage());
    }
  }

  public EmployeeInfo getEmployeeForUpdate (String name) throws SQLError {
    try {
      startTrans ();

      int empno = 0;
      double salary = 0.0;
      #sql { select empno, sal into :empno, :salary from emp
	            where ename = :name for update };
      return new EmployeeInfo (name, empno, (float)salary);
    } catch (SQLException e) {
      throw new SQLError (e.getMessage ());
    }
  }

  public void updateEmployee (EmployeeInfo employee) throws SQLError {
    try {
      TS.getTS().getCurrent().resume(c);

      #sql { update emp set ename = :(employee.name), sal = :(employee.salary)
                    where empno = :(employee.number) };
      commitTrans ();
    } catch (SQLException e) {
      throw new SQLError (e.getMessage ());
    } catch (Exception e) {
      throw new SQLError (e.getMessage ());
    }
  }
}

---