1 Introduction to JPublisher

New JPublisher Features in Oracle Database 10g

Key new JPublisher features in Oracle Database 10g can be categorized as follows:

• New Features for Web Services

• Awareness of Java Environment Classpath

• New Features for Usage of SQLJ

JPublisher Usage of the Oracle SQLJ Implementation

The following sections describe when and how JPublisher uses SQLJ, provide an overview of SQLJ, and discuss backward-compatibility modes that relate to the generation of SQLJ source files:

• Overview of SQLJ Usage

• Overview of SQLJ Concepts

• Backward Compatibility Modes Affecting SQLJ Source Files

JPublisher General Requirements

This section describes the base requirements for JPublisher, then discusses situations with less stringent requirements.

When you use the JPublisher utility, you must also have classes for the Oracle SQLJ implementation, the Oracle JDBC implementation, and a Sun Microsystems Java Developer's Kit (JDK), among other things.

To use all features of JPublisher, you must generally have the following installed and in your classpath, as applicable:

• Oracle Database 10g or Oracle9i database

• JPublisher invocation script or executable

  The jpub script (for UNIX) or jpub.exe program (for Microsoft Windows) must be in your file path. They are typically in ORACLE_HOME/bin (or ORACLE_HOME/sqlj/bin for manual downloads). With proper setup, if you type just "jpub" in the command line, you will see information about common JPublisher option and input settings.

• JPublisher and SQLJ translator classes

  These classes are in the library translator.jar, typically in ORACLE_HOME/sqlj/lib.

  
  

  Notes: The translator library is also automatically loaded into the database, intranslator-jserver.jar. The client-side translator library includes JPublisher client-side runtime classes, particularly oracle.jpub.reflect.Client for Java call-ins to the database. The database translator library includes JPublisher server-side runtime classes, particularly oracle.jpub.reflect.Server, also for Java call-ins to the database.

  
  

• SQLJ runtime classes

  The SQLJ runtime library is runtime12.jar, for JDK 1.2 or higher. It is typically located in ORACLE_HOME/sqlj/lib.

• Oracle Database 10g or Oracle9i JDBC drivers

  The Oracle JDBC library—classes12.jar for JDK 1.2 or higher, or ojdbc14.jar for JDK 1.4 specifically—is typically in ORACLE_HOME/jdbc/lib. See the Oracle Database JDBC Developer's Guide and Reference for more information about the JDBC files.

  Each JDBC library also includes the JPublisher runtime classes in the oracle.jpub.runtime package.

• Web services classes

  These classes are included in the library utl_dbws.jar, typically located in ORACLE_HOME/sqlj/lib.

• Additional PL/SQL packages and JAR files in the database, as needed

  There are packages and JAR files that must be in the database if you use JPublisher features for Web services call-ins, Web services call-outs, support for PL/SQL types, or support for invocation of server-side Java classes. Some are preloaded and some must be loaded manually. See the next section, "Required Packages and JAR Files in the Database".

• JDK version 1.2 or higher (JDK 1.4 or higher for Web services call-outs or to map SYS.XMLType for Web services)

  Note that you must be able to invoke the Java compiler, javac, from the command line. For information about how to specify a JDK version and a compiler version other than the default for the JPublisher environment, see "Java Environment Options".

Required Packages and JAR Files in the Database

Some or all of the following PL/SQL packages and JAR files must be present in the database, depending on what JPublisher features you use. Subsections that follow discuss how to verify the presence of these packages and files, and how to load them if they are not present.

• SQLJUTL package, to support PL/SQL types

• SQLJUTL2 package, to support invocation of server-side Java classes

• UTL_DBWS package, to support Web services call-outs

• utl_dbws_jserver.jar file, to support JAX-RPC or SOAP client proxy classes for Web services call-outs from Oracle Database 10g

  See "Options to Facilitate Web Services Call-Outs" for information about related JPublisher features.

• JAR files to support SOAP client proxy classes for Web services call-outs from Oracle9i or Oracle8i databases

  For Web services call-outs from Oracle9i or Oracle8i, there is not yet a convenience JAR file to parallel utl_dbws_jserver.jar. You must load several JAR files instead. Also note that JPublisher does not yet support JAX-RPC client proxy classes in Oracle9i or Oracle8i.

• sqljutl.jar file or its contents, to support Web services call-ins

  In Oracle Database 10g, support for Web services call-ins is preloaded in the database Java VM, so the sqljutl.jar file is unnecessary. In Oracle9i or Oracle8i, you must load the file manually.

