Release Notes for JPublisher (JPub) 10.1.0.2.

This file contains important information about version 10.1.0.2.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 Java programs. JPub is
documented in the _Oracle 9i JPublisher User's Guide_. Some of the comments
in this README file presume that you have seen the JPub documentation.

These notes are divided into the following sections:

1. HOW TO INSTALL AND INVOKE JPUB

2. SEVERAL FREQUENTLY ASKED QUESTIONS ABOUT JPUB
3. NEW FEATURES IN THIS VERSION
4. BUGS FIXED IN JPUB
5. KNOWN BUGS AND RESTRICTIONS

1: INSTALL AND INVOKE JPUB

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

installed SQLJ, you have installed JPub.

Currently, JPub requires SQLJ because:

* JPub generates .sqlj code as intermediate files, which will be

compiled into .java code by the SQLJ translator

* JPub-generated code requires SQLJ runtime.

In the future, JPub may be decoupled from SQLJ, in that JPub would generate
.java code that does not depend on 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 JPublisher and JDBC, see:

* the Oracle 10g SQLJ Developer's Guide and Reference

* the Oracle 10g JDBC Developer's Guide and Reference
* the Oracle 10g JPublisher User's Guide

To install JPub, follow the JPublisher installation steps, as described in

the JPublisher User's Guide. Here is a summary.

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

1.1. INVOKE JPUB VIA jpub

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 followed by zero or more arguments. If you do not

provide any arguments, jpub will display information about the available
command-line arguments. The "jpub" script uses an installation-specific
CLASSPATH, i.e., the installation process hardcodes the CLASSPATH
environement variable for JPublisher in the "jpub" script based on the JDK
location detected during installation.

1.2. INVOKE JPUB VIA oracle.jpub.Doit

If you have downloaded JPublisher from the Oracle website as part of the
SQLJ product, then the "jpub" 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

o Oracle JDBC driver for your environment:
o ORACLE_HOME/jdbc/lib/classes12.jar (for JDK 1.2 and 1.3), or
o ORACLE_HOME/jdbc/lib/ojdbc14.jar (for JDK 1.4).
o On Windows platforms, these file names are written:
o ORACLE_HOME\jdbc\lib\classes12.jar (for JDK 1.2 and 1.3), or
o ORACLE_HOME\jdbc\lib\ojdbc14.jar (for JDK 1.4), or

* 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/runtime12.jar
(for JDK 1.2 or later). 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 SQLJ.

To invoke JPublisher, use the command

java oracle.jpub.Doit

followed by zero or more command-line arguments. The command above has the
same effect as the "jpub" command mentioned in Section 1.1, except that,
with the command above, JPublisher picks up the CLASSPATH setting in your
environment, while in the Section 1.1 case, the CLASSPATH variable picked
by JPublisher is pre-defined during installation.

1.3 AFTER GENERATION

To use classes generated by JPub:

* Include the file ORACLE_HOME/jdbc/lib/ojdbc14.jar (for JDK 1.4), the

file ORACLE_HOME/jdbc/lib/classes12.jar (for JDK 1.2 and JDK 1.3), and
ORACLE_HOME/sqlj/lib/runtime12.jar in your CLASSPATH.
* Include in your CLASSPATH the directories of the packages containing
the .class files for the classes generated by JPub.

Now you are ready to run JPub-generated code.

1.4 WEBSERVICES CALLOUT SETUP

JPublisher can generate webservices client and its PL/SQL wrapper, to

support webservice invocation inside the database. This functionality, also
called webservices callout, requires the following extra setup steps.

First, download the webservice callout utility for 10g from the OTN website
below.

http://otn.oracle.com/tech/webservices/database.html

Second, extract downloaded archive under ORACLE_HOME. The utl_dbws.jar and

utl_dbws_jserver.jar file will be added to the directory

ORACLE_HOME/sqlj/lib

Third, load the utl_dbws_jserver. jar file into the SYS schema or into the
schema where the webservice client will be invoked. For instance, to load
that jar file to SYS, use the loadjava command below.

loadjava -u sys/change_on_install -r -v -f -s -grant public

utl_dbws_jserver.jar

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.
3. NEW FEATURES IN JPUB

The following changes were made to JPub between verstion 10.1.0.0.0 and
10.1.0.2.0.

Using the "-proxywsdl" option, JPublisher can generate and load the
webservice client and the corresponding PL/SQL call specification into the
database, so that one can invoke the database webservice from the database.
This functionality is also called webservices callout.

When the option -omit-schema-names is set, JPublisher generates an

additional method __setSchemaName(String) for a SQL object type. The
purpose of the added method is to allow specifying the schema where the SQL
object type is located at runtime.

In previous JPublisher releases, with "-numbertypes=jdbc", the SMALLINT

type is mapped into "short". While SMALLINT contains 32 binary bits in the
database, the Java short type has 16 bits. Starting this release, SMALLINT
is mapped into Java "int". For backward compatibility, JPublisher provides
an option "-compatible=9i". When that setting and "-numbertypes=jdbc" is
specified, JPublisher will map SMALLINT into "short", as previous
JPublisher behave by default.

The -methods options supports two additional setting, "overload" and

