Files related to this demo are in install_dir/COM/odi/demo/threads.


Threads Example
===============

This directory contains two thread examples.

These examples illustrate the use of ObjectStore in multi-threaded
applications where the threads cooperate, which means they belong
to the same session.

Data Model
==========

Institution: This is a persistence-capable class. An institution is identified
by its name and is stored as a database root. An Institution object contains a
vector of account holders. Account holders are represented by another
persistence-capable class called Account.

Account: This is a persistence-capable class that contains information about
account holders.

Load: This class is responsible for creating a database when a database is 
needed and it does not exist. The database gets its data from a flat file 
called bankData.txt. This file must be present in the current directory.

Banking1: This is the main module for one of the thread examples. It contains
another class called Compute, which is derived from Thread. In the main thread,
the example initializes ObjectStore, opens a database and starts a transaction.
When both the threads are done the transaction is committed and database is
closed. Each thread displays appropriate account information obtained in the 
thread.

Banking: This is the main module for the second thread example. it contains
another class called Teller, which is derived from Thread. In the main thread,
the example initializes ObjectStore and opens a database. The example starts
each Teller as a thread. Each Teller then performs activities such as creating
accounts, updating accounts, and removing accounts. Each of these activities
starts and ends its own transaction because such activities should be atomic.
Although the example does not illustrate this, the transactions can overlap.
Each thread displays appropriate account information obtained from the open
database. When activity in the Teller threads is complete the main thread 
closes the database and exits the application. Java "synchronized" is used
to make sure that only one of the threads performs a transaction at any one time.

bankData.txt: Contains data that is used by the Load object to create a database
for the examples. In terms of columns, the structure of this file is :
0-20(name) 22-23(age) 25-33(ssn) 35-43(type) 45-55(Amount)
Each line here represents new account holders data.

actionData.txt: Contains action to be performed by threads named Teller1, 
Teller2, Teller3. This file must be present in the current directory. In terms
of columns, the structure of this file is :
1-6(Teller name) 8(Activity) 10-18(ssn).
Activities could be : 1 = READ, 2 = ADD, 3 = UPDATE, 4 = REMOVE.
This file is used by Banking.java. 


Prerequisites For Running the Applications
==========================================

Before running the program, you need an additional entry in your
CLASSPATH environment variable.  You must already have two
ObjectStore related entries in your CLASSPATH: an entry for the
"osji.zip" file in order to use ObjectStore,
and a second entry for the "tools.zip" file in order
to use the class file postprocessor and other database tools.

You must add another entry to the CLASSPATH variable to build and run
the demo programs. This entry names the ObjectStore installation
directory, and enables ObjectStore to locate the annotated demo 
classes when the demo is run.

For example, on Solaris, if you place the ObjectStore distribution into 
/opt/ODI/osji, you need the following additional entry:

  CLASSPATH=/opt/ODI/osji/osji.zip:/opt/ODI/osji/tools.zip:
   /opt/ODI/osji

On Windows, if you place the ObjectStore distribution into
c:\odi\osji, you need this entry:

  CLASSPATH=c:\odi\osji\osji.zip;c:\odi\osji\tools.zip;
   c:\odi\osji

Compliling and Running the Program
==================================

Compile the program: first go to the directory COM/odi/demo/threads, and
then enter "javac *.java". 

Before running the demo you must run the class file postprocessor to
make the classes work persistently.  You can run the postprocessor as
follows.  Be sure that the "bin" directory that contains the osjcfp
executable is in your path as noted in the toplevel README.

   osjcfp @cfpargs

Running the osjcfp command line above results in annotated class
definitions being created in the current directory.

These programs run as two separate Java applications. These programs take a
Database name as the value of the tellerDB system parameter.

Here are typical command lines:

java -DtellerDB=teller.odb COM.odi.demo.threads.Banking
java -DtellerDB=teller.odb COM.odi.demo.threads.Banking1

The argument is the pathname of the database. 

Your configuration might be set up so that the ObjectStore Server
requires a user name and password to run this program. If it is,
you can specify a user name and password on the command line with
the -D option (/d for Microsoft jview):

java -DCOM.odi.user=your_user_name -DCOM.odi.password=your_password \
     -DtellerDB=teller.odb COM.odi.demo.threads.Banking


If the database does not exist the example creates the database and if
the database exists then the application uses the existing database.

Sample output from the first command appears below. When you run this
demo, you might see these lines of text in some other order.

Main Account with ssn :90391234 Added.
Main Account with ssn :90393949 Added.
Main Account with ssn :20093929 Added.
....
Main Account with ssn :19012346 Added.
Main Account with ssn :19012346 Added.
Teller2 Name :Jack
Teller2 AGE :2
Teller2 SSN :90393949
Teller2 Account Type :Savings
Teller2 Balance :900.0
Teller3 Account for ssn:60894836 does not exist
...
Teller1 Name :New60894834
Teller1 AGE :36
Teller1 SSN :60894834
Teller1 Account Type :Savings
Teller1 Balance :1000.0
Teller2 Account with ssn :19090909 Removed.
...
Teller3 Account with ssn :60894836 Added.
Teller1 Account with ssn :20093929 updated.
Teller2 Name :New60894836
Teller2 AGE :36
Teller2 SSN :60894836
...
Teller3 SSN :60894834
Teller3 Account Type :Savings
Teller3 Balance :1000.0
END THREAD :Teller2
Teller1 Name :Tom
Teller1 AGE :3
Teller1 SSN :20093929
Teller1 Account Type :Checkin
Teller1 Balance :89000.0
END THREAD :Teller1
Teller3 Name :New60894836
Teller3 AGE :36
Teller3 SSN :60894836
Teller3 Account Type :Savings
Teller3 Balance :1000.0
END THREAD :Teller3

And the expected output of the second command is:

Children Name :Amy
Children AGE :9
Children SSN :90391234
Children Account Type :Savings
Children Balance :10000.0
...
Children Name :J5
Children AGE :5
Children SSN :19012346
Children Account Type :Savings
Sum Name :Amy
Sum AGE :9
Sum SSN :90391234
Sum Account Type :Savings
Sum Balance :10000.0
...
Sum Name :J5
Sum AGE :5
Sum SSN :19012346
Sum Account Type :Savings
Children Balance :19000.0
Children Name :John
Children AGE :2
Children SSN :19012346
Children Account Type :Savings
Children Balance :21345.0
Number Of Accounts having More than $10K 8
Sum of amount in Accounts having More than $10K 335027.0
END THREAD :Children
Sum Balance :19000.0
Sum Name :John
Sum AGE :2
Sum SSN :19012346
Sum Account Type :Savings
Sum Balance :21345.0
Number Of children having More than $10K and age less than 10 8
END THREAD :Sum