SQL> describe sys.utl_dbws

ORACLE_HOME/sqlj/lib/utl_dbws_decl.sql
ORACLE_HOME/sqlj/lib/utl_dbws_body.sql

SQL> describe sys.sqljutl
SQL> describe sys.sqljutl2

Warning: Cannot determine what kind of type is <schema>.<type.> You likely need
to install SYS.SQLJUTL. The database returns: ORA-06550: line 1, column 7:
PLS-00201: identifier 'SYS.SQLJUTL' must be declared

SQL>  select status, object_type from all_objects where
      dbms_java.longname(object_name)='oracle/jpub/runtime/dbws/DbwsProxy$1';

STATUS  OBJECT_TYPE
------- -------------------
VALID   JAVA CLASS
VALID   SYNONYM

% loadjava -oci8 -u sys/change_on_install -r -v -f -s 
           -grant public utl_dbws_jserver.jar

% loadjava -u sys/change_on_install -r -v -s -f -grant public 
ORACLE_HOME/soap/lib/soap.jar 
ORACLE_HOME/dms/lib/dms.jar 
J2EE_HOME/lib/servlet.jar 
J2EE_HOME/lib/ejb.jar 
J2EE_HOME/lib/mail.jar

SQL> select status, object_type from all_objects where
     dbms_java.longname(object_name)='oracle/jpub/reflect/Client';

STATUS  OBJECT_TYPE
------- -------------------
VALID   JAVA CLASS
VALID   SYNONYM

% loadjava -oci8 -u sys/change_on_install -r -v -f -s 
           -grant public sqlj/lib/sqljutl.jar

Situations for Reduced Requirements

If you will not be using certain features of JPublisher, your requirements may be less stringent:

• If you never generate classes that implement the Oracle-specific oracle.sql.ORAData interface (or the deprecated oracle.sql.CustomDatum interface), you can use a non-Oracle JDBC driver and connect to a non-Oracle database. JPublisher itself, however, must be able to connect to an Oracle database. Be aware that Oracle does not test or support configurations that use non-Oracle components. (See "Representing User-Defined SQL Types Through JPublisher" for an overview of ORAData.)

• If you instruct JPublisher to not generate wrapper methods (through the setting -methods=false), or if your object types define no methods, then JPublisher will not generate wrapper methods or produce any SQLJ classes. Under these circumstances, there will be no SQLJ translation step, so the SQLJ translator is not required. See "Generation of Package Classes and Wrapper Methods (-methods)" for information about the -methods option.

• If you use JPublisher to generate custom object classes that implement only the deprecated CustomDatum interface, then you can use the Oracle8i Release 8.1.5 database with the 8.1.5 version of the JDBC driver and with JDK version 1.1 or higher. But it is advisable to upgrade to the ORAData interface, which requires an Oracle9i or higher JDBC implementation.

• If you do not use JPublisher functionality for invocation of server-side Java classes, then you do not need the sqljutl.jar file to be loaded in the database.

• If you do not use JPublisher functionality to enable Web services call-outs, then you do not need utl_dbws.jar or utl_dbws_jserver.jar to be loaded in the database.

JPublisher Limitations

Be aware of the following when you use JPublisher:

• There are limitations to the support for PL/SQL RECORD and indexed-by table types. First, an intermediate wrapper layer is used to map a RECORD or indexed-by-table argument to a SQL type that JDBC supports. In addition, JPublisher cannot fully support the semantics of indexed-by tables. An indexed-by table is similar in structure to a Java Hashtable, but information is lost when JPublisher maps this to a SQL TABLE type (SQL collection). See "Type Mapping Support for PL/SQL RECORD and Indexed-by Table Types" for details about how these types are supported.

• If you use an INPUT file to specify type mappings, note that some potentially disruptive error conditions do not result in error or warning messages from JPublisher. Additionally, there are reserved terms that you are not permitted to use as SQL or Java identifiers. See "INPUT File Precautions" for details.

• There is a JPublisher option, -omit_schema_names, that has boolean logic but does not use the same syntax as other boolean options. You can use this option to instruct JPublisher to not use schema names to qualify SQL names that are referenced in wrapper classes. (By default, JPublisher uses schema names to qualify SQL names.) To enable the option (to disable the use of schema names), enter the option name, "-omit_schema_names", on the command line, but do not attempt to set "-omit_schema_names=true" or "-omit_schema_names=false". See "Omission of Schema Name from Name References (-omit_schema_names)" for additional information.

