/* Copyright (c) Oracle Corporation 1999, 2000. */
/* All rights reserved */

This file is the README file for sample programs in the JPub demo directory.
It specifies the steps required to run each of the programs in this directory,
and their expected behavior.  All demos use the scott/tiger schema.

0. First, check your environment setup
**************************************

0.1 Modify the entries in "connect.properties" and "jpub.properties" to reflect
    the logon strings used for your JDBC driver and database account.

    The demo programs in the demo directory use information contained in the
    file "connect.properties" to establish a runtime connection.  In addition,
    the JPublisher utility uses information contained in the file "jpub.properties"
    to extablish a connection.


0.2 Make sure the JPub utility can be invoked from the command line, and produces
    the expected output:

% jpub
JPub: Java Object Type Publisher, version 8.1.7.0.0 Production

JPub generates Java or SQLJ source code for the following SQL entities:
   object types, collection types, and packages.

Invocation:
   jpub <options>

The following option is required: 
   -user=<username>/<password>

Other options are:
   -input=<input file>
   Types and packages to be processed by JPub may be listed in the -input file
   The contents of the -input file may be as simple as:
      SQL Person
      SQL Employee

   -sql=<sql entity list>
   Types and packages to be processed by JPub may also be listed using the -sql option
   For example, -sql=a,b:c,d:e:f is equivalent to the -input file entries:
      SQL a
      SQL b AS c
      SQL d GENERATE e AS f

   The following four options determine which Java types are generated
   to represent SQL user-defined, numeric, lob, and other types:
   -builtintypes=jdbc|oracle
   -lobtypes=oracle|jdbc
   -numbertypes=objectjdbc|jdbc|bigdecimal|oracle
   -usertypes=oracle|jdbc

   -case=mixed|same|lower|upper
   -dir=<base directory for generated Java files>
   -driver=<JDBC-Driver>
      (default: oracle.jdbc.driver.OracleDriver)
   -encoding=<Java encoding of -input file and generated files>
   -methods=none|named|all
   -omit_schema_names
   -package=<package-name>
   -props=<properties file from which to load options>
   -url=<JDBC-URL>
      (default: jdbc:oracle:oci8:@)


    If this expected output is not obtained, please check your environment
    settings for PATH and CLASSPATH:
       * PATH should include the directory .../sqlj/bin
       * CLASSPATH should include the file .../sqlj/lib/translator.zip

    In addition, a JDK 1.1-compatible Java compiler (assumed to be javac)
    and the java interpreter (assumed java) must be correctly installed.


0.3 Make sure that the SQLJ translator can be invoked from the command
    line prompt, and produces the expected output:

% sqlj
Usage:  sqlj [options] file1.sqlj [file2.java] ...
   or   sqlj [options] file1.ser  [file2.jar]  ...
where options include:
     -d=<directory>           root directory for generated binary files
     -encoding=<encoding>     Java encoding for source files
     -user=<user>/<password>  enable online checking
     -url=<url>               specify URL for online checking
     -status                  print status during translation
     -compile=false           do not compile generated Java files
     -linemap                 instrument compiled class files from sqlj source
     -profile=false           do not customize generated *.ser profile files
     -ser2class               convert generated *.ser files to *.class files
     -P-<option> -C-<option>  pass -<option> to profile customizer or compiler
     -P-help  -C-help         get help on profile customizer or compiler
     -J-<option>              pass -<option> to the JavaVM running SQLJ
     -version                 get SQLJ version
     -help-alias              get help on command-line aliases
     -help-long               get full help on all front-end options

Note:  place -<key>=<value> in sqlj.properties as sqlj.<key>=<value>

    If this expected output is not obtained, please check your environment
    settings, as described in section 0.2.


1. Next, run the sample programs in this directory.
***************************************************

Four rational number examples are provided, demonstrating three different
ways to do the same thing:

* "MyRationalC" uses a rational number object type.  The class JPub generates
  has no methods other than "get" and "set" accessor methods.  The user
  extends the class JPub generates and adds additional methods.

