
      Release Notes for JPublisher (JPub) 11.1


This file contains important information about version 11.1 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 11g 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 <install>
   2. SEVERAL FREQUENTLY ASKED QUESTIONS ABOUT JPUB <faq>
   3. NEW FEATURES IN THIS VERSION <newfeatures>
   4. BUGS FIXED IN JPUB <bugfixes>
   5. KNOWN BUGS AND RESTRICTIONS <knownbugs>


      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.

With SQLJ code generation mode, 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.

With JDBC code generation mode, JPub 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 11.1 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 11g SQLJ Developer's Guide and Reference
    * the Oracle 11g JDBC Developer's Guide and Reference
    * the Oracle 11g 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/ojdbc5.jar (require JDK 1.5).
          o On Windows platforms, these file names are written:
          o ORACLE_HOME\jdbc\lib\ojdbc5.jar (require JDK 1.5), 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.
    * Optionally, for SQLJ code generation mode, include in your
      CLASSPATH the file ORACLE_HOME/sqlj/lib/runtime12.jar. 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/ojdbc5.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 from the OTN website below.

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

Second, extract downloaded archive under ORACLE_HOME. The dbwsa.jar and
dbwsclientws.jar, dbwsclientdb101.jar, dbwsclientdb102.jar, and
dbwsclientdb11.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 scott/tiger -r -v -f  dbwsclientws.jar dbwsclientdb101.jar
    , for Oracle 10.1 databases
    
    loadjava -u scott/tiger -r -v -f dbwsclientws.jar dbwsclientdb102.jar
    , for Oracle 10.2 databases
    
    loadjava -u scott/tiger -r -v -f dbwsclientws.jar dbwsclientdb11.jar
    , for Oracle 11g databases


      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.