Publishing SQL User-Defined Types

Using JPublisher to publish SQL objects or collections as Java classes is straightforward. This section provides examples of this for the OE (Order Entry) schema that is part of the Oracle Database sample schema. (See Oracle Database Sample Schemas for detailed information.) If you do not have the sample schema installed, but have your own object types that you would like to publish, then replace the user name, password, and object names with your own.

Assuming that the password for the OE schema is OE, use the following command to publish the SQL object type CATEGORY_TYP (where % is the system prompt):

% jpub -user=OE/OE -sql=CATEGORY_TYP:CategoryTyp

Use the JPublisher -user option to specify the user name (schema name) and password. The -sql option specifies the types to be published. CATEGORY_TYP is the name of the SQL type and, separated by a colon (":"), CategoryTyp is the name of the corresponding Java class to be generated. JPublisher echoes to the standard output the names of the SQL types that it is publishing:

OE.CATEGORY_TYP

When you list the files in your current directory, notice that in addition to the file CategoryTyp.java, JPublisher has also generated the file CategoryTypeRef.java. This represents a strongly typed wrapper class for SQL object references to OE.CATEGORY_TYP. Both files are ready to be compiled with the Java compiler, javac.

Here is another example, for the type CUSTOMER_TYP, using the shorthand -u (followed by a space) for "-user=" and -s (followed by a space) for "-sql=":

% jpub -u OE/OE -s CUSTOMER_TYP:CustomerTyp

JPublisher reports a list of SQL object types, as follows, because whenever it encounters an object type for the first time (whether through an attribute, an object reference, or a collection that has element types that themselves are objects or collections), it automatically generates a wrapper class for that type as well.

OE.CUSTOMER_TYP
OE.CORPORATE_CUSTOMER_TYP
OE.CUST_ADDRESS_TYP
OE.PHONE_LIST_TYP
OE.ORDER_LIST_TYP
OE.ORDER_TYP
OE.ORDER_ITEM_LIST_TYP
OE.ORDER_ITEM_TYP
OE.PRODUCT_INFORMATION_TYP
OE.INVENTORY_LIST_TYP
OE.INVENTORY_TYP
OE.WAREHOUSE_TYP

Two source files are generated for each object type in this example: 1) source file for a Java class, such as CustomerTyp, to represent instances of the object type; and 2) source file for a reference class, such as CustomerTypeRef, to represent references to the object type. You may also have noticed the naming scheme that JPublisher uses by default: the SQL type OE.PRODUCT_INFORMATION_TYP turns into a Java class ProductInformationTyp, for example.

Even though JPublisher automatically generates wrapper classes for embedded types, it does not do so for subtypes of given object types. In this case, you have to explicitly enumerate all the subtypes that you want to have published. The CATEGORY_TYP type has three subtypes: LEAF_CATEGORY_TYP, COMPOSITE_CATEGORY_TYP, and CATALOG_TYP. The following is a single wraparound JPublisher command line to publish these object types.

% jpub  -u OE/OE  -s COMPOSITE_CATEGORY_TYP:CompositeCategoryTyp
        -s LEAF_CATEGORY_TYP:LeafCategoryTyp,CATALOG_TYP:CatalogTyp

Here is the JPublisher output, listing the processed types:

OE.COMPOSITE_CATEGORY_TYP
OE.SUBCATEGORY_REF_LIST_TYP
OE.LEAF_CATEGORY_TYP
OE.CATALOG_TYP
OE.CATEGORY_TYP
OE.PRODUCT_REF_LIST_TYP

Note the following:

• If you want to unparse several types, you can list them all together in the -sql (-s) option, separated by commas, or you can supply several -sql options on the command line, or you can do both.

• Although JPublisher does not automatically generate wrapper classes for all subtypes, it does generate them for all supertypes.

• For SQL objects with methods (stored procedures), such as CATALOG_TYP, JPublisher uses SQLJ classes, meaning Java classes that use the SQLJ runtime during execution, to implement the wrapper methods. In Oracle Database 10g, the use of SQLJ classes, as opposed to regular Java classes, is invisible to you unless you use one of the backward compatibility modes.

If the code that JPublisher generates does not give you the functionality or behavior you want, then you can extend generated wrapper classes to override or complement their functionality. Consider the following example:

