README FILE FOR JPublisher (JPub) 9.2.0.1.

0 Production
------------------------------------------------------
This file contains important information about version 9.2.0.1.0
Production 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 9i JPublisher User's Guide_.
Additional information about JPub is found in the _Oracle 9i 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 bugs that have been fixed in this version.
* Section 5 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 9.2.0 JDBC driver is recommended, and 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 Oracle 9i SQLJ Developer's Guide and Reference
* the Oracle 9i 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.
The installation process will create a script file (a shell script
on Unix platforms, and a .bat script on Windows platforms) that
directly includes references to the Java JRE, the JDBC driver,
and the SQLJ translator that has been installed. You should be
able to just invoke this script by typing
jpub
on the command line. If you have downloaded JPublisher from the
Oracle website as part of the SQLJ product, then this script
will not have been automatically created and customized for you.
In this case you should perform the steps outlined below.
* Include in your environment variable CLASSPATH the appropriate
Oracle JDBC driver for your environment:
ORACLE_HOME/jdbc/lib/classes111.jar (for JDK 1.1), or
ORACLE_HOME/jdbc/lib/classes12.jar (for JDK 1.2).
On Windows platforms, these file names are written:
ORACLE_HOME\jdbc\lib\classes111.jar (for JDK 1.1), or
ORACLE_HOME\jdbc\lib\classes12.jar (for JDK 1.2).
* Include in your CLASSPATH the file ORACLE_HOME/sqlj/lib/translator.jar.
The translator.jar file contains the .class files for both SQLJ and JPub.
* Include in your CLASSPATH the file ORACLE_HOME/sqlj/lib/runtime11.jar
(for JDK 1.1), or ORACLE_HOME/sqlj/lib/runtime12.jar (for JDK 1.2).
The runtime files contains runtime .class files for both SQLJ
and JPub. Alternatively, you can use ORACLE_HOME/sqlj/lib/runtime.jar
(this setting would be required if you are using an 8.1.7 or older
JDBC driver). ;
* 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.jar (for JDK 1.2)
or the file ORACLE_HOME/jdbc/lib/classes111.jar (for JDK 1.1)
in your CLASSPATH.
* Using your SQLJ compiler, compile the .sqlj or .java files generated
by JPub. If JPub has only generated .java files, you can also use
your Java compiler for creating .class files.
* Include in your CLASSPATH the directories of the packages
containing the .class files for the classes generated by JPub.
If you have compiled your classes from .sqlj source files, you
must also provide the SQLJ runtime11.jar (or runtime12.jar) in
your CLASSPATH in order to run your program.

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 object type in a JDBC program
must implement the oracle.sql.ORAData interface or the java.sql.SqlData
interface. A Java class that represents an Oracle 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 use subclasses that extend the classes generated
by JPub. When you do this, you must tell JPub about the subclass you
want to use with the -input file syntax
SQL <type name>
AS <subclass name>
GENERATE <name of JPub-generated class>
or you can use the command-line syntax
-sql=<type name>:<subclass name>:<name of JPub-generated class>
As of version 9.2, JPub even generates a first version of this
subclass for you - all you need to do is edit the generated file.
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.ORAData interface or the java.sql.SqlData
interface. By default, JPub generates to the oracle.sql.ORAData
interface. You request java.sql.SqlData by specifying
-usertypes=oracle
In addition, for backwards compatibility with Oracle8i
JDBC drivers, JPub can also generate to the oracle.sql.CustomDatum
interface. You obtain this by using the following setting
-compatible=CustomDatum
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 9.0.1.0.0 and
version 9.2.0.1.0.
JPublisher now supports virtually all of the types that can be
used by the Oracle JDBC driver. Additionally, JPublisher facilitates
the use of PL/SQL types in stored procedure and object method
signatures through PL/SQL conversion support.
The following Oracle JDBC types are now directly supported:
- NCHAR types
- TIMESTAMP types
- SQLJ object types
- SQL opaque types; specifically
SYS.XMLTYPE via oracle.xdb.XMLTypes.
 SQL opaque types can be supported through a predefined type
correspondence or they can trigger JPublisher code generation.
Native PL/SQL types can now be more easily accessed by JPublisher
code through the automatic generation of PL/SQL wrapper functions
and procedures in conjunction with the following mechanisms:
- predefined type conversions, such as between PL/SQL BOOLEAN
and Java boolean, or INTERVAL and String
- user-defined mappings for PL/SQL index-by-tables in conjunction
with the JDBC-OCI driver
- user-defined conversion functions for mapping PL/SQL record types
and tables of records to SQL object and collection types and Java
JPublisher provides improved functionality as well as flexibility in
the code it generates and reduces programming effort further.
- JPub generates attribute-based constructors for SQL object types.
- New APIs are provided in the generated classes to convert between
strongly typed Refs and to transfer connection information between
objects.
- Generated Java wrappers for SQL object types can be made
serializable (new option -serializable)
- JPub can create toString() methods that report the object
value (new option -tostring)
- When requesting user-subclassing of JPub-generated classes, a
first version of the user classes will be automatically generated.
- Inheritance hierarchies now require no initialization by the
user application.
- Generated files will not be clobbered unnecessarily, improving
interaction with Makefile environments.
- Extended syntax for JPublisher properties files permits multi-line
option settings and the embedding of JPub directives in SQL scripts.
- JPublisher permits publishing of individual or selected top-level
functions.