The other examples involve client wrapper methods that invoke server-side
PL/SQL methods:

* "RationalO" uses a rational number object type, with a few methods for
  manipulating the rational numbers.

* "RationalP" puts the rational number methods in a PL/SQL package.  A
   rational number type without methods provides arguments to the PL/SQL
   methods in the package.

* "MyRationalO" shows another example of extending a JPub-generated rational
  number class.

These examples are kept deliberately simple, so as not to obscure the
principles involved.

This directory contains the following files:
  README.txt            the file you are now reading

  Rational.sql          SQL script to create the object types Rational and RationalO
                        and the PL/SQL package RationalP

  MyRationalC.java      Source code for the class MyRationalC

  TestMyRationalC.java  Test program to demonstrate use of the class MyRationalC,
                        a hand-written class that extends the JPub-generated class
                        JPubRationalC

  TestRationalO.java    Test program to demonstrate use of the class RationalO, which
                        JPub generates to represent the RationalO type

  TestRationalP.java    Test program to demonstrate use of the class RationalP, which
                        JPub generates to represent the PL/SQL package RationalP
                        This test also uses the Rational class, which JPub generates
                        to represent the Rational type

  TestMyRationalO.java  Test program to demonstrate use of the class MyRationalO,
                        a hand-written class that extends the JPub-generated class
                        JPubRationalO.

  MyRationalO.java      Source code for the class MyRationalO

  connect.properties    used by the test programs when they connect

  jpub.properties       used by JPub when it connects


1.1 Run the Rational.sql SQL script to create the object types and the PL/SQL
    package used in these examples. (replace scott/tiger with your
    username/password values).

    % sqlplus scott/tiger @Rational.sql

1.2 Run the MyRationalC test.  In this test, JPub generates JPubRationalC.java.
    This class represents the database object type RationalO.  The hand-written
    class MyRationalC.java extends JPubRationalC by adding methods such as 
    toString() and plus().

    % jpub -props=jpub.properties -sql=RationalO:JPubRationalC:MyRationalC -mapping=jdbc -methods=none
    % javac JPubRationalC.java MyRationalC.java TestMyRationalC.java
    % java TestMyRationalC
 
    The expected output is:

    gcd: 5
    real value: 0.5
    sum: 100/100
    sum: 1/1

1.3 Run the RationalO test.  In this test, JPub generates RationalO.java.
    This class invokes server methods of the database object type RationalO,
    which represents rational numbers.

    % jpub -props=jpub.properties -sql=RationalO -methods=true
    % sqlj RationalO.sqlj TestRationalO.java
    % java TestRationalO

    The expected output is:

    gcd: 5
    real value: 0.5
    sum: 100/100
    sum: 1/1

1.4 Run the RationalP test.  This time, JPub generates a .java file for the
    class Rational, which represents the database object type of the same name.
    This Rational class has numerator and denominator attributes, but no methods.
    JPub also generates a .java file for the Java class RationalP, which 
    represents the PL/SQL package of the same name.  This package has methods
    to manipulate rational numbers .

    % jpub -props=jpub.properties -sql=RationalP,Rational -mapping=oracle -methods=true
    % sqlj RationalP.sqlj Rational.sqlj TestRationalP.java
    % java TestRationalP

    The expected output is:

    % real value: 0.50
    % gcd: 5
    % sum: 100/100
    % sum: 1/1

1.5 Run the MyRationalO test.  This test demonstrates how to extend a class
    generated by JPub.  This time, JPub generates JPubRationalO.java.  This
    class represents the database object type RationalO.  The hand-written
    class MyRationalO.java extends JPubRationalO by adding a toString()
    method.

    % jpub -props=jpub.properties -sql=RationalO:JPubRationalO:MyRationalO -methods=true
    % sqlj JPubRationalO.sqlj MyRationalO.java TestMyRationalO.java
    % java TestMyRationalO

    The expected output is:

    % gcd: 5
    % real value: 0.5
    % sum: 100/100
    % sum: 1/1