"unique". The "overload" setting indicates that the method name in the
generated Java program can be overloaded, for instance, "int foo(int)" and
"int foo(String)". The "unique" setting means that every Java method
generated is uniquely named, for instance, "int foo(int)" and "int
fooiS(String)".

The "-plsqlfile" option specifies the PL/SQL wrapper file generated during
publishing PL/SQL stored procedure. Now the "-plsqlfile" can take second
argument, a file that holds the SQL script file to drop the generated
PL/SQL wrapper, for instance,

-plsqlfile=my_wrapper.sql,my_dropper.sql

Now JPublisher supports multiple -style options. If two mappings are

defined for the same source type,
the mapping appearing later takes effect.

For database webservics, JPubisher provides two predefined -style

templates, webservices9 and webservice10. With the setting
-style=webservices9, JPublisher generates code compatible to Oracle
Webservices in 10g(9.0.4) or earlier. With -style=webservices10, JPublisher
generates code compatible to Oracle Webservices 10g (10.0).

Previously, JPublisher does not acknowledge the CLASSPATH environment

variable. Starting from this release, JPublisher picks up the CLASSPATH
enviroment variable.

The SQLJ translator may be desupported in future releases. The following

JPublisher change and facilities strives to minimize the impact of future
SQLJ desupport.

In previous releases, JPublisher generates .java and .sqlj code. Starting

this release, JPublisher no longer generates .sqlj code. Instead,
JPublisher will generate .java code and .class file compiled from generated
.java code. Note that for this release, .sqlj programs are actually
generated,
translated and removed.

With the setting -compatible=sqlj, JPublisher will generate .sqlj as

previous releases and will not translate the .sqlj program generated. Also
with -compatible is set to 8i or 9i, JPublisher will also perserve the
behavior of JPublisher 8i or 9i releases, thus will allow .sqlj programs to
be
generated.

With the setting -compile=false, JPublisher will not compile generated

.java program into .class files. The default setting is -compile=true.

JPublisher now accepts the -classpath setting, which specifies the

classpath used for compiling generated Java programs.

JPublisher supports a new option, -compiler-executable, which specifies the

compile executable used for compiling generated Java programs.

With the setting -sqlj, JPublisher will use all the options following that
"-sqlj" setting as SQLJ options to translate .sqlj programs generated into
.java programs.

At the end of the JPublisher command line, one can specifies .sqlj or .java
programs to be translated and compiled along with JPublisher-generated
code. For instance,

jpub -u scott/tiger -s foo bar.java

The following changes were made to JPub between verstion 9.2.3.0.0 and
10.1.0.0.0.

JPublisher can publish SQL queries and DML statements via the option
"-sqlstatement". SQL queries and DMLs can be published as methods in a
generated Java class.

Using the "-java" option, given a Java class in the server (database),
JPublisher can generate a correpsonding client-side class which invokes the
static methods in that Java class.

Using the "-proxyclasses" option, JPublisher can create PL/SQL proxy for
Java classes. A typical scenario for the "-proxyclasses" functionality is
WebServices call-outs, where the web service calls originate from the
database.

Using the "-style" option, JPublisher can map an argument type into another
type in the generated user subclass. As an example, JPublisher can map a
returned ReultSet into an array of Java Beans, a XML document, or a
WebRowSet.

Using the "-filtermodes" and "-filtertype" options, JPublisher can prevent

certain PL/SQL methods from being published. The "-sql" option is enhanced
to support specifying certain methods to be or not to be published.

Using the "-generatebean" option, JPublisher can make sure the generated
Java classes for SQL types are Java beans.

The following changes were made to JPub between verstion 9.0.2.1.0 and
9.2.3.0.0.

JPublisher now can generate interfaces along with classes. For instance,
the command "jpub -sql=<sqlType>:<javaClass>#<javaInterface>:<myClass>"
generates, for a SQL type (<sqlType>), a java class (<javaClass>), a java
interface (<javaInterface>), and a user Java class (<myClass>), where
<javaInterface> defines the interface of <javaClass>. The generated
interface contains the public methods in the generated class, typically
those accessors methods.

JPublisher 9.2 permits publishing of individual or selected top-level

functions. JPublisher 9.2.3 generalizes function selection as follows:

- Functions and procedures can be selected from any PL/SQL package.

- The function names can end in the wildcard character "%" (the percent
sign). In this case, they will match functions that begin with the same
prefix.
- SQL argument signatures of the functions or procedures can be specified
as selection criteria.

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

4. BUGS FIXED IN JPUB

The following issues were addressed in JPublisher release 10.1.0.2.0.

3157214 When publishing PL/SQL stored procedures involving PL/SQL table on

certain platforms, JPublisher may throw "Exhausted ResultSet" error and
generate code that do not compile.

The following issues were addressed in JPublisher release 10.1.0.0.0.

1757898 In Oracle9i release 9.0.1, the option "-methods=true" results in

"Method not found" error during SQLJ translation if the published SQL
object or packages contain no methods.

The following issues were addressed in JPublisher 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.

5. KNOWN BUGS AND RESTRICTIONS IN JPUB

2395122 When publishing a package in a 817 database, the integer type in

the package is always mapped into java.math.BigDecimal, regardless of the
-numbertypes setting. When -numbertypes is set to be "jdbc", integer should
be mapped into the primitive java type "int".

2144086 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.