6 Command-Line Options and Input Files

File Containing Names of Objects and Packages to Translate

The -input option specifies the name of a file from which JPublisher reads the names of SQL or PL/SQL entities or server-side Java classes to publish, along with any related information or instructions. JPublisher publishes each item in the list. You can think of the INPUT file as a makefile for type declarations, which lists the types that need Java class definitions.

The syntax of the -input option is as follows:

-input=filename
-i filename

Both formats are synonymous. The second one is a convenient command-line shortcut.

In some cases, JPublisher may find it necessary to translate some additional classes that do not appear in the INPUT file. This is because JPublisher analyzes the types in the INPUT file for dependencies before performing the translation and translates other types as necessary.

If you do not specify any items to publish in an INPUT file or on the command line, then JPublisher translates all user-defined SQL types and PL/SQL packages declared in the database schema to which it is connected.

Declaration of Server-Side Java Classes to Publish

The -java option enables you to create client-side stub classes to access server-side classes. This is an improvement over earlier JPublisher releases in which calling Java stored procedures and functions from a database client required JDBC calls to associated PL/SQL wrappers.

The syntax of the -java option is as follows:

-java=class_or_package_list

The functionality of the -java option mirrors that of the -sql option. It creates 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.

When using the -java option, specify a comma-delimited list of server-side Java classes or packages.

For example:

-java=foo.bar.Baz,foo.baz.*

Or, to specify the client-side class name corresponding to Baz, instead of using the server-side name by default:

-java=foo.bar.Baz:MyBaz,foo.baz.*

This setting creates MyBaz and not foo.bar.MyBaz.

or:

-java=foo.bar.Baz:foo.bar.MyBaz,foo.baz.*

You can also specify a schema:

-java=foo.bar.Baz@SCOTT

If you specify the schema, then only that schema is searched. If you do not specify a schema, then the schema of the logged-in user, according to the -user option setting, is searched. This is the most likely scenario.

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

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

Use the following -java setting:

-java=oracle.sqlj.checker.JdbcVersion

Code Generation for -java Option When you use the -java option, generated code uses the following API:

public class Client
{
   public static String getSignature(Class[]);
   public static Object invoke(Connection, String, String, 
                               String, Object[]);
   public static Object invoke(Connection, String, String, 
                               Class[], Object[]);
}

Classes for the API are located in the oracle.jpub.reflect package, so client applications must import this package.

For a setting of -java=oracle.sqlj.checker.JdbcVersion, JPublisher-generated code includes the following call:

Connection conn = ...;
String serverSqljVersion = (String)
           Client.invoke(conn, "oracle.sqlj.checker.JdbcVersion",
           "to_string", new Class[]{}, new Object[]{});

The Class[] array is for the method parameter types, and the Object[] array is for the parameter values. In this case, because to_string has no parameters, the arrays are empty.

Note the following:

• Any serializable type, such as int[] or String[], can be passed as an argument.

• The semantics of this API are different from the semantics for invoking Java stored procedures or functions through a PL/SQL wrapper, in the following ways:

  • Arguments cannot be OUT or IN OUT. Returned values must be part of the function result.

  • Exceptions are properly returned.

  • Method invocation uses invoker's rights. There is no tuning to obtain definer's rights.

    See Also:

    Oracle Database Java Developer's Guide for information about invoker's rights and definer's rights

Declaration of Server-Side Java Classes to Publish

The related options for publishing a server-side Java class are:

• -dbajva=class_list
  

• -proxyopts=single|multiple|static|arrayin|arrayout|arrayinout
  |arrayall|noload
  

• -compatible=10.1
  

• -sysuser=user/password
  

• -plsqlfile=wrapper[,dropper]
  

• -plsqlpackage=name
  

