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:
Currently, JPub requires SQLJ because:
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:
Let ORACLE_HOME be the location into which your Oracle products have been installed.
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.
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.
First, download the webservice callout utility for 10g from the OTN website below.
ORACLE_HOME/sqlj/libThird, 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
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.
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
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.
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.