The following changes were made to JPub between version 8.1.7.0.0 and
version 9.0.1.0.0.
- JPublisher now only generates SQLJ code for an Object type if
that type contains methods. Otherwise it will generate Java
code by default (unless you use the option setting
-methods=always).
- The JPub-generated code now provides abstraction from the
specifics of the JPublisher implementation. The following
protected methods are provided as a replacement for the
previously accessible _struct and _ctx fields:
getConnection() - to obtain the JDBC connection
 getConnnectionContext() - to obtain the SQLJ context
create(Object,Datum,int) - for re-using the superclass-provided
implementation for a factory interface
setFrom(Object), setValueFrom(Object) - to transfer internal
state from another object
User-written classes for JPublisher 8.1.7 must be rewritten
to use these methods. Alternatively, you can use the backwards
compatibility setting -compatible=8i.
- By default JPublisher now uses SQLJ connection contexts of type
sqlj.runtime.ref.DefaultContext rather than creating and using
inner context classes _Ctx. This behavior can be adjusted
with the -context command line option.
- By default JPubllisher generates all wrapper classes into the
current directory. Previously, it would generate the wrapper
classes into a package hierarchy under the current directory.
To get this behavior you now need to explicitly specify the
setting "-dir=."
- JPublisher will translate SQL Object types that stand in an
inheritance relationship into a similar Java class hierarchy.
In addition, JPublisher will also generate initialization code
to create a type map that reflects this hierarchy.
Users just need to create an instance of the leaf types to ensure
that this initialization is performed.
- With the setting -usertypes=oracle, JPublisher now generates Java
classes that implement the interface oracle.sql.ORAData.
The new command line option -compatible=CustomDatum can be used
to generate classes for the backward compatible interface
oracle.sql.CustomDatum.
- The new JPublisher option -access permits control over the access
modifier of JPublisher-generated methods, and the new option
-context permits control over the class that is used for
SQLJ connection context (sqlj.runtime.ref.DefaultContext by
default), and also whether indiviual Java wrapper classes declare
their own individual SQLJ context types or not.
- JPublisher can now connected to the database with DBA authentication,
using the username SYS or INTERNAL.

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: BUGS FIXED IN JPub Release 9.2.0
-------------------------------------------
2116164 JPublisher could throw a NullPointerException when
publishing top-level procedures and functions.
1757898 When you use JPublisher to generate Java code for a SQL
Object type hierarchy where some classes add method
definitions while others do not, JPublisher will now
generate all classes into .sqlj files (unless the option
-methods=false was specified). This ensures that the
generated files are compatible with one another.
n/a JPub now supports the following SQL argument types which
are also supported by JDBC 9.2 and/or SQLJ:
- OPAQUE types
- SQLJ object types
- TIMESTAMP types
- NCHAR
- NCLOB
- NVARCHAR2
n/a JPub can now support the PL/SQL argument types, either
automatically, or through a user-provided type conversion
between the PL/SQL type and a corresponding SQL type.
- BOOLEAN
- record types
- index-by tables

The following issues were addressed in JPublisher release 9.0.1.0.0

1691446 In 8.1.7 JPublisher implicitly created SQLJ connection context
instances. Unfortunately, the 8.1.7 SQLJ runtime was not able
to properly free these when the object they were attached to
got garbage-collected. In 9.0.1 you have four options to remedy
this bug:
- use JDK 1.2 and the SQLJ runtime12.jar
- use the SQLJ translator option -codegen=oracle
- explicitly issue setConnectionContext() on your objects
- explicitly issue release() before your objects go out
of scope.
1534649 JPub did not generate code for PL/SQL packages if no package
body existed. This happened, for example, if the package
header was created in advance of the implementation and then
JPublisher was run to generate a .sqlj wrapper class for
this package.
1497108 Changes on nested object attributes were not properly recognized
by the JPub runtime. This resulted in lost update when the
object with the modified attribute was written back to the
database.

1418893 Running JPub on a single procedure or function failed to add the

declaration for _ctx, so the generated SQLJ file did not compile.
1364448 JPub did not read the last line of the inputfile when that line
 was not terminated by LF or by CR/LF.

SECTION 5: KNOWN BUGS AND RESTRICTIONS IN JPub

----------------------------------------------
n/a If you see the following JPublisher warning message.
Warning: Cannot determine what kind of type is XXXX. YYYY.
You likely need to install SYS.SQLJUTL. The database returns:
ORA-06550: line 1, column 7:
PLS-00201: identifier 'SYS.SQLJUTL' must be declared
ORA-06550: line 1, column 7:
PL/SQL: Statement ignored
then you are using JPublisher against an Oracle 9.2 database
that is not Java enabled. In general you can ignore this
message, unless you want to use SQL opaque types or SQLJ
object type.
You can get rid of this message by installing the package
SQLJUTL into the SYS schema. This package is defined in
the following SQL script file.
[Oracle Home]/sqlj/lib/sqljutl.sql
n/a JPublisher does not accept the following syntax:
jpub -u scott/tiger -s TOPLEVEL:TopLevel
Use instead:
jpub -u scott/tiger -s TopLevel
n/a The Java code that JPublisher generates to represent strongly
typed instances of REFs permits you to create Java Refs using
the empty constructor. However, calling getValue() or setValue()
on such an instance results in a NullPointerException.
You must always obtain a Java Ref instance from the database
(or as an attribute of a database object).
1851361 When running JPublisher 8.1.7 against an 8.1.6 database, it may
fail with an "invalid column name error.
In this case JPublisher is not backwards compatible when looking
up database metadata. As a workaround you can do one of the
following.
(1) Use the JPublisher version that came with your database.
(2) Use JPublisher from Oracle 9.0.1 or later. It generally
provides backward compatibility to 8i databases.
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.