
README FILE FOR JPublisher (JPub) 8.1.7.0.0
-------------------------------------------
 
This file contains important information about version 8.1.7.0.0
of the Java Publisher utility, or JPub for short.

JPub generates Java source code that makes it easy for you to represent
Oracle Object types and PL/SQL packages in your SQLJ and Java programs.
JPub is documented in  the _Oracle 8i JPublisher User's Guide_.
Additional information about JPub is found in the _Oracle 8i SQLJ
Developer's Guide and Reference_.  Some of the comments in this README
file presume that you have seen the JPub documentation.

These notes are divided into four sections:
 
* Section 1 describes how to install and invoke JPub.

* Section 2 answers several frequently asked questions about JPub.
 
* Section 3 lists new features in this version.

* Section 4 lists known bugs and restrictions.
 

SECTION 1: HOW TO INSTALL AND INVOKE JPub
-----------------------------------------

JPub is a Java program.  It is shipped with Oracle SQLJ.  If you
have installed SQLJ, you have installed JPub.

JPub requires SQLJ because:

* JPub optionally generates .sqlj code, which must be compiled by SQLJ
* JPub itself is a SQLJ program, so it requires the SQLJ runtime.

JPub communicates with the database via JDBC.  To run JPub, you must
also install a JDBC driver.  If you are using Oracle objects, an
Oracle 8.1.x JDBC driver is required.

By default, JPub communicates with the Oracle database using the
Oracle JDBC OCI driver, but you may select another driver, such as
the Oracle "thin" driver, by setting the -url command-line parameter.

For information on installing SQLJ and JDBC, see:
* the SQLJ Developer's Guide and Reference
* the Oracle 8i JDBC Developer's Guide and Reference
* the SQLJ README file
* the JDBC README file


To install JPub, follow the SQLJ installation steps, as described in
the SQLJ documents just mentioned. Here is a summary.

Let ORACLE_HOME be the location into which your Oracle products have
been installed.

* Include in your environment variable CLASSPATH the appropriate
  Oracle JDBC driver for your environment:
    ORACLE_HOME/jdbc/lib/classes111.zip (for JDK 1.1), or
    ORACLE_HOME/jdbc/lib/classes12.zip (for JDK 1.2).
  On Windows platforms, these file names are written:
    ORACLE_HOME\jdbc\lib\classes111.zip (for JDK 1.1), or
    ORACLE_HOME\jdbc\lib\classes12.zip (for JDK 1.2).

* Include in your CLASSPATH the file ORACLE_HOME/sqlj/lib/translator.zip.
  The translator.zip file contains the .class files for both SQLJ and JPub.

* Include in your CLASSPATH the file ORACLE_HOME/sqlj/lib/runtime.zip.
  The runtime.zip file contains the .class files for both SQLJ
  and JPub. Alternatively, if you use JDK 1.1 and Oracle JDBC 8.1.7
  you can instead specify the file ORACLE_HOME/sqlj/lib/runtime11.zip;
  or if you use JDK 1.2 or later and Oracle JDBC 8.1.7 you can instead
  specify the file ORACLE_HOME/sqlj/lib/runtime12.zip.

* Make sure that you can execute commands in the directory
  ORACLE_HOME/bin (or ORACLE_HOME\bin).  In Unix environments,
  this is accomplished by including the directory ORACLE_HOME/bin
  in your PATH environment variable.  The ORACLE_HOME/bin directory
  includes a wrapper script or executable to simplify the invocation
  of JPub.

To invoke JPublisher, say "jpub" followed by zero or more command-line
arguments.  If you do not provide any arguments, jpub will display
information about the available command-line arguments.


To use classes generated by JPub:

*  Include the file ORACLE_HOME/jdbc/lib/classes12.zip (for JDK 1.2)
   or the file ORACLE_HOME/jdbc/lib/classes111.zip (for JDK 1.1)
   in your CLASSPATH.

*  Using your SQLJ compiler, compile the .sqlj files generated by JPub.

*  Using your SQLJ or Java compiler, compile the .java files generated by JPub.

*  Include in your CLASSPATH the directories of the packages
   containing the .class files for the classes generated by JPub.


SECTION 2: JPub FREQUENTLY ASKED QUESTIONS 
------------------------------------------

Question:  Why can't I write Java classes by hand for my object types
and packages?

You can.  However, this is error-prone.