Oracle Database 10g release 1 (10.1) introduced the -java option to publish server-side Java classes. Oracle Database 10g release 2 (10.2) introduced a new approach toward server-side Java class publishing. The -dbjava option publishes a server-side Java class into PL/SQL, or into client-side Java class. The class_list specification is a comma-delimited list of server-side classes at the specified server. The class_list item is of the form classname[:name[#interface]]. It can also be a package name. Consider the option:

-dbajva=classname[:name[#interface]]

If name is not specified, then the server-side Java class, classname, is published into PL/SQL, else into the client-side Java class, name. If interface is specified, then the interface file is generated for the client-side Java class.

When used with -dbjava, the -proxyopts option indicates whether to map instance methods using a singleton instance or using multiple instances, and also whether to map methods with array parameters assuming arrays as IN, OUT, IN OUT, or all the modes. The -proxyopts=static setting specifies that only static methods should be published. The default setting, -proxyopts=single,arrayin, indicates that instance methods are called using a singleton instance and array parameters are considered as input. The -proxyopts=noload setting forbids JPublisher from loading the generated PL/SQL and Java stored procedure wrappers.

The -compatible=10.1 option makes -dbjava equivalent to -java.

Declaration of Server-Side Java Classes to Publish

The related options for publishing server-side Java class are:

• -proxyclasses=class_or_jar_list
  

• -proxyopts=single|multiple|static|arrayin|arrayout|arrayinout
  |arrayall
  

• -plsqlfile=wrapper[,dropper]
  

• -plsqlpackage=name
  

The -proxyclasses option is similar to -dbjava. While -dbjava requires that the classes to be published exist in the database, -proxyclasses requires that the classes appear in the classpath. Typically, by using -proxyclasses, you can load the exposed classes and the generated wrappers into the database later.

The -proxyclasses option generates only a PL/SQL wrapper. Unlike -dbjava, it will not generate client-side Java code for a server-side Java class. Also, unlike -dbjava, -proxyclasses does not load the generated Java stored procedure into the database.

You can use the -proxyclasses option to specify a comma-delimited list of Java classes, either loose classes or Java Archive (JAR) files, for which JPublisher creates PL/SQL wrappers. Depending on the situation, JPublisher can also create Java wrapper classes to afford access from PL/SQL. Each of the classes processed must have either public, static methods or, for classes in which you want to publish instance methods, a public zero-argument constructor.

To summarize, the following are generated for each class being processed, depending on the -proxyopts option settings:

• A PL/SQL wrapper to allow access from PL/SQL. This is always generated.

• A wrapper class to expose Java instance methods as static methods, if there are any instance methods to publish.

Instance methods must be exposed as static methods to allow access from PL/SQL. A wrapper class is also necessary if the wrapped class uses anything other than Java primitive types in the method calling sequences.

While using the -proxyclasses option directly, you can specify JAR files and Java classes that exist in the classpath. Classes and JAR files can be specified as follows:

• Class name, such as foo.bar.Baz or foo.bar.Baz.class

• Package name, such as foo.bar.*, for @server mode only

• JAR or ZIP file name, such as foo/bar/baz.jar or Baz.zip

• JAR or ZIP file name followed by parenthesized list of classes or packages, such as baz.jar (foo.MyClass1, foo.bar.MyClass2, foo1.*)

Settings for Java and PL/SQL Wrapper Generation

The -proxyopts option is used as input by the -dbjava, -proxywsdl, and -proxyclasses options and specifies JPublisher behavior in generating wrapper classes and PL/SQL wrappers for server-side Java classes.

The syntax of the -proxyopts option is as follows:

-proxyopts=setting1,setting2,...

This option uses the basic settings, which can be used individually or in combinations. In this discussion, processed classes are the classes that are wrapped by using the -dbjava, -proxywsdl, or -proxyclasses options.

Where Java wrapper classes are generated, the wrapper class for a class foo.bar.MyClass would be foo.bar.MyClassJPub, unless the package is overridden by a setting of the -package option.

You can use the basic -proxyopts settings as follows:

• Use the static setting to specify the treatment of static methods of processed classes.

  With this setting, in the PL/SQL wrapper, a wrapper procedure is generated for each static method. Without this setting, static methods are ignored. For classes with only static methods, wrapper classes are not required for processed classes that use only Java primitive types in their method calling sequences.

• Use the multiple or single setting to specify treatment of instance methods of processed classes, where you want instance methods exposed as static methods. In either case, for each processed class, JPublisher generates an intermediate Java class that wraps instance methods with static methods, in addition to generating a PL/SQL wrapper.

  Use the instance setting to specify treatment of instance methods of processed classes, where you want instance methods maintained as instance methods.

  These settings function as follows:

  • multiple

    For each processed class, the Java wrapper class has a static equivalent for each instance method through the use of handles, which identify instances of wrapped classes.

  • single

    Only a single default instance of each wrapped class is used during run time. For each processed class, the Java wrapper class has static wrapper methods for instance methods without requiring the use of handles. This is the singleton mechanism.

  • instance

    Instance methods are wrapped as instance methods in the Java wrapper class.

    Note:

    The instance setting is not appropriate for Web services.

  The instance methods are ignored if one of these settings or a jaxrpc or soap setting, which implies single, is not specified. For either of these settings, only classes that provide a public zero-argument constructor are processed. You can use both settings to generate wrapper classes of both styles.

• Use the jaxrpc or soap setting to publish instance methods of Web services client proxy classes. These settings function as follows:

  • jaxrpc

    This is the default setting. It is a convenient setting for wrapping JAX-RPC client proxy classes, which is appropriate for use with Oracle Application Server 10g 10.0.1 and later releases. JPublisher creates a Java wrapper class for each processed class and also creates the PL/SQL wrapper. Client proxy classes do not have static methods to be published, and instance methods are published using the singleton mechanism by default. Therefore, when processing JAX-RPC client proxy classes, -proxyopts=jaxrpc implies -proxyopts=single. The jaxrpc setting also results in generation of special code that is specific to JAX-RPC clients.

  • soap

    This setting is equivalent to the jaxrpc setting, but is used for wrapping SOAP client proxy classes instead of JAX-RPC client proxy classes. This is appropriate for use with Oracle Application Server 10g 9.0.4 and earlier releases.

Here are some basic uses of the -proxyopts option:

-proxyopts=jaxrpc

-proxyopts=soap

-proxyopts=static

-proxyopts=static,instance

-proxyopts=single

-proxyopts=single,multiple

-proxyopts=static,multiple

The static,instance setting publishes static and instance methods. The single,multiple setting publishes only instance methods, using both the singleton mechanism and the handle mechanism. The static,multiple setting publishes static and instance methods, using the handle mechanism to expose instance methods as static methods.

There are additional, advanced -proxyopts settings as well. The functionality of each setting is as follows:

• noload

  Use this to indicate that the generated code need not be loaded into the database. By default, the generated code is loaded.

• recursive

  Use this to indicate that when processing a class that extends another class, also create PL/SQL and Java wrappers, if appropriate, for inherited methods.

• tabfun

  Use this with the jaxrpc or soap setting for JPublisher to generate PL/SQL table functions for the PL/SQL package for each of the wrapped Web services operations. This exposes data through database tables rather than stored procedures or functions.

  Do not use the -proxyopts=tabfun setting when the Web service operation contains array types as parameter types. In such cases, JPublisher generates PL/SQL stored procedure with SQL tables as parameter types. So, setting the -proxyopts=tabfun setting will result in compilation error for the generated PL/SQL wrapper.

• deterministic

  Use this to indicate in the generated PL/SQL wrapper that the wrapped methods are deterministic. This would typically be used with the tabfun setting. Deterministic is a PL/SQL annotation.

  See Also:

  Oracle Database SQL Language Reference for information about DETERMINISTIC functions

• main(0,...)

  Use this with the static setting to define the wrapper methods to be generated if there is a public void String main(String[]) method in the class. A separate method is generated for each number of arguments that you want to support. You can use commas or hyphens when indicating the number of arguments, as in the following examples:

  • main or main(0) produces a wrapper method only for zero arguments.

  • main(0,1) produces wrapper methods for zero arguments and one argument. This is the default setting.

  • main(0-3) produces wrapper methods for zero, one, two, and three arguments.

  • main(0,2-4) produces wrapper methods for zero, two, three, and four arguments.

  The maximum number of arguments in the wrapper method for the main() method is according to PL/SQL limitations.

The following example uses the jaxrpc basic setting by default. It also uses table functions and indicates that wrapped methods are deterministic:

-proxyopts=tabfun,deterministic

The following example explicitly sets the static mode, processing classes that are not client proxy classes, and specifies that the generated code should not be loaded into the database:

-proxyopts=static,noload

Input Properties File

The -props option specifies the name of a JPublisher properties file that specifies JPublisher option settings. JPublisher processes the properties file as if its contents were inserted in sequence on the command line where the -props option is specified.

The syntax of the -props option is as follows:

-props=filename
-p filename

Both formats are synonymous. The second one is provided as a convenient command-line shortcut.

If more than one properties file appears on the command line, then JPublisher processes them with the other command-line options, in the order in which they appear.

Declaration of Object Types and Packages to Translate

The -sql option is used to specify the user-defined SQL types, such as objects or collections, or the PL/SQL packages that need to be published. Optionally, you can specify the user subclasses or interfaces that should be generated. You can publish all or a specific subset of a PL/SQL package.

The syntax of the -sql option is as follows:

-sql={toplevel|object_type_and_package_translation_syntax}
-s {toplevel|object_type_and_package_translation_syntax}

The two formats of this option, -sql and -s, are synonymous. The -s format is provided as a convenient command-line shortcut.

You can use the -sql option when you do not need the generality of an INPUT file. The -sql option lets you list one or more database entities declared in SQL that you want JPublisher to translate. Alternatively, you can use several -sql options in the same command line, or several jpub.sql options in a properties file.

You can mix user-defined type names and package names in the same -sql declaration. JPublisher can detect whether each item is an object type or a package. You can also use the -sql option with the keyword toplevel to translate all top-level PL/SQL subprograms in a schema. The toplevel keyword is not case-sensitive.

If you do not specify any types or packages to translate in the INPUT file or on the command line, then JPublisher translates all the types and packages in the schema to which you are connected. In this section, the -sql option is explained in terms of the equivalent INPUT file syntax.

You can use the any of the following syntax modes:

• -sql=name_a

  JPublisher publishes name_a, naming the generated class according to the default settings. In an INPUT file, you specify this options as follows:

  SQL name_a
  

• -sql=name_a:class_c

  JPublisher publishes name_a as the generated Java class class_c. In an INPUT file, you specify this options as follows:

  SQL name_a AS class_c
  

• -sql=name_a:class_b:class_c

  In this case, name_a must represent an object type. JPublisher generates the Java class, class_b, and a stub class, class_c, that extends class_b. You provide the code for class_c, which is used to represent name_a in your Java code. In an INPUT file, you specify this options as follows:

  SQL name_a GENERATE class_b AS class_c
  

• -sql=name_a:class_b#intfc_b

• -sql=name_a:class_b:class_c#intfc_c

  You can use either of these syntax formats to have JPublisher generate a Java interface. This feature is particularly useful for Web services. In the first case, class_b represents name_a and implements intfc_b. In the second case, class_c represents name_a, extends class_b, and implements intfc_c.

  See Also:

  "Generation of Java Interfaces"

  Specify an interface for either the generated class or the user subclass, but not both. In an INPUT file, this syntax is as follows:

    SQL name_a
      [GENERATE  class_b
                 [ implements intfc_b] ]
      [AS        class_c
                 [ implements intfc_c ] ]
      ...
  

If you enter more than one item for translation, then the items must be separated by commas, without any white space. This example assumes that CORPORATION is a package and that EMPLOYEE and ADDRESS are object types:

-sql=CORPORATION,EMPLOYEE:OracleEmployee,ADDRESS:JAddress:MyAddress

JPublisher interprets this command as follows:

SQL CORPORATION 
SQL EMPLOYEE AS OracleEmployee 
SQL ADDRESS GENERATE JAddress AS MyAddress

JPublisher performs the following actions:

• Creates a wrapper class for the CORPORATION package.

• Translates the EMPLOYEE object type as OracleEmployee.

• Generates an object reference class, OracleEmployeeRef.

• Translates ADDRESS as JAddress, but generates code and references so that ADDRESS objects will be represented by the MyAddress class.

• Generates a MyAddress stub, which extends JAddress, where you can write your custom code.

• Generates an object reference class MyAddressRef.

If you want JPublisher to translate all the top-level PL/SQL subprograms in the schema to which JPublisher is connected, then enter the keyword toplevel following the -sql option. JPublisher treats the top-level PL/SQL subprograms as if they were in a package. For example:

-sql=toplevel

JPublisher generates a wrapper class, toplevel, for the top-level subprograms. If you want the class to be generated with a different name, you can declare the name as follows:

-sql=toplevel:MyClass 

Note that this is synonymous with the following INPUT file syntax:

SQL toplevel AS MyClass

Similarly, if you want JPublisher to translate all the top-level PL/SQL subprograms in some other schema, then enter:

-sql=schema_name.toplevel

In this example, schema_name is the name of the schema containing the top-level subprograms. In addition, there are features to publish only a subset of stored procedures in a PL/SQL package or at the top level, using the following syntax:

-sql=plsql_package(proc1+proc2+proc3+...)

Use a plus sign (+) between stored procedure names. Alternatively, for the SQL top level, use:

-sql=toplevel(proc1+proc2+proc3+...)

The following syntax is for a JPublisher INPUT file, where commas are used between stored procedure names:

SQL plsql_package (proc1, proc2, proc3, ...) AS ...

You can also specify the subset according to stored procedure names and argument types by using the following syntax:

myfunc(sqltype1, sqltype2, ...)

In this case, only those stored procedures that match in name and the number and types of arguments will be published. For example:

-sql=mypackage(myfunc1(NUMBER, CHAR)+myfunc2(VARCHAR2))

Declaration of SQL Statements to Translate

The -sqlstatement option enables you to publish SELECT, INSERT, UPDATE, or DELETE statements as Java methods. JPublisher generates SQLJ classes for this functionality.

The syntax of the -sqlstatement option is as follows:

-sqlstatement.class=ClassName:UserClassName#UserInterfaceName
-sqlstatement.methodName=sqlStatement
-sqlstatement.return={both|resultset|beans}

Use -sqlstatement.class to specify the Java class in which the method will be published. In addition to the JPublisher-generated class, you can optionally specify a user subclass of the generated class, a user interface for the generated class or subclass, or both. Functionality for subclasses and interfaces is the same as for the -sql option. If you also use the JPublisher -package option, then the class you specify will be in the specified package. The default class is SQLStatements.

Use -sqlstatement.methodName to specify the desired Java method name and the SQL statement. For a SELECT statement, use -sqlstatement.return to specify whether JPublisher should generate a method that returns a generic java.sql.ResultSet instance, a method that returns an array of JavaBeans, or both. Generic implies that the column types of the result set are unknown or unspecified.

For queries, however, the column types are actually known. This provides the option of returning specific results through an array of beans. The name of the method returning ResultSet will be methodName(). The name of the method returning JavaBeans will be methodNameBeans().

JPublisher INPUT file syntax is as follows:

SQLSTATEMENTS_TYPE ClassName AS UserClassName
                             IMPLEMENTS UserInterfaceName
SQLSTATEMENTS_METHOD aSqlStatement AS methodName

Here is a set of sample settings:

-sqlstatement.class=MySqlStatements
-sqlstatement.getEmp="select ename from emp
                      where ename=:{myname VARCHAR}"
-sqlstatement.return=both

These settings result in the generated code shown in "Generated Code: SQL Statement".

In addition, be aware that a style file specified through the -style option is relevant to the -sqlstatement option. If a SQL statement uses an Oracle data type X, which corresponds to a Java type Y, and type Y is mapped to a Java type Z in the style file, then methods generated as a result of the -sqlstatement option will use Z, and not Y.

For SELECT or DML statement results, you can use a style file to map the results to javax.xml.transform.Source, oracle.jdbc.rowset.OracleWebRowSet, or org.w3c.dom.Document.

Declaration of Object Types to Translate

The -types option lets you list one or more individual object types that you want JPublisher to translate. The syntax of the -types option is as follows:

-types=type_translation_syntax

You can use the -types option, for SQL object types only and when you do not need the generality of an INPUT file. Except for the fact that the -types option does not support PL/SQL packages, it is identical to the -sql option.

If you do not enter any types or packages to translate in the INPUT file or on the command line, then JPublisher translates all the types and packages in the schema to which you are connected. The command-line syntax lets you indicate three possible type translations.

• -types=name_a

  JPublisher interprets this syntax as:

  TYPE name_a
  

• -types=name_a:name_b

  JPublisher interprets this syntax as:

  TYPE name_a AS name_b
  

• -types=name_a:name_b:name_c

  JPublisher interprets this syntax as:

  TYPE name_a GENERATE name_b AS name_c
  

TYPE, TYPE...AS, and TYPE...GENERATE...AS commands have the same functionality as SQL, SQL...AS, and SQL...GENERATE...AS syntax.

Enter -types=... on the command line, followed by one or more object type translations that you want JPublisher to perform. If you enter more than one item, then the items must be separated by commas without any white space. For example, if you enter:

-types=CORPORATION,EMPLOYEE:OracleEmployee,ADDRESS:JAddress:MyAddress

JPublisher interprets this command as:

TYPE CORPORATION
TYPE EMPLOYEE AS OracleEmployee
TYPE ADDRESS GENERATE JAddress AS MyAddress

SQLJ Connection Context Classes

The -context option specifies the connection context class that JPublisher uses, and possibly declares, for SQLJ classes that JPublisher produces. The syntax of the -context option is as follows:

-context={generated|DefaultContext|user_defined}

The -context=DefaultContext setting is the default and results in any JPublisher-generated SQLJ classes using the SQLJ default connection context class, sqlj.runtime.ref.DefaultContext, for all connection contexts. This is sufficient for most uses.

Alternatively, you can specify any user-defined class that implements the standard sqlj.runtime.ConnectionContext interface and exists in the classpath. The specified class will be used for all connection contexts.

The -context=generated setting results in an inner class declaration for the _Ctx connection context class in all SQLJ classes generated by JPublisher. So, each class uses its own SQLJ connection context class. This setting may be appropriate for Oracle8i compatibility mode, but it is otherwise not recommended. Using the DefaultContext class or a user-defined class avoids the generation of additional connection context classes. You can specify the -context option on the command line or in a properties file.

Notes for -context Usage in Backward-Compatibility Modes

If you use a backward-compatibility mode and use .sqlj files and the SQLJ translator directly, then a -context=DefaultContext setting gives you greater flexibility if you translate and compile your .sqlj files in separate steps, translating with the SQLJ -compile=false setting. If you are not using JDK 1.2-specific types, such as java.sql.BLOB, CLOB, Struct, Ref, or Array, then you can compile the resulting .java files under JDK 1.1, JDK 1.2, or later. This is not the case with the -context=generated setting, because SQLJ connection context classes in JDK 1.1 use java.util.Dictionary instances for object type maps, while SQLJ connection context classes in JDK 1.2 or later use java.util.Map instances.

A benefit of using the -context=generated setting, if you are directly manipulating .sqlj files, is that it permits full control over the way the SQLJ translator performs online checking. Specifically, you can check SQL user-defined types and PL/SQL packages against an appropriate exemplar database schema. However, because JPublisher generates .sqlj files from an existing schema, the generated code is already verified as correct through construction from that schema.

The Default datasource Option

You can use -datasource to specify the default data source for publishing SQL, PL/SQL, AQ, and server-side Java classes. With -datasource set, if the JDBC connection is not explicitly set by the application at run time, then the generated code will look up the specified Java Naming and Directory Interface (JNDI) location to get the data source and further get the JDBC connection from that data source.

The syntax of the -datasource option is as follows:

-datasource=jndi_location

JDBC Driver Class for Database Connection

The -driver option specifies the driver class that JPublisher uses for JDBC connections to the database. The syntax of this option is as follows:

-driver=driver_class_name

The default setting is:

-driver=oracle.jdbc.OracleDriver

This setting is appropriate for any Oracle JDBC driver.

Connection URL for Target Database

You can use the -url option to specify the URL of the database to which you want to connect. The syntax of the -url option is as follows:

-url=URL

The default setting is:

-url=jdbc:oracle:oci:@

To specify the JDBC Thin driver, use a setting of the following form:

-url=jdbc:oracle:thin:@host:port/servicename

In this syntax, host is the name of the host on which the database is running, port is the port number, and servicename is the name of the database service.

User Name and Password for Database Connection

JPublisher requires the -user option, which specifies an Oracle user name and password, so that it can connect to the database. If you do not enter the -user option, then JPublisher prints an error message and stops execution.

The syntax of the -user option is as follows:

-user=username/password
-u username/password

Both formats are equivalent. The second one is provided as a convenient command-line shortcut.

For example, the following command directs JPublisher to connect to the database with the user name scott:

% jpub -user=scott -input=demoin -dir=demo -mapping=oracle -package=corp
Enter scott password: password

Mappings for Built-In Types

The -builtintypes option controls data type mappings for all the built-in data types except the LOB types, which are controlled by the -lobtypes option, and the different numeric types, which are controlled by the -numbertypes option. The syntax of the -builtintypes option is as follows:

-builtintypes={jdbc|oracle}

Table 6-2 lists the data types affected by the -builtintypes option and shows their Java type mappings for -builtintypes=oracle and -builtintypes=jdbc, which is the default.

Mappings for LOB Types

The -lobtypes option controls data type mappings for LOB types. The syntax of the -lobtypes option is as follows:

-lobtypes={jdbc|oracle}

Table 6-3 shows how these types are mapped for -lobtypes=oracle, which is the default, and for -lobtypes=jdbc.

Mappings for Numeric Types

The -numbertypes option controls data type mappings for numeric SQL and PL/SQL types. The syntax of the -numbertypes option is as follows:

-numbertypes={jdbc|objectjdbc|bigdecimal|oracle}

The following choices are available:

• In JDBC mapping, most numeric data types are mapped to Java primitive types, such as int and float, and DECIMAL and NUMBER are mapped to java.math.BigDecimal.

• In Object JDBC mapping, which is the default, most numeric data types are mapped to Java wrapper classes, such as java.lang.Integer and java.lang.Float. DECIMAL and NUMBER are mapped to java.math.BigDecimal.

• In BigDecimal mapping, all numeric data types are mapped to java.math.BigDecimal.

• In Oracle mapping, all numeric data types are mapped to oracle.sql.NUMBER.

Table 6-4 lists the data types affected by the -numbertypes option and shows their Java type mappings for -numbertypes=jdbc and -numbertypes=objectjdbc, which is the default.

Mappings for User-Defined Types

The -usertypes option controls whether JPublisher implements the Oracle ORAData interface or the standard SQLData interface in generated classes for user-defined types. The syntax of the -usertypes option is as follows:

-usertypes={oracle|jdbc}

When -usertypes=oracle, which is the default, JPublisher generates ORAData classes for object, collection, and object reference types.

When -usertypes=jdbc, JPublisher generates SQLData classes for object types. JPublisher does not generate classes for collection or object reference types in this case. You must use java.sql.Array for all collection types and java.sql.Ref for all object reference types.

Mappings for All Types

The -mapping option specifies mapping for all data types, so offers little flexibility between types. The syntax of the -mapping option is as follows:

-mapping={jdbc|objectjdbc|bigdecimal|oracle}

The -mapping=oracle setting is equivalent to setting all the type mapping options to oracle. The other -mapping settings are equivalent to setting -numbertypes equal to the value of -mapping and setting the other type mapping options to their defaults. This is summarized in Table 6-5.

Style File for Java-to-Java Type Mappings

JPublisher style files allow you to specify Java-to-Java type mappings. One use for this is to ensure that generated classes can be used in Web services. You use the -style option to specify the name of a style file. You can use the -style option multiple times. The settings accumulate in order. The syntax of the -style option is as follows:

-style=stylename

Typically, Oracle supplies the style files, but there may be situations in which you would edit or create your own. To use the Oracle style file for Web services in Oracle Database 11g, for example, use the following setting:

-style=webservices10

Adding an Entry to the Default Type Map

Use the -adddefaulttypemap option to append an entry or a comma-delimited list of entries to the JPublisher default type map. In addition, JPublisher uses this option internally. The syntax of this option is:

-adddefaulttypemap=list_of_typemap_entries

Additional Entry to the User Type Map

Use the -addtypemap option to append an entry or a comma-delimited list of entries to the JPublisher user type map. The syntax of this option is:

-addtypemap=list_of_typemap_entries

Default Type Map for JPublisher

JPublisher uses the -defaulttypemap option internally to set up predefined type map entries in the default type map. The syntax of this option is:

-defaulttypemap=list_of_typemap_entries

The difference between the -adddefaulttypemap option and the -defaulttypemap option is that -adddefaulttypemap appends entries to the default type map, while -defaulttypemap replaces the existing default type map with the specified entries. To clear the default type map, use the following setting:

-defaulttypemap=

You may want to do this to avoid conflicts between the default type map and the user type map, for example.

Replacement of the JPublisher Type Map

Use the -typemap option to specify an entry or a comma-delimited list of entries to set up the user type map. The syntax of this option is:

-typemap=list_of_typemap_entries

The difference between the -typemap option and the -addtypemap option is that -typemap replaces the existing user type map with the specified entries and -addtypemap appends entries to the user type map. To clear the user type map, use the following setting.

-typemap=

You may want to do this to avoid conflicts between the default type map and the user type map, for example.

Method Access

The -access option determines the access modifier that JPublisher includes in generated constructors, attribute setter and getter methods, member methods on object wrapper classes, and methods on PL/SQL packages. The syntax of this option is:

-access={public|protected|package}

JPublisher uses the possible option settings as follows:

• public

  Methods are generated with the public access modifier. This is the default option setting.

• protected

  Methods are generated with the protected access modifier.

• package

  The access modifier is omitted, so generated methods are local to the package.

You may want to use a setting of -access=protected or -access=package if you want to control the usage of the generated JPublisher wrapper classes. For example, when you provide customized versions of the wrapper classes as subclasses of the JPublisher-generated classes, but do not want to provide access to the generated superclasses.

You can specify the -access option on the command line or in a properties file.

Case of Java Identifiers

For class or attribute names that you do not specify in an INPUT file or on the command line, the -case option affects the case of Java identifiers that JPublisher generates, including class names, method names, attribute names embedded within getXXX() and setXXX() method names, and arguments of generated method names. The syntax of this option is:

-case={mixed|same|lower|upper}

Table 6-6 describes the possible values for the -case option.

For class or attribute names that you specify through JPublisher options or the INPUT file, JPublisher retains the case of the letters in the specified name and overrides the -case option.

Code Generation Type

The -codegen option determines whether the generated Java code uses SQLJ runtime or JDBC runtime. The syntax of this option is:

-codegen=jdbc|sqlj

The default value is sqlj.

The setting -codegen=jdbc indicates that JPublisher generates Java code using JDBC runtime. Generation of Java code purely relying on JDBC runtime is a new feature of JPublisher 11g release. The setting -codegen=sqlj indicates that JPublisher generates Java code using SQLJ runtime. This is the default behavior of JPublisher 11g release. All the earlier JPublisher releases use only SQLJ runtime to generate Java code.

Method Filtering According to Parameter Modes

In some cases, particularly for generating code for Web services, not all parameter modes are supported in method signatures or attributes for the target usage of your code. The -filtermodes option enables you to filter generated code according to parameter modes. The syntax of this option is:

-filtermodes=list_of_modes_to_filter_out_or_filter_in

You can specify the following for the -filtermodes option:

• in

• out

• inout

• return

Start the option setting with a 1 to include all possibilities by default, which would mean no filtering. Then list specific modes or types each followed by a minus sign (-), indicating that the mode or type should be excluded. Alternatively, start with a 0 to include no possibilities by default, which would mean total filtering, then list specific modes or types each followed by a plus sign (+), indicating that the mode or type should be allowed.

The following examples would have the same result, allowing only methods that have parameters of the in or return mode. Separate the entries by commas.

-filtermodes=0,in+,return+

-filtermodes=1,out-,inout-

Method Filtering According to Parameter Types

In some cases, particularly for generating code for Web services, not all parameter types are supported in method signatures or attributes for the target usage of your code. The -filtertypes option enables you to filter generated code according to parameter types. The syntax of this option is:

-filtertypes=list_of_types_to_filter_out_or_filter_in

You can specify the following settings for the -filtertypes option:

• Any qualified Java type name

  Specify package and class, such as java.sql.SQLData, oracle.sql.ORAData.

• .ORADATA

  This setting indicates any ORAData or SQLData implementations.

• .STRUCT, .ARRAY, .OPAQUE, .REF

  Each of these settings indicates any types that implement ORAData or SQLData with the corresponding _SQL_TYPECODE specification.

• .CURSOR

  This setting indicates any SQLJ iterator types and java.sql.ResultSet.

• .INDEXBY

  This setting indicates any indexed-by table types.

• .ORACLESQL

  This setting indicates all oracle.sql.XXX types.

Start the option setting with a 1 to include all possibilities by default, indicating no filtering, then list specific modes or types each followed by a minus sign (-), indicating that the mode or type should be excluded. Alternatively, start with a 0 to include no possibilities by default, indicating total filtering, then list specific modes or types each followed by a plus sign (+), indicating that the mode or type should be allowed.

This first example filters out only .ORADATA and .ORACLESQL. The second example filters everything except .CURSOR and .INDEXBY:

-filtertypes=1,.ORADATA-,.ORACLESQL-

-filtertypes=0,.CURSOR+,.INDEXBY+

The .STRUCT, .ARRAY, .OPAQUE, and .REF settings are subcategories of the .ORADATA setting. Therefore, you can have specifications, such as the following, which filters out all ORAData and SQLData types except those with a typecode of STRUCT:

-filtertypes=1,.ORADATA-,.STRUCT+

Alternatively, to allow ORAData or SQLData types in general, with the exception of those with a typecode of ARRAY or REF:

-filtertypes=0,.ORADATA+,.ARRAY-,.REF-

Code Generation Adherence to the JavaBeans Specification

The -generatebean option is a flag that you can use to ensure that generated classes follow the JavaBeans specification. The syntax of this option is:

-generatebean={true|false}

The default setting is -generatebean=false. With the -generatebean=true setting, some generated methods are renamed so that they are not assumed to be JavaBean property getter or setter methods. This is accomplished by prefixing the method names with an underscore (_). For example, for classes generated from SQL table types, VARRAY, or indexed-by table, method names are changed as follows.

Method names are changed from:

public int getBaseType() throws SQLException;
public int getBaseTypeName() throws SQLException;
public int getDescriptor() throws SQLException;

to:

public int _getBaseType() throws SQLException;
public String _getBaseTypeName() throws SQLException; 
public ArrayDecscriptor _getDescriptor() throws SQLException; 

The changes in return types are necessary because the JavaBeans specification says that a getter method must return a bean property, but getBaseType(), getBaseTypeName(), and getDescriptor() do not return a bean property.

Class and Interface Naming Pattern

It is often desirable to follow a certain naming pattern for Java classes, user subclasses, and interfaces generated for user-defined SQL types or packages. The -genpattern option, which you can use in conjunction with the -sql or -sqlstatement option, enables you to define such patterns conveniently and generically. The syntax of this option is:

-genpattern=pattern_specifications

Consider the following explicit command-line options:

-sql=PERSON:PersonBase:PersonUser#Person
-sql=STUDENT:StudentBase:StudentUser#Student
-sql=GRAD_STUDENT:GradStudentBase:GradStudentUser#GradStudent

The following pair of options is equivalent to the preceding set of options:

-genpattern=%1Base:%1User#%1
-sql=PERSON,STUDENT,GRAD_STUDENT

By definition, %1 refers to the default base names that JPublisher would create for each SQL type. By default, JPublisher would create the Person Java type for the PERSON SQL type, the Student Java type for the STUDENT SQL type, and the GradStudent Java type for the GRAD_STUDENT SQL type. So %1Base becomes PersonBase, StudentBase, and GradStudentBase, respectively. Similar results are produced for %1User.

If the -sql option specifies the output names, then %2, by definition, refers to the specified names. For example, the following pair of options has the same effect as the earlier pair:

-genpattern=%2Base:%2User#%2
-sql=PERSON:Person,STUDENT:Student,GRAD_STUDENT:GradStudent

The following example combines the -genpattern option with the -sqlstatement option:

-sqlstatement.class=SqlStmts -genpattern=%2Base:%2User:%2

These settings are equivalent to the following:

-sqlstatement.class=SqlStmtsBase:SqlStmtsUser#SqlStmts

Generation of User Subclasses

The value of the -gensubclass option determines whether JPublisher generates initial source files for user-provided subclasses and, if so, what format these subclasses should have. The syntax of this option is:

-gensubclass={true|false|force|call-super}

For -gensubclass=true, which is the default, JPublisher generates code for the subclass only if it finds that no source file is present for the user subclass. The -gensubclass=false setting results in JPublisher not generating any code for user subclasses.

For -gensubclass=force, JPublisher always generates code for user subclasses. It overwrites any existing content in the corresponding .java and .class files if they already exist. Use this setting with caution.

The setting -gensubclass=call-super is equivalent to -gensubclass=true, except that JPublisher generates slightly different code. By default, JPublisher generates only constructors and methods necessary for implementing an interface, for example, the ORAData interface. JPublisher indicates how superclass methods or attribute setter and getter methods can be called, but places this code inside comments. With the call-super setting, all getters, setters, and other methods are generated.

The idea is that you can specify this setting if you use Java development tools based on class introspection. Only methods relating to SQL object attributes and SQL object methods are of interest, and JPublisher implementation details remain hidden. In this case you can point the tool at the generated user subclass.

You can specify the -gensubclass option on the command line or in a properties file.

Generation of Package Classes and Wrapper Methods

The -methods option determines whether:

• JPublisher generates wrapper methods for methods, or stored procedures in SQL object types and PL/SQL packages.

• Overloaded method names are allowed.

• Methods will attempt to reestablish a JDBC connection if an SQLException is caught.

The syntax for the -methods option is:

-methods={all|none|named|always,overload|unique,noretry|retry}

For -methods=all, which is the default setting among the first group of settings, JPublisher generates wrapper methods for all the methods in the SQL object types and PL/SQL packages it processes. This results in generation of a SQLJ class if the underlying SQL object or package actually defines methods and if not, a non-SQLJ class. Prior to Oracle Database 10g, SQLJ classes were always generated for the all setting.

For -methods=none, JPublisher does not generate wrapper methods. In this case, JPublisher does not generate classes for PL/SQL packages, because they would not be useful without wrapper methods.

For -methods=named, JPublisher generates wrapper methods only for the methods explicitly named in the INPUT file.

The -methods=always setting also results in wrapper methods being generated. However, for backward compatibility with Oracle8i and Oracle9i JPublisher versions, this setting always results in SQLJ classes being generated for all SQL object types, regardless of whether the types define methods.

Among the overload and unique settings, -methods=overload is the default and specifies that method names in the generated code can be overloaded, such as the following:

int foo(int);
int foo(String);

Alternatively, the -methods=unique setting specifies that all method names must be unique. This is required for Web services. Consider the following functions:

function foo (a VARCHAR2(40)) return VARCHAR2;
function foo ( x int, y int) return int;

With the default -methods=overload setting, these functions are published as follows:

String foo(String a);
java.math.BigDecimal foo(java.math.BigDecimal x, java.math.BigDecimal y);

With the -methods=unique setting, these functions are published using a method-renaming mechanism based on the first letter of the return type and argument types, as shown in the following example:

String foo(String a);
java.math.BigDecimal fooBBB(java.math.BigDecimal x, java.math.BigDecimal y);

With the -methods=retry setting, JPublisher generates constructors with DataSource arguments and extra code for each method published. A JDBC operation in a method is enclosed within a try...catch block. If an SQLException is raised when the method is processed, then the extra code will attempt to reestablish the JDBC connection and process the SQL operation again. If the attempt to reconnect fails, then the original SQLException is thrown again.

For -methods=retry, JPublisher generates code different from that generated for -methods=noretry, in two respects:

• An additional constructor, which takes a DataSource object as parameter, is generated. The DataSource object is used to get a new connection at operation invocation time.

• A new JDBC connection is requested if an SQLException is thrown.

The -methods=retry setting takes effect only for PL/SQL stored procedures, SQL statements, AQ, and Web services call-ins for Java classes.

To specify a setting of all, none, named, or always at the same time as you specify a setting of overload or unique and a setting for retry or noretry, use a comma to separate the settings. This is shown in the following example:

-methods=always,unique,retry

You can specify the -methods option on the command line or in a properties file.

Omission of Schema Name from Name References

In publishing user-defined SQL types, such as objects and collections, when JPublisher references the type names in Java wrapper classes, it generally qualifies the type names with the database schema name, such as SCOTT.EMPLOYEE for the EMPLOYEE type in the SCOTT schema.

However, by specifying the -omit_schema_names option, you instruct JPublisher not to qualify SQL type names with schema names. The syntax of this option is:

-omit_schema_names

When this option is specified, names are qualified with a schema name only under the following circumstances:

• You declare the user-defined SQL type in a schema other than the one to which JPublisher is connected. A type from another schema always requires a schema name to identify it.

• You declare the user-defined SQL type with a schema name on the command line or in an INPUT file. The use of a schema name with the type name on the command line or INPUT file overrides the -omit_schema_names option.

Omitting the schema name makes it possible for you to use classes generated by JPublisher when you connect to a schema other than the one used when JPublisher is invoked, as long as the SQL types that you use are declared identically in the two schemas.

ORAData and SQLData classes generated by JPublisher include a static final String field that names the user-defined SQL type matching the generated class. When the code generated by JPublisher is processed, the SQL type name in the generated code is used to locate the SQL type in the database. If the SQL type name does not include the schema name, then the type is looked up in the schema associated with the current connection when the code generated by JPublisher is processed. If the SQL type name includes the schema name, then the type is looked up in that schema.

When the -omit_schema_names option is enabled, JPublisher generates the following code in the Java wrapper class for a SQL object type and similar code to wrap a collection type:

 public Datum toDatum(Connection c) throws SQLException
    {
      if (__schemaName != null)
      {
        return _struct.toDatum(c, __schemaName + "." + _SQL_NAME);
      }
      return _struct.toDatum(c, typeName);
    }
    private String __schemaName = null;
    public void __setSchemaName(String schemaName) { __schemaName = schemaName; }
  }
  

The __setSchemaName() method enables you to explicitly set the schema name at run time so that SQL type names can be qualified by schema even if JPublisher was run with the -omit_schema_names option enabled. Being qualified by schema is necessary if a SQL type needs to be accessed from another schema.

Holder Types for Output Arguments

There are no OUT or IN OUT designations in Java, but values can be returned through holders. In JPublisher, you can specify one of three alternatives for holders:

• Arrays, which is the default

• JAX-RPC holder types

• Function returns

The -outarguments option enables you to specify the mechanism to use, through a setting of array, holder, or return, respectively. This feature is particularly useful for Web services. The syntax of this option is:

-outarguments={array|holder|return}

Name for Generated Java Package

The -package option specifies the name of the Java package that JPublisher generates. The name appears in a package declaration in each generated class. The syntax for this option is:

-package=package_name

If you use the -dir and -d options, the directory structure in which JPublisher places the generated files reflects the package name as well as the -dir and -d settings.

Example 1  Consider the following command:

% jpub -dir=/a/b -d=/a/b -package=c.d -sql=PERSON:Person ...

JPublisher generates the files /a/b/c/d/Person.java and /a/b/c/d/Person.class.

In addition, the Person class includes the following package declaration:

package c.d;

Example 2 Now consider the following command:

% jpub -dir=/a/b -d=/a/b -package=c.d -sql=PERSON:Person -input=myinputfile

Assume that myinputfile includes the following:

SQL PERSON AS e.f.Person

In this case, the package information in the INPUT file overrides the -package option on the command line. JPublisher generates the files /a/b/e/f/Person.java and /a/b/e/f/Person.class, with the Person class including the following package declaration:

package e.f;

If you do not specify a package name, then JPublisher does not generate any package declaration. The output .java files are placed directly into the directory specified by the -dir option or into the current directory by default. The output .class files are placed directly into the directory specified by the -d option or into the current directory.

Sometimes JPublisher translates a type that you do not explicitly request, because the type is required by another type that is translated. For example, it may be an attribute of the requested type. In this case, the .java and .class files declaring the required type are also placed into the package specified on the command line, in a properties file or the INPUT file.

By contrast, JPublisher never translates packages or stored procedures that you do not explicitly request, because packages or stored procedures are never strictly required by SQL types or by other packages or stored procedures.

Serializability of Generated Object Wrapper Classes

The -serializable option specifies whether the Java classes that JPublisher generates for SQL object types implement the java.io.Serializable interface. The default setting is -serializable=false. The syntax for this option is:

-serializable={true|false}

Please note the following if you choose to set -serializable=true:

• Not all object attributes are serializable. In particular, none of Oracle LOB types, such as oracle.sql.BLOB, oracle.sql.CLOB, or oracle.sql.BFILE, can be serialized. Whenever you serialize objects with such attributes, the corresponding attribute values are initialized to null after deserialization.

• If you use object attributes of type java.sql.Blob or java.sql.Clob, then the code generated by JPublisher requires that the Oracle JDBC rowset implementation be available in the classpath. This is provided in the ocrs12.jar library at ORACLE_HOME/jdbc/lib. In this case, the underlying value of Clob and Blob objects is materialized, serialized, and subsequently retrieved.

• Whenever you deserialize objects containing attributes that are object references, the underlying connection is lost, and you cannot issue setValue() or getValue() calls on the reference. For this reason, JPublisher generates the following method into your Java classes whenever you specify -serializable=true:

  void restoreConnection(Connection)
  

  After deserialization, call this method once for a given object or object reference to restore the current connection into the reference or, respectively, into all transitively embedded references.

Generation of toString() Method on Object Wrapper Classes

You can use the -tostring flag to tell JPublisher to generate an additional toString() method for printing out an object value. The output resembles SQL code you would use to construct the object. The default setting is false. The syntax for this option is:

-tostring={true|false}

Rename main Method

You can use -nomain=true to avoid generating Java methods with the signature main(String[]). This option applies to SQL publishing and server-side Java class publishing. The syntax for this option is:

-nomain[=true|false]

The -dbjava option automatically sets -nomain=true because of Java stored procedure limitation. In case a method with the signature main(String[]) is to be generated with the -nomain=true setting, then JPublisher will rename the method, for example, into main0(Stringp[]).

The default setting is:

-nomain=false

Generation of SQL types

JPublisher may generate new SQL types when publishing PL/SQL types and generating PL/SQL wrappers for server-side Java classes. The -overwritedbtypes option determines how JPublisher names the generated SQL types. The syntax for this option is:

-overwritedbtypes={true|false}

Prior to Oracle Database 10g release 2 (10.2), JPublisher checked the database for naming conflicts and chose a name, which was not already in use, for the generated SQL type. Since Oracle Database 10g release 2 (10.2), JPublisher generates SQL type names by default, regardless of the existing type names in the database. The -overwritedbtypes=true setting, which is the default, overwrites the existing types if the type name is the same as that of the generated SQL type. This enables JPublisher to generate exactly the same PL/SQL wrappers over different runs.

To ensure that JPublisher does not overwrite any type inside the database while executing the generated PL/SQL wrapper, you must explicitly specify -overwritedbtypes=false.

A frequently reported problem in releases prior to Oracle Database 10g release 2 (10.2) is that after the generated PL/SQL wrapper is processed, rerunning the JPublisher command generates a different set of SQL types. A workaround for this problem is to run the PL/SQL dropper script before the JPublisher command is rerun.

File Names for PL/SQL Scripts

The -plsqlfile option specifies the name of a wrapper script and a dropper script generated by JPublisher. The syntax for this option is:

-plsqlfile=plsql_wrapper_script,plsql_dropper_script

The wrapper script contains instructions to create SQL types to map to PL/SQL types and instructions to create the PL/SQL package that JPublisher uses for any PL/SQL wrappers or call specs, conversion functions, wrapper functions, and table functions. The dropper script contains instructions to drop these entities.

You must load the generated files into the database, using SQL*Plus, for example, and run the wrapper script to install the types and package in the database.

If the files already exist, then they are overwritten. If no file names are specified, then JPublisher writes to files named plsql_wrapper.sql and plsql_dropper.sql.

JPublisher writes a note about the generated scripts, such as the following:

J2T-138, NOTE: Wrote PL/SQL package JPUB_PLSQL_WRAPPER to
file plsql_wrapper.sql. Wrote the dropping script to file plsql_dropper.sql.

Generation of PL/SQL Wrapper Functions

The -plsqlmap option specifies whether JPublisher generates wrapper functions for stored procedures that use PL/SQL types. Each wrapper function calls the corresponding stored procedure and invokes the appropriate PL/SQL conversion functions for PL/SQL input or output of the stored procedure. Only the corresponding SQL types are exposed to Java. The syntax for this option is:

-plsqlmap={true|false|always}

The setting can be any of the following:

• true

  This is the default. JPublisher generates PL/SQL wrapper functions only as needed. For any given stored procedure, if the Java code to call it and convert its PL/SQL types directly is simple enough and the PL/SQL types are used only as IN parameters or for the function return, then the generated code calls the stored procedure directly. It processes the PL/SQL input or output through the appropriate conversion functions.

• false

  JPublisher does not generate PL/SQL wrapper functions. If it encounters a PL/SQL type in a signature that cannot be supported by direct call and conversion, then it skips generation of Java code for the particular stored procedure.

• always

  JPublisher generates a PL/SQL wrapper function for every stored procedure that uses a PL/SQL type. This is useful for generating a proxy PL/SQL package that complements an original PL/SQL package, providing Java-accessible signatures for those functions or procedures that are inaccessible from Java in the original package.

Package for Generated PL/SQL Code

The -plsqlpackage option specifies the name of the PL/SQL package into which JPublisher places any generated PL/SQL code. This includes PL/SQL wrappers or call specifications, conversion functions to convert between PL/SQL and SQL types, wrapper functions to wrap stored procedures that use PL/SQL types, and table functions. The syntax for this option is:

-plsqlpackage=name_of_PLSQL_package

By default, JPublisher uses the package JPUB_PLSQL_WRAPPER.

Package for PL/SQL Index-By Tables

Use -plsqlindextable=array or -plsqlindextable=int to specify that PL/SQL index-by table of numeric and character types be mapped to Java array. The syntax for this option is:

-plsqlindextable=array|custom|int

The int specification defines the capacity of the Java array. The default capacity is 32768. The -plsqlindextable=custom setting specifies that PL/SQL index-by table be mapped to custom JDBC types, such as a class implementing ORAData.

The default setting is:

-plsqlindextable=custom

No Compilation or Translation

Use the -compile option to suppress the compilation of the generated .java files and, for backward-compatibility modes, to optionally suppress the translation of generated .sqlj files. The syntax for this option is:

-compile={true|false|notranslate}

With the default true setting, all generated classes are compiled into .class files. If you are in a backward-compatibility mode, then you can use the -compile=notranslate setting to suppress SQLJ translation and Java compilation of generated source files. This leaves you with .sqlj output from JPublisher, which you can translate and compile manually by using either the JPublisher -sqlj option or the SQLJ command-line utility directly. You can also use the -compile=false setting to proceed with SQLJ translation, but skip Java compilation. This leaves you with .java output from JPublisher, which you can compile manually.

If you are not in a backward-compatibility mode, such as if you use the default -compatible=oradata setting, then you can use a setting of -compile=false to skip compilation. In this scenario, the notranslate setting is not supported, because visible .sqlj files are not produced if you are not in a backward-compatibility mode.

Output Directories for Generated Source and Class Files

Use the -dir option to specify the root of the directory tree within which JPublisher places the .java source files or the .sqlj source files for backward-compatibility modes. The syntax for this option is:

-dir=directory_path
-d=directory_path

A setting of a period (.) explicitly specifies the current directory as the root of the directory tree. Similarly, use the -d option to specify the root of the directory tree within which JPublisher places compiled .class files, with the same functionality for a period (.) setting.

For each option with any nonempty setting, JPublisher also uses package information from the -package option or any package name included in an SQL option setting in the INPUT file. This information is used to determine the complete directory hierarchy for generated files.

For example, consider the following JPublisher command:

% jpub -user=scott -d=myclasses -dir=mysource -package=a.b.c  -sql=PERSON:Person,STUDENT:Student
Enter scott password: password

This results in the following output, relative to the current directory:

mysource/a/b/c/Person.java
mysource/a/b/c/PersonRef.java
mysource/a/b/c/Student.java
mysource/a/b/c/StudentRef.java

myclasses/a/b/c/Person.class
myclasses/a/b/c/PersonRef.class
myclasses/a/b/c/Student.class
myclasses/a/b/c/StudentRef.class

By default, source and class files are placed directly into the current directory, with no package hierarchy, regardless of the -package setting or any package specification in the INPUT file.

You can also explicitly specify this behavior with empty settings:

%jpub ... -d= -dir=

You can set these options on the command line or in a properties file.

Java Character Encoding

The -encoding option specifies the Java character encoding of the INPUT file that JPublisher reads and the source files that JPublisher writes. The default encoding is the value of the file.encoding system property or 8859_1 (ISO Latin-1), if this property is not set. The syntax for this option is:

-encoding=name_of_character_encoding

As a general rule, you do not have to set this option unless you specify an encoding for the SQLJ translator and Java compiler, which you can do with a SQLJ -encoding setting through the JPublisher -sqlj option. In this scenario, you should specify the same encoding for JPublisher as for SQLJ and the compiler.

You can use the -encoding option to specify any character encoding supported by your Java environment. If you are using the Sun Microsystems JDK, these options are listed in the native2ascii documentation, which you can find at the following URL:

http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/native2ascii.html

WSDL Document for Java and PL/SQL Wrapper Generation

The syntax for the -proxywsdl option is:

-proxywsdl=WSDL_URL

This option is used as follows:

% jpub -proxywsdl=META-INF/HelloService.wsdl ...

Given the Web services WSDL document at the 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 automatically sets the -proxyclasses option, uses the -proxyopts setting as input, and executes the following steps:

1. Invokes Oracle Database Web services assembler tool to produce Web services client proxy classes based on the WSDL document. These classes use Oracle Database Web services client run time to access the Web services specified in the WSDL document.

2. Creates Java wrapper classes for the Web services client proxy classes as appropriate or necessary. For each proxy class that has instance methods, a wrapper class is necessary to expose the instance methods as static methods. Even if there are no instance methods, a wrapper class is necessary if methods of the proxy class use anything other than Java primitive types in their calling sequences.

3. Creates PL/SQL wrappers for the generated classes, to make them accessible from PL/SQL. PL/SQL supports only static methods, so this step requires the wrapping of instance methods by static methods, This is performed in the previous step.

4. Loads generated code into the database assuming you have specified -user and -url settings and JPublisher has established a connection, unless you specifically bypass loading through the -proxyopts=noload setting.

The -endpoint option is typically used in conjunction with the -proxywsdl option.

Web Services Endpoint

You can use the -endpoint option in conjunction with the -proxywsdl option to specify the Web services endpoint. The endpoint is the URL to which the Web service is deployed and from which the client accesses it. The syntax for this option is:

-endpoint=Web_services_endpoint

Use this option as follows:

% jpub -proxywsdl=META-INF/HelloService.wsdl ...
       -endpoint=http://localhost:8888/javacallout/javacallout

With this command, the Java wrapper class generated by JPublisher includes the following code:

      ((Stub)m_port0)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, 
                     "http://localhost:8888/javacallout/javacallout");

Without the -endpoint option, there would instead be the following commented code:

      // Specify the endpoint and then uncomment the following statement:
      // ((Stub)m_port0)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, 
      //                "<endpoint not provided>");

If you do not specify the endpoint in the JPublisher command line, then you must manually alter the generated wrapper class to uncomment this code and specify the appropriate endpoint.

Proxy URL for WSDL

If a WSDL document used for Web services call-outs is accessed through a firewall, use the -httpproxy option in conjunction with the -proxywsdl option to specify a proxy URL to use in resolving the URL of the WSDL document. The syntax for this option is:

-httpproxy=proxy_URL

For example:

% jpub ... -httpproxy=http://www-proxy.oracle.com:80

Superuser for Permissions to Run Client Proxies

Use the -sysuser option to specify the name and password of a superuser account. This account is used in running the JPublisher-generated PL/SQL script that grants permissions that allow client proxy classes to access Web services using HTTP. The syntax for this option is:

-sysuser=superuser_name/superuser_password

For example:

-sysuser=sys/change_on_install

Without a -sysuser setting, JPublisher does not load the generated script granting permissions. Instead, it asks you to execute the script separately.

If the -url setting specifies a thin driver, then you must set up a password file for SYS, which authorizes logon as SYS, through the thin driver. To set up a password file, you must:

1. Add the remote_login_passwordfile option to the database parameter file. You must use either of the following settings:

   remote_login_passwordfile=shared
   
   remote_login_passwordfile=exclusive
   

2. Create a password file, if you have not already created one. You can do this by running the following command, where ORACLE_HOME/dbs/ is an existing directory:

   orapwd file="ORACLE_HOME/dbs/orapwlsqlj1" entries=100 force=y
   Enter password: password
   

3. Grant remote logon privileges to a user. This can be done as follows:

   % sqlplus /nolog
   SQL> CONN / AS sysdba
   Connected.
   SQL> GRANT sysdba TO scott;
   Grant succeeded.
   

Settings for the SQLJ Translator

In Oracle Database 11g, SQLJ translation is automatic by default when you run JPublisher. Translation is transparent, with no visible .sqlj files resulting from JPublisher code generation.

However, you can still specify SQLJ settings for the JPublisher invocation of the SQLJ translator by using the JPublisher -sqlj option. The syntax for this option is:

-sqlj=sqlj_options

For example:

% jpub -user=scott -sqlj -optcols=true -optparams=true -optparamdefaults=datatype1(size1),datatype2(size)
Enter scott password: password

You can also run JPublisher solely to translate .sqlj files that have already been produced explicitly, such as if you run JPublisher with the -compatible=sqlj setting, which skips the automatic SQLJ translation step and results in .sqlj output files from JPublisher. In this case, use no JPublisher options other than -sqlj. This is a way to accomplish manual SQLJ translation if the sqlj front-end script or executable is unavailable.

The commands following -sqlj are equivalent to the command you would give to the SQLJ translator utility directly. Here is an example:

% jpub -sqlj -d=outclasses -warn=none -encoding=SJIS Foo.sqlj

This is equivalent to the following, if the SQLJ command-line translator is available:

% sqlj -d=outclasses -warn=none -encoding=SJIS Foo.sqlj

Backward-Compatible Oracle Mapping for User-Defined Types

The -compatible option has two modes of operation:

• Through a setting of oradata or customdatum, you can explicitly specify an interface to be implemented by JPublisher-generated custom Java classes.

• Through a setting of sqlj, 8i, both8i, or 9i, you can specify a backward-compatibility mode.

You can select either of the two modes, but not both.

The syntax for this option is:

-compatible={oradata|customdatum|both8i|8i|9i|10.1|sqlj}

Using -compatible to Specify an Interface

If -usertypes=oracle, then you have the option of setting -compatible=customdatum, to implement the deprecated CustomDatum interface in your generated classes for user-defined types, instead of the default ORAData interface. CustomDatum was replaced by ORAData in Oracle9i Database, but is still supported for backward compatibility.

The default setting to use the ORAData interface is oradata. If you set -usertypes=jdbc, then a -compatible setting of customdatum or oradata is ignored.

If you use JPublisher in a pre-Oracle9i Database environment, in which the ORAData interface is not supported, then the CustomDatum interface is used automatically if -usertypes=oracle. You will receive an informational warning if -compatible=oradata, but the generation will take place.

Using -compatible to Specify a Backward-Compatibility Mode

Use the sqlj, 10.1, 9i, 8i, or both8i setting to specify a backward-compatibility mode.

The -compatible=sqlj setting instructs JPublisher to skip SQLJ translation and instead produce .sqlj files that you can work with directly. The sqlj setting has no effect on the generated code itself. To translate the resulting .sqlj files, you can use the SQLJ translator directly, if available, or use the JPublisher -sqlj option.

The -compatibility=10.1 setting specifies Oracle Database 10g release 1 (10.1) compatibility mode. In this mode, the JPublisher option -dbjava acts the same as -java in Oracle Database 10g release 1 (10.1).

The -compatibility=9i setting specifies Oracle9i compatibility mode. In this mode, JPublisher generates .sqlj files with the same code as would be generated by Oracle9i version.

The -compatible=8i setting specifies Oracle8i compatibility mode. This mode uses the CustomDatum interface, generating .sqlj files with the same code that would be generated by Oracle8i versions of JPublisher. The 8i setting is equivalent to setting several individual JPublisher options for backward compatibility to Oracle8i. For example, behavior of method generation is equivalent to that for -methods=always, and generation of connection context declarations is equivalent to that for -context=generated.

The -compatible=both8i setting is for an alternative Oracle8i compatibility mode. With this setting, wrapper classes are generated to implement both the ORAData and CustomDatum interfaces. Code is generated as it would have been by Oracle8i version of JPublisher. This setting is generally preferred over the -compatible=8i setting, because support for ORAData is required for programs running in the middle tier, such as in Oracle Application Server. However, using ORAData requires an Oracle9i release 1 (9.0.1) or later JDBC driver.

Classpath for Translation and Compilation

Use the -classpath option to specify the Java classpath for JPublisher to use in resolving Java source and classes during translation and compilation. The syntax for this option is:

-classpath=path1:path2:...:pathN

The following command shows an example of its usage, adding new paths to the existing classpath:

% jpub -user=scott -sql=PERSON:Person,STUDENT:Student -classpath=.:$ORACLE_HOME/jdbc/lib/ocrs12.jar:$CLASSPATH
Enter scott password: password

Java Compiler

Use the -compiler-executable option if you want Java code generated by JPublisher to be compiled by anything other than the compiler that JPublisher would use by default on your system. Specify the path to an alternative compiler executable file. The syntax for this option is:

-compiler-executable=path_to_compiler_executable

Java Version

Use the -vm option if you want to use a JVM other than the JVM that JPublisher would use by default on your system. Specify the path to an alternative Java executable file. The syntax for this option is:

-vm=path_to_JVM_executable

As an example, assume that JDK 1.4 is installed on a UNIX system at the location JDK14, relative to the current directory. Run JPublisher with the following command to use the JDK 1.4 JVM and compiler when publishing Web services client proxy classes:

% jpub -vm=JDK14/bin/java -compiler-executable=JDK14/bin/java -proxywsdl=hello.wsdl

Understanding the Translation Statement

The translation statement in the INPUT file identifies the names of the user-defined types and PL/SQL packages that you want JPublisher to translate. Optionally, the translation statement can also specify a Java name for the type or package, a Java name for attribute identifiers, and whether there are any extended classes.

One or more translation statements can appear in the INPUT file. The structure of a translation statement is as follows:

( SQL name
| SQL [schema_name.]toplevel  [(name_list)]
| TYPE type_name)
[GENERATE java_name_1]
[AS java_name_2] 
[TRANSLATE  
     database_member_name AS simple_java_name
 { , database_member_name AS simple_java_name}* 
]

The following sections describe the components of the translation statement.

SQL name | TYPE type_name Enter SQL name to identify a SQL type or a PL/SQL package that you want JPublisher to translate. JPublisher examines the name, determines whether it is for a user-defined type or a PL/SQL package, and processes it appropriately. If you use the reserved word toplevel in place of name, JPublisher translates the top-level subprograms in the schema to which JPublisher is connected.

Instead of SQL, it is permissible to enter TYPE type_name if you are specifying only object types. However, the TYPE syntax is deprecated.

You can enter name as schema_name.name to specify the schema to which the SQL type or package belongs. If you enter schema_name.toplevel, JPublisher translates the top-level subprograms in schema schema_name. In conjunction with TOPLEVEL, you can also supply name_list, which is a comma-delimited list of names to be published, enclosed in parentheses. JPublisher considers only top-level functions and procedures that match this list. If you do not specify this list, JPublisher generates code for all top-level subprograms.

SQL "CaseSenstiveType" AS CaseSensitiveType

SQL SCOTT."CaseSensitiveType" AS CaseSensitiveType

SQL "Scott"."CaseSensitiveType" AS CaseSensitiveType

GENERATE java_name_1 AS java_name_2 The AS clause specifies the name of the Java class that represents the SQL user-defined type or PL/SQL package being translated.

When you use the AS clause without a GENERATE clause, JPublisher generates the class in the AS clause and maps it to the SQL type or PL/SQL package.

When you use both the GENERATE clause and the AS clause for a SQL user-defined type, the GENERATE clause specifies the name of the Java class that JPublisher generates, which is referred to as the base class. The AS clause specifies the name of a Java class that extends the generated base class, which is referred to as the user subclass. JPublisher produces an initial version of the user subclass, and you will typically add code for your desired functionality. JPublisher maps the SQL type to the user subclass, and not to the base class. If you later run the same JPublisher command to republish the SQL type, then the generated class is overwritten, but the user subclass is not.

The java_name_1 and java_name_2 can be any legal Java names and can include package identifiers. The case of the Java names overrides the -case option.

TRANSLATE database_member_name AS simple_java_name This clause optionally specifies a different name for an attribute or method. The database_member_name is the name of an attribute of a SQL object type or the name of a method of an object type or PL/SQL package. The attribute or method is to be translated to simple_java_name, which can be any legal Java name. The case of the Java name overrides the -case option. This name cannot have a package name.

If you do not use TRANSLATE...AS to rename an attribute or method, or if JPublisher translates an object type not listed in the INPUT file, then JPublisher uses the database name of the attribute or method as the Java name. If applicable, the Java name is modified according to the setting of the -case option. Reasons why you may want to rename an attribute or method include:

• The name contains characters other than letters, digits, and underscores.

• The name conflicts with a Java keyword.

• The type name conflicts with another name in the same scope. This can happen, for example, if the program uses two types with the same name from different schemas.

Remember that your attribute names will appear embedded within getXXX() and setXXX() method names, so you may want to capitalize the first letter of your attribute names. For example, if you enter:

TRANSLATE FIRSTNAME AS FirstName

JPublisher generates a getFirstName() method and a setFirstName() method. In contrast, if you enter:

TRANSLATE FIRSTNAME AS firstName

JPublisher generates a getfirstName() method and a setfirstName() method.

TRANSLATE FIRSTNAME AS null

Package Naming Rules in the INPUT File  You can specify a package name by using a fully qualified class name in the INPUT file. If you use a simple, unqualified class name in the INPUT file, then the fully qualified class name includes the package name from the -package option. This is demonstrated in the following examples:

• Assume the following in the INPUT file:

  SQL A AS B
  

  And assume the setting -package=a.b. In this case, a.b is the package and a.b.B is the fully qualified class name.

• Assume that you enter the following in the INPUT file and there is no -package setting:

  SQL A AS b.C
  

  The package is b, and b.C is the fully qualified class name.

Translating Additional Types It may be necessary for JPublisher to translate additional types that are not listed in the INPUT file. This is because JPublisher analyzes the types in the INPUT file for dependencies before performing the translation and translates any additional required types.

Consider the example in "Sample JPublisher Translation". Assume that the object type definition for EMPLOYEE includes an attribute called ADDRESS, and ADDRESS is an object with the following definition:

CREATE OR REPLACE TYPE address AS OBJECT
(
    street     VARCHAR2(50),
    city       VARCHAR2(50),
    state      VARCHAR2(30),
    zip        NUMBER
);

In this case, JPublisher would first translate ADDRESS, because that would be necessary to define the EMPLOYEE type. In addition, ADDRESS and its attributes would all be translated in the same case, because they are not specifically mentioned in the INPUT file. A class file would be generated for Address.java, which would be included in the package specified on the command line.

JPublisher does not translate PL/SQL packages you do not request, because user-defined types or other PL/SQL packages cannot have dependencies on PL/SQL packages.

Sample Translation Statement

To better illustrate the function of the INPUT file, consider an updated version of the example in "Sample JPublisher Translation".

Consider the following command:

% jpub -user=scott -input=demoin -numbertypes=oracle -usertypes=oracle -dir=demo -d=demo -package=corp -case=same
Enter scott password: password

And assume that the INPUT file demoin contains the following:

SQL employee AS Employee 
TRANSLATE NAME AS Name HIRE_DATE AS HireDate

The -case=same option specifies that generated Java identifiers maintain the same case as in the database, except where you specify otherwise. Any identifier in a CREATE TYPE or CREATE PACKAGE declaration is stored in uppercase in the database unless it is quoted. In this example, the -case option does not apply to the EMPLOYEE type, because EMPLOYEE is specified to be translated as the Java class Employee.

For attributes, attribute identifiers not specifically mentioned in the INPUT file remain in uppercase, but JPublisher translates NAME and HIRE_DATE as Name and HireDate, as specified.

The translated EMPLOYEE type is written to the following files, relative to the current directory, for UNIX systems in this example, reflecting the -package, -dir, and -d settings:

demo/corp/Employee.java
demo/corp/Employee.class

Requesting the Same Java Class Name for Different Object Types

If you request the same Java class name for two different object types, the second class overwrites the first without warning. Consider that the INPUT file contains:

type PERSON1 as Person
type PERSON2 as Person

JPublisher creates the Person.java file for PERSON1 and then overwrites it for the PERSON2 type.

Requesting the Same Attribute Name for Different Object Attributes

If you request the same attribute name for two different object attributes, JPublisher generates getXXX() and setXXX() methods for both attributes without issuing a warning message. The question of whether the generated class is valid in Java depends on whether the two getXXX() methods with the same name and the two setXXX() methods with the same name have different argument types so that they may be unambiguously overloaded.

Specifying Nonexistent Attributes

If you specify a nonexistent object attribute in the TRANSLATE clause, then JPublisher ignores it without issuing a warning message.

Consider the following example from an INPUT file:

type PERSON translate X as attr1

A situation in which X is not an attribute of PERSON does not cause JPublisher to issue a warning message.

JPublisher Reserved Terms

Do not use any of the following reserved terms as SQL or Java identifiers in the INPUT file.

AS 
GENERATE 
IMPLEMENTS 
SQLSTATEMENTS_TYPE 
SQLSTATEMENTS_METHOD 
SQL 
TRANSLATE 
TOPLEVEL 
TYPE 
VERSION