% jpub -u OE/OE -s WAREHOUSE_TYP:JPubWarehouse:MyWarehouse

Here is the JPublisher output:

OE.WAREHOUSE_TYP

With this command, JPublisher generates both JPubWarehouse.java and MyWarehouse.java. The file JPubWarehouse.java is regenerated every time you rerun this command. The file MyWarehouse.java is created to be customized by you, and will not be overwritten by future runs of this JPublisher invocation. You can add new methods in MyWarehouse.java, override the method implementations from JPubWarehouse.java, or both. The class that is used to materialize WAREHOUSE_TYP instances in Java is the specialized class MyWarehouse. If you want user-specific subclasses for all types in an object type hierarchy, then you must specify "triplets" of the form SQL_TYPE:JPubClass:UserClass, as shown in the preceding JPublisher command, for all members of the hierarchy.

Once you have generated and compiled Java wrapper classes with JPublisher, using them is fairly straightforward. You can use the object wrappers directly.

The following SQLJ class calls a PL/SQL stored procedure. Assume that register_warehouse takes a WAREHOUSE_TYP instance as an IN OUT parameter. (A code comment shows the corresponding #sql command. By default, JPublisher generates and translates the SQLJ code automatically.) See the next section, "Publishing PL/SQL Packages", for a discussion of wrapper methods and the problems posed by OUT and IN OUT arguments.

java.math.BigDecimal location = new java.math.BigDecimal(10); 
java.math.BigDecimal warehouseId = new java.math.BigDecimal(10); 
MyWarehouse w = new MyWarehouse(warehouseId,"Industrial Park",location); 
//  ************************************************************
//  #sql { call register_warehouse(:INOUT w) };
//  ************************************************************
//
// declare temps 
oracle.jdbc.OracleCallableStatement __sJT_st = null; 
sqlj.runtime.ref.DefaultContext __sJT_cc =
          sqlj.runtime.ref.DefaultContext.getDefaultContext(); 
if (__sJT_cc==null)
          sqlj.runtime.error.RuntimeRefErrors.raise_NULL_CONN_CTX(); 
sqlj.runtime.ExecutionContext.OracleContext __sJT_ec =
          ((__sJT_cc.getExecutionContext()==null) ?
          sqlj.runtime.ExecutionContext.raiseNullExecCtx() :
          __sJT_cc.getExecutionContext().getOracleContext()); 
try { 
   String theSqlTS = "BEGIN register_warehouse( :1 ) \n; END;"; 
   __sJT_st = __sJT_ec.prepareOracleCall(__sJT_cc,"0RegisterWarehouse",theSqlTS); 
   if (__sJT_ec.isNew()) 
   { 
      __sJT_st.registerOutParameter(1,2002,"OE.WAREHOUSE_TYP"); 
   } 
   // set IN parameters 
   if (w==null) __sJT_st.setNull(1,2002,"OE.WAREHOUSE_TYP"); 
   else __sJT_st.setORAData(1,w); 
   // execute statement 
   __sJT_ec.oracleExecuteUpdate(); 
   // retrieve OUT parameters 
   w = (MyWarehouse)__sJT_st.getORAData(1,MyWarehouse.getORADataFactory()); 
} finally { __sJT_ec.oracleClose(); } 

In JDBC, you typically register the relationship between the SQL type name and the corresponding Java class in the type map for your connection instance. This is required once for each connection, as in the following example:

java.util.Map typeMap = conn.getTypeMap();
typeMap.put("OE.WAREHOUSE_TYP", MyWarehouse.class);
conn.setTypeMap(typeMap);

The following JDBC code is equivalent to the JPublisher output (translated SQLJ code) shown previously:

CallableStatement cs = conn.prepareCall("{call register_warehouse(?)}");
((OracleCallableStatement)cs).registerOutParameter
                 (1, Oracle.jdbc.OracleTypes.STRUCT,"OE.WAREHOUSE_TYP");
cs.setObject(w);
cs.executeUpdate();
w = cs.getObject(1);

Publishing PL/SQL Packages

In addition to mapping SQL objects, you may want to encapsulate entire PL/SQL packages as Java classes. JPublisher offers functionality to create Java wrapper methods for the stored procedures of a PL/SQL package.

The concept of representing PL/SQL stored procedures as Java methods presents a problem, however. Arguments to such functions or procedures may use the PL/SQL mode OUT or IN OUT, but there are no equivalent modes for passing arguments in Java. A method that takes an int argument, for example, is not able to modify this argument in such a way that its callers can receive a new value for it. As a workaround, JPublisher can generate single-element arrays for OUT and IN OUT arguments. For an array int[] abc, for example, the input value is provided in abc[0], and the modified output value is also returned in abc[0]. JPublisher also uses a similar pattern when generating code for SQL object type methods.

For additional information about the array mechanism and other mechanisms for handling OUT or IN OUT parameters, see "JPublisher Treatment of Output Parameters".

The following command line publishes the SYS.DBMS_LOB package into Java:

% jpub  -u SCOTT/TIGER  -s SYS.DBMS_LOB:DbmsLob

Here is the JPublisher output:

SYS.DBMS_LOB

Because DBMS_LOB is publicly visible, you can access it from a different schema, such as SCOTT. Note that this JPublisher invocation creates a SQLJ class in DbmsLob.java that contains the calls to the PL/SQL package. The generated Java methods are actually all instance methods. The idea is that you create an instance of the package using a JDBC connection or a SQLJ connection context and then call the methods on that instance.

% jpub -numbertypes=jdbc  -u SCOTT/TIGER  -s SYS.DBMS_LOB:DbmsLob

SYS.DBMS_LOB

% jpub  -u SCOTT/TIGER  -s TOPLEVEL:SQLTopLevel

SCOTT.top-level_scope

Publishing Server-Side Java Classes

Oracle Database 10g introduces the native Java interface—new features for calls to server-side Java code. Previously, calling Java stored procedures and functions from a database client required JDBC calls to associated PL/SQL wrappers. Each PL/SQL wrapper had to be manually published with a SQL signature and a Java implementation. This process had the following disadvantages:

• The signatures permitted only Java types that had direct SQL equivalents.

• Exceptions issued in Java were not properly returned.

The JPublisher -java option provides functionality to avoid these disadvantages.

To remedy the deficiencies of JDBC calls to associated PL/SQL wrappers, the -java option makes convenient use of an API for direct invocation of static Java methods. This functionality is also useful for Web services.

The functionality of the -java option mirrors that of the -sql option, creating a client-side Java stub class to access a server-side Java class, in contrast to creating a client-side Java class to access a server-side SQL object or PL/SQL package. The client-side stub class mirrors the server-side class and includes the following features:

• Methods corresponding to the public static methods of the server class

• Two constructors: one that takes a JDBC connection and one that takes the SQLJ default connection context instance

At runtime, the stub class is instantiated with a JDBC connection. Calls to its methods result in calls to the corresponding methods of the server-side class. Any Java types used in these published methods must be primitive or serializable.

As an example, assume that you want to call the following method in the server:

public String oracle.sqlj.checker.JdbcVersion.to_string();

Use the -java setting in the following JPublisher command:

% jpub -u scott/tiger -url=jdbc:oracle:oci:@ -java=oracle.sqlj.checker.JdbcVersion

Note that for invocation of server-side Java, you must provide information for the database connection.

See "Declaration of Server-Side Java Classes to Translate (-java)" for information about -java option syntax.

Publishing SQL Queries or DML Statements

The JPublisher -sqlstatement option enables you to publish SQL queries (SELECT statements) or DML statements (INSERT, UPDATE, or DELETE statements) as Java methods. This functionality is of potential use for Web services, but is more generally useful as well.

Specify the following through -sqlstatement settings:

• Java class in which the method will be published (-sqlstatement.class=classname)

• SQL statement and desired corresponding Java method name (-sqlstatement.methodname=sqlstatement)

• Whether JPublisher should generate a method that returns a generic java.sql.ResultSet instance, a method that returns an array of JavaBeans, or both methods (-sqlstatement.return=resultset|beans|both)

Consider the following -sqlstatement settings:

-sqlstatement.class=SqlStatement 
-sqlstatement.getEmp="select ename from emp where empno=:{myno NUMBER}"

JPublisher generates a class named SqlStatement with the following method:

public static GetEmpRow[] getEmpBeans(int myno) 
{...}

See "Declaration of SQL Statements to Translate (-sqlstatement)" for syntax information and a complete example.

Publishing Proxy Classes and Wrappers for Web Services Call-Outs

Given a Web Services Description Language (WSDL) document at a specified URL, JPublisher directs the generation of Web services client proxy classes and generates appropriate Java and PL/SQL wrappers for Web services call-outs from the database. Classes to generate and process are determined from the WSDL document. JPublisher executes the following steps:

1. Invokes the Oracle Database Web services assembler tool to produce Web services client proxy classes based on the WSDL document.

2. As appropriate or necessary, creates Java wrapper classes for the Web services client proxy classes. For each proxy class that has instance methods (as is typical), a wrapper class is necessary to expose the instance methods as static methods.

3. Creates PL/SQL wrappers (call specs) for the generated classes, to make them accessible from PL/SQL.

4. Loads generated code into the database, unless you specify otherwise, and assuming you specify a database to connect to.

See "Options to Facilitate Web Services Call-Outs" for details.

JPublisher Mappings for User-Defined Types and PL/SQL Types

JPublisher provides mappings from the following to Java classes:

• User-defined SQL types (objects, collections, and OPAQUE types)

• PL/SQL types

JPublisher Mapping Categories

JPublisher offers different categories of datatype mappings from SQL to Java. ("Options for Datatype Mappings" describes JPublisher options to specify these mappings.)

Each type mapping option has at least two possible values: jdbc and oracle. The -numbertypes option has two additional alternatives: objectjdbc and bigdecimal.

The following sections describe these categories of mappings. For more information about datatype mappings, see Chapter 2.

Input to JPublisher

You can specify input options on the command line and in a JPublisher properties file. In addition to producing Java classes for the translated entities, JPublisher writes the names of the translated objects and packages to standard output. "JPublisher Options" describes all the JPublisher options.

In addition, you can use a file known as the JPublisher INPUT file to specify the SQL types, PL/SQL packages, or server-side Java classes that JPublisher should publish. It also controls the naming of the generated packages and classes. "INPUT File Structure and Syntax" describes INPUT file syntax.

To use a properties file to specify option settings, specify the name of the properties file on the command line, using the -props option. JPublisher processes a properties file as if its contents were inserted in sequence on the command line at the point of the -props option. For additional flexibility, properties files can also be SQL script files in which the JPublisher directives are embedded in SQL comments. For more information about properties file and their formats, see "Properties File Structure and Syntax".

Output from JPublisher

This section describes JPublisher output for user-defined object types, user-defined collection types, OPAQUE types, PL/SQL packages, server-side Java classes, and SQL queries or DML statements.

Summary of the Publishing Process: Generation and Use of Output

This section lists the basic steps, illustrated in Figure 1-1 that follows, for publishing specified SQL types, PL/SQL packages, or server-side Java classes.

1. Run JPublisher with input from the command line, properties file, and INPUT file, as desired.

2. JPublisher accesses the database to which it is attached to obtain definitions of SQL or PL/SQL entities that you specified for publishing.

3. JPublisher generates .java or .sqlj source files, as appropriate, depending primarily on whether wrapper methods are created for stored procedures.

4. By default, JPublisher invokes the SQLJ translator (provided as part of the JPublisher product) to translate .sqlj files into .java files.

5. By default, the SQLJ translator (or JPublisher, for non-SQLJ classes) invokes the Java compiler to compile .java files into .class files.

6. JPublisher outputs PL/SQL wrappers and scripts (.sql files), as appropriate, in addition to the .class files. There is a script to create the PL/SQL wrapper package and any necessary SQL types (such as types to map to PL/SQL types), a script to drop these entities, and scripts to grant or revoke required privileges.

7. In the case of proxy class generation (through the -proxywsdl or -proxyclasses option), JPublisher can load generated PL/SQL wrappers and scripts into the database to which it is connected, for execution in the database PL/SQL engine.

8. By default, JPublisher loads generated Java classes for Web services call-outs into the database to which it is connected, for execution in the database JVM. JPublisher-generated classes other than those for Web services call-outs typically execute in a client or middle-tier JVM. You may also have your own classes, such as subclasses of JPublisher-generated classes, that would typically execute in a client or middle-tier JVM.

Figure 1-1 Translating and Using JPublisher-Generated Code

Description of the illustration O_1094.gif

JPublisher Command-Line Syntax

On most operating systems, you invoke JPublisher on the command line, typing jpub followed by a series of options settings, as follows:

% jpub -option1=value1 -option2=value2 ...

JPublisher responds by connecting to the database and obtaining the declarations of the types or packages you specify, then generating one or more custom Java classes (SQLJ classes or non-SQLJ classes, as appropriate) and writing the names of the translated object types or PL/SQL packages to standard output.

Here is an example of a (single wraparound) command that invokes JPublisher:

% jpub -user=scott/tiger -input=demoin -numbertypes=oracle -usertypes=oracle
       -dir=demo -d=demo -package=corp

Enter the command on one command line, allowing it to wrap as necessary. For clarity, this chapter refers to the input file specified by the -input option as the INPUT file (to distinguish it from any other kinds of input files).

This command directs JPublisher to connect to the database with user name SCOTT and password TIGER and to translate datatypes to Java classes, based on instructions in the INPUT file demoin. The -numbertypes=oracle option directs JPublisher to map object attribute types to Java classes supplied by Oracle, and the -usertypes=oracle option directs JPublisher to generate Oracle-specific ORAData classes. JPublisher places the classes that it generates in the package corp under the directory demo.

JPublisher also supports specification of .java files (or .sqlj files, if you are using SQLJ source files directly) on the JPublisher command line. The specified files are translated and compiled in addition to any JPublisher-generated files. For example:

% jpub ...options... Myclass.java

Sample JPublisher Translation

This section provides a sample JPublisher translation of a user-defined object type. At this point, do not worry about the details of the code JPublisher generates. You can find more information about JPublisher input and output files, options, datatype mappings, and translation later in this manual.

Create the object type EMPLOYEE:

CREATE TYPE employee AS OBJECT
(
    name       VARCHAR2(30),
    empno      INTEGER,
    deptno     NUMBER,
    hiredate   DATE,
    salary     REAL
);

The INTEGER, NUMBER, and REAL types are all stored in the database as NUMBER types, but after translation they have different representations in the Java program, based on your setting of the -numbertypes option.

Assume JPublisher translates the types according to the following (wraparound) command line:

% jpub -user=scott/tiger -dir=demo -numbertypes=objectjdbc -builtintypes=jdbc
       -package=corp -case=mixed -sql=Employee

"JPublisher Options" describes each of these options in detail.

Note that because the EMPLOYEE object type does not define any methods, JPublisher generates a non-SQLJ class.

Because -dir=demo and -package=corp were specified on the JPublisher command line, the translated class Employee is written to Employee.java in the following location (for a UNIX system):

./demo/corp/Employee.java

The Employee.java class file would contain the code shown in the following example.

package corp;

import java.sql.SQLException;
import java.sql.Connection;
import oracle.jdbc.OracleTypes;
import oracle.sql.ORAData;
import oracle.sql.ORADataFactory;
import oracle.sql.Datum;
import oracle.sql.STRUCT;
import oracle.jpub.runtime.MutableStruct;

public class Employee implements ORAData, ORADataFactory
{
  public static final String _SQL_NAME = "SCOTT.EMPLOYEE";
  public static final int _SQL_TYPECODE = OracleTypes.STRUCT;

  protected MutableStruct _struct;

  private static int[] _sqlType =  { 12,4,2,91,7 };
  private static ORADataFactory[] _factory = new ORADataFactory[5];
  protected static final Employee _EmployeeFactory = new Employee(false);

  public static ORADataFactory getORADataFactory()
  { return _EmployeeFactory; }

  /* constructor */
  protected Employee(boolean init)
  { if(init) _struct = new MutableStruct(new Object[5], _sqlType, _factory); }
  public Employee()
  { this(true); }
  public Employee(String name, Integer empno, java.math.BigDecimal deptno,
                  java.sql.Timestamp hiredate, Float salary) 
   throws SQLException
  { this(true);
    setName(name);
    setEmpno(empno);
    setDeptno(deptno);
    setHiredate(hiredate);
    setSalary(salary);
  }

  /* ORAData interface */
  public Datum toDatum(Connection c) throws SQLException
  {
    return _struct.toDatum(c, _SQL_NAME);
  }

  /* ORADataFactory interface */
  public ORAData create(Datum d, int sqlType) throws SQLException
  { return create(null, d, sqlType); }
  protected ORAData create(Employee o, Datum d, int sqlType) throws SQLException
  {
    if (d == null) return null; 
    if (o == null) o = new Employee(false);
    o._struct = new MutableStruct((STRUCT) d, _sqlType, _factory);
    return o;
  }
  /* accessor methods */
  public String getName() throws SQLException
  { return (String) _struct.getAttribute(0); }

  public void setName(String name) throws SQLException
  { _struct.setAttribute(0, name); }

  public Integer getEmpno() throws SQLException
  { return (Integer) _struct.getAttribute(1); }

  public void setEmpno(Integer empno) throws SQLException
  { _struct.setAttribute(1, empno); }

  public java.math.BigDecimal getDeptno() throws SQLException
  { return (java.math.BigDecimal) _struct.getAttribute(2); }

  public void setDeptno(java.math.BigDecimal deptno) throws SQLException
  { _struct.setAttribute(2, deptno); }

  public java.sql.Timestamp getHiredate() throws SQLException
  { return (java.sql.Timestamp) _struct.getAttribute(3); }

  public void setHiredate(java.sql.Timestamp hiredate) throws SQLException
  { _struct.setAttribute(3, hiredate); }

  public Float getSalary() throws SQLException
  { return (Float) _struct.getAttribute(4); }

  public void setSalary(Float salary) throws SQLException
  { _struct.setAttribute(4, salary); }

}

• JPublisher also generates object constructors based on the object attributes.

• Additional private or public methods may be generated with other option settings. For example, the setting -serializable=true results in the object wrapper class implementing the interface java.io.Serializable and in the generation of private writeObject() and private readObject() methods. The setting -tostring=true results in the additional generation of a public toString() method.

• There is a protected _struct field in JPublisher-generated code for SQL object types. This is an instance of the internal class oracle.jpub.runtime.MutableStruct; this instance contains the data in original SQL format. In general, you should never reference this field directly. Instead, use the setting -methods=always or -methods=named, as necessary, to ensure that JPublisher produces setFrom() and setValueFrom() methods, then use these methods when extending a class. See "The setFrom(), setValueFrom(), and setContextFrom() Methods".

• JPublisher generates SQLJ classes instead of non-SQLJ classes in the following circumstances:

  • The SQL object being published has methods, and the setting -methods=false is not specified.

  • A PL/SQL package, stored procedure, query, or DML statement is published, and the setting -methods=false is not specified.

  Additionally:

  • If a SQLJ class is created for a type definition, then a SQLJ class is also created for the corresponding REF definition.

  • If a SQLJ class is created for a base class, then SQLJ classes are also created for any subclasses.

  (In a backward compatibility mode, this means that JPublisher generates .sqlj files instead of .java files.)

• Note that the JPublisher version provided with Oracle8i generates implementations of the now-deprecated CustomDatum and CustomDatumFactory interfaces, instead of ORAData and ORADataFactory. In fact, it is still possible to do this through the JPublisher -compatible option, and this is required if you are using an Oracle8i JDBC driver.

JPublisher also generates an EmployeeRef.java class. The source code is displayed here:

package corp;

import java.sql.SQLException;
import java.sql.Connection;
import oracle.jdbc.OracleTypes;
import oracle.sql.ORAData;
import oracle.sql.ORADataFactory;
import oracle.sql.Datum;
import oracle.sql.REF;
import oracle.sql.STRUCT;

public class EmployeeRef implements ORAData, ORADataFactory
{
  public static final String _SQL_BASETYPE = "SCOTT.EMPLOYEE";
  public static final int _SQL_TYPECODE = OracleTypes.REF;

  REF _ref;

private static final EmployeeRef _EmployeeRefFactory = new EmployeeRef();

  public static ORADataFactory getORADataFactory()
  { return _EmployeeRefFactory; }
  /* constructor */
  public EmployeeRef()
  {
  }

  /* ORAData interface */
  public Datum toDatum(Connection c) throws SQLException
  {
    return _ref;
  }

  /* ORADataFactory interface */
  public ORAData create(Datum d, int sqlType) throws SQLException
  {
    if (d == null) return null;
    EmployeeRef r = new EmployeeRef();
    r._ref = (REF) d;
    return r;
  }

  public static EmployeeRef cast(ORAData o) throws SQLException
  {
     if (o == null) return null;
     try { return (EmployeeRef) getORADataFactory().create(o.toDatum(null),
           OracleTypes.REF); }
     catch (Exception exn)
     { throw new SQLException("Unable to convert "+o.getClass().getName()+" to
             EmployeeRef: "+exn.toString()); }
  }

  public Employee getValue() throws SQLException
  {
     return (Employee) Employee.getORADataFactory().create(
       _ref.getSTRUCT(), OracleTypes.REF);
  }

  public void setValue(Employee c) throws SQLException
  {
    _ref.setValue((STRUCT) c.toDatum(_ref.getJavaSqlConnection()));
  }
}

Note that JPublisher also generates a public static cast() method to cast from other strongly typed references into a strongly typed reference instance.