A Java class that represents an Oracle 8 object type in a JDBC program
must implement the oracle.sql.CustomDatum interface or the java.sql.SqlData
interface.  A Java class that represents an Oracle 8 object type in a
SQLJ program must also name the object type in a declaration within the
class of the form

  public static final String _SQL_NAME = "<name of object type>";

Code generated by JPub handles these tasks for you.  In addition, for both
object types and PL/SQL packages, JPub generates code to handle the details
of argument passing and method invocation when server methods are invoked.


Question:  I want to add some methods to a class generated by JPub.
           Should I edit the class generated by JPub, or write a
           new class that extends the one generated by JPub?

If you edit the class generated by JPub, and at some time in the future
you need to run JPub again to regenerate the class, you will have to
save the changes you made and reinsert them by hand.  It is probably
more convenient for you to extend the class generated by JPub.  When you
do this, you must tell JPub about the subclass you are writing using
the -input file syntax

TYPE <type name>
   AS <subclass name>
   GENERATE <name of JPub-generated class>

See your JPub documentation for more information on this feature.


Question: Can I get JPub to generate a class that implements the
          java.sql.SqlData interface?

Yes. JPub, the Oracle JDBC drivers, and Oracle SQLJ support your
choice of the oracle.sql.CustomDatum interface or the java.sql.SqlData
interface.


Question:  Can I override an option in the -props file by respecifying
           it on the command line?

Yes, by specifying it on the command line after the -props option.
Options are processed from left to right in the order in which they
appear on the command line.  Options in the -props file are processed
when the -props option is encountered on the command line.


Question:  I said "jpub -user=scott/tiger" without specifying any
           object types or packages for JPub to translate, but JPub
           not complain about this. What happened?

If the options -input, -sql, and -types are all absent, all types and
packages in the user's schema will be translated.


Question:  When do I need to specify the JPub -encoding option?

As a general rule, if you do not specify an -encoding option when you
invoke your Java compiler, you do not need to specify an -encoding option
when you invoke JPublisher.  If -encoding is not specified, the value of
the System property file.encoding is used.

The encoding option specifies the character encoding to use for the
input file generated by JPub, and for the .sqlj and .java files generated
by JPub.  The -encoding setting does not affect how the command line or
the -props file is read.


Question:  I'm happy with the way JPub translates my object types to Java,
           but I also want to use object types in C programs.  How can I
           accomplish this?

Another Oracle utility, the Object Type Translator (OTT), translates 
object types to C.


SECTION 3: NEW FEATURES IN JPub
-------------------------------

The following changes were made to JPub between version 8.1.6.0.0 and
version 8.1.7.0.0.

- The following fields have been made protected in JPub-generated
  code for SQL object types.  This provides for additional capabilites
  in user-written subclasses of the JPub-generated class.
  - _ctx - the SQLJ connection context object
  - _struct - the mutable struct object with the data in original SQL format

- The Java keyword "null" takes on special significance when used as the
  Java name for mapping attributes or methods.
  - no method will be generated when a SQL method is mapped to null
  - no getter/setter methods will be generated when a SQL attribute is
    mapped to null


SECTION 4: KNOWN BUGS AND RESTRICTIONS IN JPub
----------------------------------------------

JPub does not currently support the following PL/SQL argument types:

  BOOLEAN
  NCHAR
  NCLOB
  NVARCHAR2
  record types
  index-by tables
  strongly-typed REF CURSORs
 
  If you ask JPub to generate wrapper methods for server methods that use
  these types as argument types or result types, JPub will display error
  messages stating that you have used unsupported types, and JPub
  will generate in the .sql file comments containing partial code for
  the wrapper methods.


JPub reports most, but not all, errors in the -input file to the user.
A few errors in the -input file are not reported by JPub.
These errors are listed below:


* If the user requests the same Java class name for two different object
  types, the second class will silently overwrite the first.  For example,
  if the -input file contains

     type PERSON1 as person
     TYPE PERSON2 as person

  the file person.java will be created for type PERSON1, and then
  will be overwritten for type PERSON2.


* If the user requests the same attribute name for two different object
  attributes, get and set methods will be generated for both attributes
  without issuing a warning message.  Whether or not the generated class
  is legal in Java depends on whether the two get methods with the same
  name and the two set methods with the same name have different argument
  types so that they may be overloaded.


* If the user mentions a nonexistent object attribute in the TRANSLATE
  clause, it will be ignored without issuing a warning message.

  For example, if the -input file contains
 
    type PERSON translate X as attr1

  and X is not an attribute of PERSON,

  no warning message will be issued.
