6 Command-Line Options and Input Files

This chapter describes the usage and syntax details of JPublisher option settings and input files to specify program behavior. It is organized into the following sections:

JPublisher Options

The following sections list and discuss JPublisher command-line options:

JPublisher Option Summary

Table 6-1 summarizes JPublisher options. For default values, the abbreviation, NA, means not applicable. The Category column refers to the corresponding conceptual area, indicating the section of this chapter where the option is discussed.

Table 6-1 Summary of JPublisher Options

Option Name Description Default Value Category

-access

Determines the access modifiers that JPublisher includes in generated method definitions.

public

Java code generation

-adddefaulttypemap

Appends an entry to the JPublisher default type map.

NA

Type maps

-addtypemap

Appends an entry to the JPublisher user type map.

NA

Type maps

-builtintypes

Specifies the data type mappings, jdbc or oracle, for built-in data types that are not numeric or large object (LOB).

jdbc

Data type mappings

-case

Specifies the case of Java identifiers that JPublisher generates.

mixed

Java code generation

-classpath

Adds to the Java classpath for JPublisher to resolve Java source and classes during translation and compilation.

Empty

Java environment

-compatible

Specifies a compatibility mode and modifies the behavior of -usertypes=oracle.

See Also: "JPublisher Backward-Compatibility Modes and Settings"

oradata

Backward compatibility

-compile

Determines whether to proceed with Java compilation or suppress it. This option also affects SQLJ translation for backward-compatibility modes.

true

Input/output

-compiler-executable

Specifies a Java compiler version, in case you want a version other than the default.

NA

Java environment

-context

Specifies the class that JPublisher uses for SQLJ connection contexts. This can be the DefaultContext class, a user-specified class, or a JPublisher-generated inner class.

DefaultContext

Connection

-defaulttypemap

Sets the default type map that JPublisher uses.

Refer to "JPublisher User Type Map and Default Type Map".

Type maps

-d

Specifies the root directory for placement of compiled class files.

Empty (all files directly present in the current directory)

Input/output

-dir

Specifies the root directory for placement of generated source files.

Empty (all files directly present in the current directory)

Input/output

-driver

Specifies the driver class that JPublisher uses for Java Database Connectivity (JDBC) connections to the database.

oracle.jdbc. OracleDriver

Connection

-encoding

Specifies the Java encoding of JPublisher input and output files.

The value of the system property file.encoding

Input/output

-endpoint

Specifies a Web service endpoint. This option is used in conjunction with the -proxywsdl option.

NA

Web services

-filtermodes

Filters code generation according to specified parameter modes.

NA

Java code generation

-filtertypes

Filters code generation according to specified parameter types.

NA

Java code generation

-generatebean

Ensures that generated code conforms to the JavaBeans specification.

false

Java code generation

-genpattern

Defines naming patterns for generated code.

NA

Java code generation

-gensubclass

Specifies whether and how to generate stub code for user subclasses.

true

Java code generation

-httpproxy

Specifies a proxy URL to resolve the URL of a Web Services Description Language (WSDL) document for access through a firewall. This option is used in conjunction with the -proxywsdl option.

NA

Web services

-input or -i

Specifies a file that lists the types and packages that JPublisher translates.

NA

Input files/items

-java

Specifies server-side Java classes for which JPublisher generates client-side classes.

NA

Input files/items

-lobtypes

Specifies the jdbc or oracle data type mapping that JPublisher uses for BLOB and CLOB types.

oracle

Data type mappings

-mapping

Specifies the mapping that generated methods support for object attribute types and method argument types.

Note: This option is deprecated in favor of the "XXXtypes" mapping options, but is supported for backward compatibility.

objectjdbc

Data type mappings

-methods

Determines whether JPublisher generates wrapper methods for stored procedures of translated SQL objects and PL/SQL packages. This option also determines whether JPublisher generates SQLJ classes or non-SQLJ classes, and whether it generates PL/SQL wrapper classes at all. There are settings to specify whether overloaded methods are allowed.

all

Java code generation

-numbertypes

Specifies the data type mappings, such as jdbc, objectjdbc, bigdecimal, or oracle, that JPublisher uses for numeric data types.

objectjdbc

Data type mappings

-omit_schema_names

Instructs JPublisher not to include the schema in SQL type name references in generated code.

Disabled (schema included in type names)

Java code generation

-outarguments

Specifies the holder type, such as arrays, Java API for XML-based Remote Procedure Call (JAX-RPC) holders, or function returns, for Java implementation of PL/SQL output parameters.

array

Java code generation

-overwritedbtypes

Specifies whether to ignore naming conflicts when creating SQL types.

true

PL/SQL code generation

-package

Specifies the name of the Java package into which JPublisher generates Java wrapper classes.

NA

Java code generation

-plsqlfile

Specifies a wrapper script to create and a dropper script to drop SQL conversion types for PL/SQL types and the PL/SQL package that JPublisher will use for generated PL/SQL code.

plsql_wrapper.sql, plsql_dropper.sql

PL/SQL code generation

-plsqlmap

Specifies whether to generate PL/SQL wrapper functions for stored procedures that use PL/SQL types.

true

PL/SQL code generation

-plsqlpackage

Specifies the PL/SQL package into which JPublisher generates PL/SQL code, such as call specifications, conversion functions, and wrapper functions.

JPUB_PLSQL_WRAPPER

PL/SQL code generation

-props or -p

Specifies a file that contains JPublisher options in addition to those listed on the command line.

NA

Input files/items

-proxyclasses

Specifies Java classes for which JPublisher generates wrapper classes and PL/SQL wrappers according to the -proxyopts setting. For Web services, you will typically use -proxywsdl instead, which uses -proxyclasses behind the scenes.

NA

Web services

-proxyopts

Specifies required layers of Java and PL/SQL wrappers and additional related settings.

Is used as input for the -proxywsdl and -proxyclasses options.

jaxrpc

Web services

-proxywsdl

Specifies the URL of a WSDL document for which Web services client proxy classes and associated Java wrapper classes are generated along with PL/SQL wrappers.

NA

Web services

-serializable

Specifies whether the code generated for object types implements the java.io.Serializable interface.

false

Java code generation

-sql or -s

Specifies object types and packages, or subsets of packages, for which JPublisher generates Java classes, and optionally subclasses and interfaces.

NA

Input files/items

-sqlj

Specifies SQLJ option settings for the JPublisher invocation of the SQLJ translator.

NA

SQLJ

-sqlstatement

Specifies SQL queries or data manipulation language (DML) statements for which JPublisher generates Java classes, and optionally subclasses and interfaces, with appropriate methods.

NA

Input files/items

-style

Specifies the name of a "style file" for Java-to-Java type mappings.

NA

Data type mappings

-sysuser

Specifies the name and password for a superuser account that can be used to grant permissions to execute wrappers that access Web services client proxy classes in the database.

NA

Web services

-tostring

Specifies whether to generate a toString() method for object types.

false

Java code generation

-typemap

Specifies the JPublisher type map.

Empty

Type maps

-types

Specifies object types for which JPublisher generates code.

Note: This option is deprecated in favor of -sql, but is supported for backward compatibility.

NA

Input files/items

-url

Specifies the URL that JPublisher uses to connect to the database.

jdbc:oracle:oci:@

Connection

-user or -u

Specifies an Oracle user name and password for connection.

NA

Connection

-usertypes

Specifies the jdbc or oracle type mapping that JPublisher uses for user-defined SQL types.

oracle

Data type mappings

-vm

Specifies a Java version, in case you want a version other than the default.

NA

Java environment


JPublisher Option Tips

Be aware of the following usage notes for JPublisher options:

  • JPublisher always requires the -user option or its shorthand equivalent -u.

  • Options are processed in the order in which they appear. Options from an INPUT file are processed at the point where the -input or -i option occurs. Similarly, options from a properties file are processed at the point where the -props or -p option occurs.

  • As a rule, if a particular option appears more than once, JPublisher uses the value from the last occurrence. However, this is not true for the following options, which are cumulative:

    -sql

    -types, which is deprecated

    -java

    -addtypemap or -adddefaulttypemap

    -style

  • In general, separate options and corresponding option values by an equal sign (=). However, when the following options appear on the command line, you can also use a space as a separator:

    -sql or -s, -user or -u, -props or -p, and -input or -i

  • With the -sqlj option, you must use a space instead of an equal sign, because SQLJ settings following the -sqlj option use equal signs. Consider the following example, where each entry after "-sqlj" is a SQLJ option:

    % jpub -user=scott/tiger -sql=PERSON:Person -sqlj -optcols=true -optparams=true
           -optparamdefaults=datatype1(size1),datatype2(size)
    
    
  • It is advisable to specify a Java package for generated classes with the -package option, either on the command line or in a properties file. For example, you could enter the following on the command line:

    % jpub -sql=Person -package=e.f ...
    
    

    Alternatively, you could enter the following in the properties file:

    jpub.sql=Person
    jpub.package=e.f
    ...
    
    

    These statements direct JPublisher to create the class Person in the Java package e.f, that is, to create the class e.f.Person.

  • If you do not specify a type or package in the INPUT file or on the command line, then JPublisher translates all types and packages in the user schema according to the options specified on the command line or in the properties file.

Notational Conventions

The JPublisher option syntax used in the following sections uses the following notational conventions:

  • Braces {...} enclose a list of possible values. Specify only one of the values within the braces.

  • A vertical bar | separates alternatives within braces.

  • Terms in italics are for user input. Specify an actual value or string.

  • Terms in boldface indicate default values.

  • Square brackets [...] enclose optional items. In some cases, however, square brackets or parentheses are part of the syntax and must be entered verbatim. In this case, this manual uses boldface: [...] or (...).

  • Ellipsis points ... immediately following an item, or items enclosed in brackets, mean that you can repeat the item any number of times.

  • Punctuation symbols other than those described in this section are entered as shown in this manual. These include "." and "@", for example.

Options for Input Files and Items to Publish

This section documents the following JPublisher options that specify key input, either JPublisher input files, such as INPUT files or properties files, or items to publish, such as SQL objects, PL/SQL packages, SQL queries, SQL DML statements, or server-side Java classes:

  • Options for input files: -input, -props

  • Options for items to publish: -java, -sql, -sqlstatement, -types

These options are discussed in alphabetic order.

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.

Notes:

  • To use the -java option, you must also specify the -user and -url settings for a database connection.

  • Functionality of the -java option requires the sqljutl.jar library to be loaded in the database. For more information, refer to "Required Database Setup".

  • It is advisable to use the same Java Development Kit (JDK) on the client as on the server.

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

Note:

If JPublisher cannot find a specified class in the schema, a specified schema or the schema of the logged-in user, then it uses the Class.forName() method to search for the class among system classes in the Java virtual machine (JVM), typically Java run-time environment (JRE) or JDK classes.

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) introduces the -java option to publish server-side Java classes. Oracle Database 10g release 2 (10.2) introduces 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.

Note:

It is typical to explicitly use the -proxyopts option with the -proxyclasses option than with the -proxywsdl option. For the use of -proxywsdl with 10.0.x releases of Oracle Application Server 10g, the default -proxyopts=jaxrpc setting is sufficient.

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.

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

Note:

Encoding settings, either set through the JPublisher -encoding option or the Java file.encoding setting, do not apply to Java properties files. Properties files always use the 8859_1 encoding. This is a feature of Java in general, and not of JPublisher in particular. However, you can use Unicode escape sequences in a properties file.

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.

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

Notes:

  • Only SQL names that are not case-sensitive are supported on the JPublisher command line. If a user-defined type was defined in a case-sensitive way in SQL, using quotes, then you must specify the name in the JPublisher INPUT file instead of specifying the user-defined type, in quotes, on the command line.

  • If your desired class and interface names follow a pattern, you can use the -genpattern command-line option for convenience.

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

Notes:

  • In an INPUT file, put a stored procedure name in quotes if it is case-sensitive. For example, "proc1". JPublisher assumes that names that are not in quotes are not case-sensitive.

  • Case-sensitive names are not supported on the JPublisher command line.

  • Specified stored procedure names can end in the wildcard character, "%". The specification "myfunc%", for example, matches all stored procedures that have their name starting with myfunc, such as myfunc1.

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().

Note:

If your desired class and interface names follow a pattern, then you can use the -genpattern option for convenience.

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.

Example: Using an XML Type This example shows the use of an XML type, SYS.XMLTYPE, with the -sqlstatement option. Assume the following table is created using SQL*Plus:

SQL>  CREATE TABLE xmltab (a XMLTYPE);

Now, assume the following JPublisher command to publish an INSERT statement:

% jpub  -u scott/tiger -style=webservices10
        -sqlstatement.addEle="insert into xmltab values(:{a sys.xmltype})"

This command causes the generation of the following methods:

public int addEle(javax.xml.transform.Source a) throws java.rmi.RemoteException;
public int addEleiS(javax.xml.transform.Source[] a) 
                                        throws java.rmi.RemoteException;

This is because SYS.XMLTYPE is mapped to oracle.sql.SimpleXMLType, which the webservices10 style file further maps to javax.xml.transform.Source.

The method name, addEleiS, is used to avoid method overloading according to JPublisher naming conventions, with i reflecting the int return type and S reflecting the Source parameter type.

Note:

This example assumes that JDK 1.4 is installed and used by JPublisher. If it is installed but not used by default, then you can set the -vm and -compiler-executable options to specify a JDK 1.4 JVM and compiler. For more information, refer to"Java Environment Options".

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

Note:

The -types option is currently supported for compatibility, but it is deprecated. Use the -sql option instead.

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

Connection Options

This section documents options related to the database connection that JPublisher uses. The options are discussed in the alphabetic order.

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.

Note:

With a user-defined class, instances of that class must be used for output from the getConnectionContext() method or for input to the setConnectionContext() method. Refer to "Connection Contexts and Instances in SQLJ Classes", for information about these methods.

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.

Note:

The use of system identifiers (SIDs) is deprecated in Oracle Database 10g, but it is still supported for backward compatibility. Their use is of the form host:port:sid.

For the Oracle JDBC Oracle Call Interface (OCI) driver, use oci in the connect string in any new code. For backward compatibility, however, oci8 is still accepted for Oracle8i drivers.

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 and password tiger:

% jpub -user=scott/tiger -input=demoin -dir=demo -mapping=oracle -package=corp

Options for Data Type Mappings

The following options control the data type mappings that JPublisher uses to translate object types, collection types, object reference types, and PL/SQL packages to Java classes:

  • The -usertypes option controls JPublisher behavior for user-defined types, in conjunction with the -compatible option for oracle mapping. Specifically, it controls whether JPublisher implements the Oracle ORAData interface or the standard SQLData interface in generated classes, and whether JPublisher generates code for collection and object reference types.

  • The -numbertypes option controls data type mappings for numeric types.

  • The -lobtypes option controls data type mappings for the BLOB, CLOB, and BFILE types.

  • The -builtintypes option controls data type mappings for non-numeric, non-LOB, and predefined SQL and PL/SQL types.

These four options are known as the type-mapping options.

For an object type, JPublisher applies the mappings specified by the type-mapping options to the object attributes and the arguments and results of any methods included with the object. The mappings control the types that the generated accessor methods support. For example, they support the types the getXXX() methods return and the setXXX() methods take.

For a PL/SQL package, JPublisher applies the mappings to the arguments and results of the methods in the package. For a collection type, JPublisher applies the mappings to the element type of the collection.

In addition, there is a subsection here for the -style option, which you can use to specify Java-to-Java type mappings, typically to support Web services. This involves an extra JPublisher step. A SQL type is mapped to a Java type that is not supported by Web services, in the JPublisher-generated base class. Then this Java type is mapped to a Java type that is supported by Web services, in the JPublisher-generated user subclass.

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.

Table 6-2 Mappings for Types Affected by the -builtintypes Option

SQL Data Type Oracle Mapping Type JDBC Mapping Type

CHAR, CHARACTER, LONG, STRING, VARCHAR, VARCHAR2

oracle.sql.CHAR

java.lang.String

RAW, LONG RAW

oracle.sql.RAW

byte[]

DATE

oracle.sql.DATE

java.sql.Timestamp

TIMESTAMP

TIMESTAMP WITH TZ

TIMESTAMP WITH LOCAL TZ

oracle.sql.TIMESTAMP

oracle.sql.TIMESTAMPTZ

oracle.sql.TIMESTAMPLTZ

java.sql.Timestamp


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.

Table 6-3 Mappings for Types Affected by the -lobtypes Option

SQL Data Type Oracle Mapping Type JDBC Mapping Type

CLOB

oracle.sql.CLOB

java.sql.Clob

BLOB

oracle.sql.BLOB

java.sql.Blob

BFILE

oracle.sql.BFILE

oracle.sql.BFILE


Notes:

  • BFILE is an Oracle-specific SQL type, so there is no standard java.sql.Bfile Java type.

  • NCLOB is an Oracle-specific SQL type. It denotes an NCHAR form of use of a CLOB and is represented as an instance of oracle.sql.NCLOB in Java.

  • The java.sql.Clob and java.sql.Blob interfaces were introduced in the JDK 1.2 versions.

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.

Table 6-4 Mappings for Types Affected by the -numbertypes Option

SQL Data Type JDBC Mapping Type Object JDBC Mapping Type

BINARY_INTEGER, INT, INTEGER, NATURAL, NATURALN, PLS_INTEGER, POSITIVE, POSITIVEN, SIGNTYPE

int

java.lang.Integer

SMALLINT

int

java.lang.Integer

REAL

float

java.lang.Float

DOUBLE PRECISION, FLOAT

double

java.lang.Double

DEC, DECIMAL, NUMBER, NUMERIC

java.math.BigDecimal

java.math.BigDecimal


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.

Notes:

  • The -usertypes=jdbc setting requires JDK 1.2 or later, because the SQLData interface is a JDBC 2.0 feature.

  • With certain settings of the -compatible option, a -usertypes=oracle setting results in classes that implement the deprecated CustomDatum interface instead of ORAData.

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}

Note:

This option is deprecated in favor of the more specific type mapping options: -usertypes, -numbertypes, -builtintypes, and -lobtypes. However, it is still supported for backward compatibility.

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.

Table 6-5 Relation of -mapping Settings to Other Mapping Option Settings

-mapping Setting -builtintypes= -numbertypes= -lobtypes= -usertypes=

-mapping=oracle

oracle

oracle

oracle

oracle

-mapping=jdbc

jdbc

jdbc

oracle

oracle

-mapping=objectjdbc (default)

jdbc

objectjdbc

oracle

oracle

-mapping=bigdecimal

jdbc

bigdecimal

oracle

oracle


Note:

Options are processed in the order in which they appear on the command line. Therefore, if the -mapping option precedes one of the specific type mapping options, -builtintypes, -lobtypes, -numbertypes, or -usertypes, then the specific type mapping option overrides the -mapping option for the relevant types. If the -mapping option follows one of the specific type mapping options, then the specific type mapping option is ignored.

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 10g, for example, use the following setting:

-style=webservices10

Type Map Options

JPublisher code generation is influenced by entries in the JPublisher user type map or default type map, primarily to make signatures with PL/SQL types accessible to JDBC. A type map entry has one of the following formats:

-type_map_option=opaque_sql_type:java_type
-type_map_option=numeric_indexed_by_table:java_numeric_type[max_length] 
-type_map_option=char_indexed_by_table:java_char_type[max_length](elem_size) 
-type_map_option=plsql_type:java_type:sql_type:sql_to_plsql_func:plsql_to_sql_func

In the type map syntax, sql_to_plsql_func and plsql_to_sql_func are for functions that convert between SQL and PL/SQL. Note that [...] and (...) are part of the syntax. Also note that some operating systems require you to quote command-line options that contain special characters.

The related options, which are discussed in alphabetic order in the following sections, are -addtypemap, -adddefaulttypemap, -defaulttypemap, and -typemap. The difference between -addtypemap and -typemap is that -addtypemap appends entries to the user type map, while -typemap replaces the existing user type map with the specified entries. Similarly, -adddefaulttypemap appends entries to the default type map, while -defaulttypemap replaces the existing default type map with the specified entries.

Here are some sample type map settings, from a properties file that uses the -defaulttypemap and -adddefaulttypemap options:

jpub.defaulttypemap=SYS.XMLTYPE:oracle.xdb.XMLType
jpub.adddefaulttypemap=BOOLEAN:boolean:INTEGER:
SYS.SQLJUTL.INT2BOOL:SYS.SQLJUTL.BOOL2INT
jpub.adddefaulttypemap=INTERVAL DAY TO SECOND:String:CHAR:
SYS.SQLJUTL.CHAR2IDS:SYS.SQLJUTL.IDS2CHAR
jpub.adddefaulttypemap=INTERVAL YEAR TO MONTH:String:CHAR:
SYS.SQLJUTL.CHAR2IYM:SYS.SQLJUTL.IYM2CHAR

Be aware that you must avoid conflicts between the default type map and user type map.

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.

See Also:

"JPublisher User Type Map and Default Type Map" for additional information, including a caution about conflicts between the type maps.

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.

Java Code-Generation Options

This section documents options that specify JPublisher characteristics and behavior for Java code generation. For example, there are options to accomplish the following:

  • Filter generated code according to parameter modes or parameter types

  • Ensure that generated code conforms to the JavaBeans specification

  • Specify naming patterns

  • Specify how stubs are generated for user subclasses

  • Specify whether generated code is serializable

The following options are described in alphabetical order: -access, -case, -filtermodes, -filtertypes, -generatebean, -genpattern, -gensubclass, -methods, -omit_schema_names, -outarguments, -package, -serializable, and -tostring.

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.

Note:

Wrapper classes for object references and VARRAY and nested table types are not affected by the value of the -access option.

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.

Table 6-6 Values for the -case Option

-case Option Value Description

mixed (default)

The first letter of every word unit of a class name or of every word unit after the first word unit of a method name is in uppercase. All other characters are in lowercase. An underscore (_), a dollar sign ($), or any character illegal in Java constitutes a word unit boundary and is removed without warning. A word unit boundary also occurs after get or set in a method name.

same

JPublisher does not change the case of letters from the way they are represented in the database. Underscores and dollar signs are retained. JPublisher removes any other character illegal in Java and issues a warning message.

upper

JPublisher converts lowercase letters to uppercase and retains underscores and dollar signs. It removes any other character illegal in Java and issues a warning message.

lower

JPublisher converts uppercase letters to lowercase and retains underscores and dollar signs. It removes any other character illegal in Java and issues a warning message.


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.

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

Note:

This is the pattern expected for Web services. Specify an output name and use that as the interface name, and append Base for the generated class and User for the user subclass.

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

Note:

For backward compatibility, JPublisher also supports the setting true as equivalent to all, the setting false as equivalent to none, and the setting some as equivalent to named.

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.

Note:

The use of oracle.jdbc.pool.OracleDataSource requires JDK 1.3 or later.

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.

Note:

Although this option behaves as a boolean option, you cannot specify -omit_schema_names=true or -omit_schema_names=false. Specify -omit_schema_names to enable it, and do nothing to leave it disabled.

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.

Notes:

  • If there are conflicting package settings between a -package option setting and a package setting in the INPUT file, the precedence depends on the order in which the -input and -package options appear on the command line. The -package setting takes precedence if that option is after the -input option. Otherwise, the INPUT file setting takes precedence.

  • If you do not use the -dir and -d options, or if you explicitly give them empty settings, then JPublisher places all generated files directly in the current directory, with no package hierarchy, regardless of the -package setting.

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 the 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

PL/SQL Code Generation Options

This section documents the following options that specify JPublisher behavior in generating PL/SQL code:

  • -overwritedbtypes

    Specifies whether naming conflicts are checked before creating SQL types.

  • -plsqlfile

    Specifies scripts to use in creating and dropping SQL types and PL/SQL packages.

  • -plsqlmap

    Specifies whether PL/SQL wrapper functions are generated

  • -plsqlpackage

    Specifies the name of the PL/SQL package in which JPublisher generates PL/SQL call specs, conversion functions, wrapper functions, and table functions.

These options are mostly used to support Java calls to stored procedures that use PL/SQL types. The options specify the creation and use of corresponding SQL types and the creation and use of PL/SQL conversion functions and PL/SQL wrapper functions that use the corresponding SQL types for input or output. This enables access through JDBC.

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

Note:

You must create this package in the database by running the SQL script generated by JPublisher.

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

Input/Output Options

This section documents options related to JPublisher input and output files and locations. These are listed in the order in which they are discussed:

  • -compile

    Use this option if you want to suppress compilation, and optionally, SQLJ translation, if JPublisher is in a backward-compatibility mode.

  • -dir

    Use this option to specify where the generated source files are placed.

  • -d

    Use this option to specify where the compiled class files are placed.

  • -encoding

    Use this option to specify the Java character encoding of the INPUT file that JPublisher reads and the .sqlj and .java files that JPublisher writes.

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/tiger -d=myclasses -dir=mysource -package=a.b.c
       -sql=PERSON:Person,STUDENT:Student

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.

Note:

SQLJ has -dir and -d options as well, with the same functionality. However, when you use the JPublisher -sqlj option to specify SQLJ settings, use the JPublisher -dir and -d options, which take precedence over any SQLJ -dir and -d settings.

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

Note:

Encoding settings, either set through the JPublisher -encoding option or the Java file.encoding setting, do not apply to Java properties files, including those specified through the JPublisher -props option. Properties files always use the 8859_1 encoding. This is a feature of Java in general and not JPublisher in particular. However, you can use Unicode escape sequences in a properties file.

Options to Facilitate Web Services Call-Outs

This section documents options and related concepts for accessing Java classes from server-side Java or PL/SQL. In particular, these options may be used to access Web services client code from inside the database, referred to as Web services call-outs. This section comprises the following topics:

The following list is a summary of the options relevant to Web services call-outs and how they relate to each other:

  • -proxyclasses=class1,class2,...,classN

    This option specifies Java classes for which Java and PL/SQL wrappers will be generated. For Web services, this option is used behind the scenes by the -proxywsdl option and is set automatically to process generated client proxy classes.

    Alternatively, you can use this option directly, for general purposes, when you want to create Java and PL/SQL wrappers for Java classes.

    The -proxyclasses option takes the -proxyopts setting as input.

  • -proxyopts=setting1,setting2,...

    This option specifies JPublisher behavior in generating wrapper classes and PL/SQL wrappers. This is usually, but not necessarily, for Web services. For typical usage of the -proxywsdl option, the -proxyopts default setting is sufficient. If you directly use the -proxyclasses option, then you may want specific -proxyopts settings.

  • -proxywsdl=WSDL_URL

    Use this option to generate Web services client proxy classes and appropriate Java and PL/SQL wrappers, given the WSDL document at the specified URL.

    The -proxywsdl option uses the -proxyclasses option behind the scenes and takes the -proxyopts setting as input.

  • -endpoint=Web_services_endpoint

    Use this option in conjunction with the -proxywsdl option to specify the Web services endpoint.

  • -httpproxy=proxy_URL

    Where the WSDL document is accessed through a firewall, use this option to specify a proxy URL to use in resolving the URL of the WSDL document.

  • -sysuser=superuser_name/superuser_password

    Use this option to specify the name and password for the superuser account used to grant permissions for the client proxy classes to access Web services using HTTP.

Notes:

  • The features described here require the dbwsclient.jar library to be installed in Oracle Database 10g.

  • Several previously existing JPublisher options are used in conjunction with wrapper generation as discussed here: -dir, -d, -plsqlmap, -plsqlfile, -plsqlpackage, and -package. You can also specify a database connection through the -user and -url options so that JPublisher can load generated entities into the database.

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/HelloServiceEJB.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 the Oracle Database Web services assembler tool to produce Web services client proxy classes based on the WSDL document. These classes use the 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.

Note:

When using -proxywsdl:
  • You must use the -package option to determine the package for generated Java classes.

  • For -proxyopts, the default jaxrpc setting is sufficient for use with 10.0.x releases of Oracle Application Server 10g. This setting uses the singleton mechanism for publishing instance methods of the Web services client proxy classes. For use with the 9.0.4 release of Oracle Application Server 10g or with earlier releases, set -proxyopts=soap.

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/HelloServiceEJB.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" password=change_on_install entries=100 force=y
    
    
  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.
    
    

See Also:

Oracle Database JDBC Developer's Guide and Reference for details of setting up a remote SYS logon

Option to Access SQLJ Functionality

This section documents the -sqlj option, which you can use to pass SQLJ options to the SQLJ translator through the JPublisher command line.

Settings for the SQLJ Translator

In Oracle Database 10g, 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/tiger -sqlj -optcols=true -optparams=true
       -optparamdefaults=datatype1(size1),datatype2(size)

Notes:

  • There is no equal sign (=) following -sqlj.

  • All other JPublisher options must precede the -sqlj option. Any option setting following -sqlj is taken to be a SQLJ option and is passed to the SQLJ translator. In the preceding example, -optcols, -optparams, and -optparamdefaults are SQLJ options.

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

Notes:

  • As an alternative to specifying SQLJ option settings through the -sqlj option, you can specify them in the sqlj.properties file that JPublisher supports.

  • The -compiler-executable option, if set, is passed to the SQLJ translator to specify the Java compiler that the translator will use to compile Java code.

Backward Compatibility Option

This section documents the -compatible option, which you can use to specify any of the following:

  • The interface for JPublisher to implement in generated classes

  • Whether JPublisher should skip SQLJ translation, resulting in visible .sqlj output files

  • A backward-compatibility mode to use JPublisher output in an Oracle9i or Oracle8i environment

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 behaves 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 the 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 the 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.

Note:

In any compatibility mode that results in the generation of visible .sqlj files, remember that if you are generating Java wrapper classes for a SQL type hierarchy and any of the types contains stored procedures, then, by default, JPublisher generates .sqlj files for all the SQL types, and not just the types that have stored procedures.

Java Environment Options

This section discusses JPublisher options that you can use to determine the Java environment:

  • The -classpath option specifies the Java classpath that JPublisher and SQLJ use to resolve classes during translation and compilation.

  • The -compiler-executable option specifies the Java compiler for compiling the code generated by JPublisher.

  • The -vm option specifies the JVM through which JPublisher is invoked.

In a UNIX environment, the jpub script specifies the location of the Java executable that runs JPublisher. This script is generated at the time you install your database or application server instance. If the jpub script uses a Java version prior to JDK 1.4, then some JPublisher functionality for Web services, such as call-outs and mapping to the SYS.XMLType, are unavailable.

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/tiger -sql=PERSON:Person,STUDENT:Student
       -classpath=.:$ORACLE_HOME/jdbc/lib/ocrs12.jar:$CLASSPATH

Note:

SQLJ also has a -classpath option. If you use the SQLJ -classpath option, following the JPublisher -sqlj option, then that setting is used for the classpath for translation and compilation, and any JPublisher -classpath option setting is ignored. It is more straightforward to use only the JPublisher -classpath option.

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/javac
       -proxywsdl=hello.wsdl

SQLJ Migration Options

In Oracle Database 10g release 2 (10.2), JPublisher provides the following command-line options to support migrating SQLJ to JDBC applications:

  • -migrate

    This option enables you to turn on SQLJ migration. The syntax for setting this option is as follows:

    -migrate[=true|false]
    
    

    The -migrate and -migrate=true settings are equivalent. Both these settings indicate that JPublisher should migrate SQLJ programs specified on the command line to JDBC programs. The -migrate=false turns off the migration mode, and SQLJ programs are translated and compiled into a Java program that possibly depends on the SQLJ run time. By default, if this option is not specified, then JPublisher behaves like -migrate=false.

  • -migconn

    This option enables you to specify the default JDBC connection used by the migrated code. The default JDBC connection replaces the default DefaultContext instance in the SQLJ run time. The syntax for setting this option is as follows:

    -migconn=getter:getter,setter:setter
    -migconn=name[[:datasource|modifier][,modifier]*]
    
    

    In the first syntax, the getter and setter settings specify the getter and setter methods for the default connection. For example:

    -migconn=getter:Test.getDefConn,setter:Test.setDefConn
    
    

    In the second syntax, the name setting specifies the default JDBC connection. The optional datasource setting provides a JNDI data source location for initializing the default JDBC connection. The modifier settings add the modifiers for the default connection variable. You can specify more than one modifier by using multiple modifier settings. Examples of the usage of the second syntax are as follows:

    -migconn=_defaultConn:public,static
    -migconn=Test._defaultConn
    -migconn=Test._defaultConn:jdbc/MyDataSource
    -migconn=_defaultConn:public,static,final
    
    
  • -migrsi

    This option enables you to specify an interface for all ResultSet iterator classes. The syntax for setting this option is as follows:

    -migrsi=java_interface_name
    
    

    For example:

    -migrsi=ResultSetInterface
    
    
  • -migsync

    This option enables you to mark static variables as synchronized. The syntax for setting this option is as follows:

    -migsync[=true|false]
    
    

    The -migsync and -migsync=true settings mark static variables generated for migration purpose as synchronized. If you do not want the variables to be marked as synchronized, then set -migsync=false. By default, JPublisher behaves like -migsync=true.

  • -migdriver

    This option enables you to specify the JDBC driver registered by the migrated code. The syntax for setting this option is as follows:

    -migdriver=class_name|no
    
    

    For example:

    -migdriver=oracle.jdbc.driver.OracleDriver
    
    

    By default, JPublisher behaves like -migdriver=oracle.jdbc.driver.OracleDriver. If you do not want the driver registration code to be generated during migration, then set this option as follows:

    -migdriver=no
    
    
  • -migcodegen

    This option enables you to specify whether the migrated code depends on an Oracle JDBC driver or a generic JDBC driver. The syntax for setting this option is as follows:

    -migcodegen=oracle|jdbc
    
    

    The default behavior is -migcodegen=oracle, indicating that Oracle-specific JDBC APIs are used in the migrated code.

  • -migserver

    This option enables you to specify whether to migrate the program to be used on the server. The syntax for setting this option is as follows:

    -migserver
    
    

JPublisher Input Files

The following sections describe the structure and contents of JPublisher input files:

Properties File Structure and Syntax

A properties file is an optional text file in which you can specify frequently used options. Specify the name of the properties file on the JPublisher command line with the -props option.

Note:

-props is the only option that you cannot specify in a properties file.

On each line in a properties file, enter only one option with its associated value. Enter each option setting with the following prefix, including the period:

jpub.

The jpub. prefix is case-sensitive. White space is permitted only directly in front of jpub.. Any other white space within the option line is significant.

Alternatively, JPublisher permits you to specify options with a double-dash (--), which is the syntax for SQL comments, as part of the prefix:

-- jpub.

A line that does not start with either of the prefixes shown is simply ignored by JPublisher.

In addition, you can use line continuation to spread a JPublisher option over several lines in the properties file. A line to be continued must have a backslash character (\) as the last character, immediately after the text of the line. Any leading space or double dash (--) on the line that follows the backslash is ignored. Consider the following sample entries:

/* The next three lines represent a JPublisher option
   jpub.sql=SQL_TYPE:JPubJavaType:MyJavaType,\
            OTHER_SQL_TYPE:OtherJPubType:MyOtherJavaType,\
            LAST_SQL_TYPE:My:LastType
*/
-- The next two lines represent another JPublisher option
-- jpub.addtypemap=PLSQL_TYPE:JavaType:SQL TYPE\
--                :SQL_TO_PLSQL_FUNCTION:PLSQL_TO_SQL_FUNCTION

Using this functionality, you can embed JPublisher options in SQL scripts, which may be useful when setting up PL/SQL-to-SQL type mappings.

JPublisher reads the options in the properties file in order, as if its contents were inserted on the command line at the point where the -props option is located. If you specify an option more than once, then the last value encountered by JPublisher overrides previous values, except for the following options, which are cumulative:

  • jpub.sql (or the deprecated jpub.types)

  • jpub.java

  • jpub.style

  • jpub.addtypemap

  • jpub.adddefaulttypemap

For example, consider the following command:

% jpub -user=scott/tiger -sql=employee -mapping=oracle -case=lower -package=corp -dir=demo

Now consider the following:

% jpub -props=my_properties

This command is equivalent to the first example if you assume that my_properties has a definition such as the following:

-- jpub.user=scott/tiger
// jpub.user=cannot_use/java_line_comments
jpub.sql=employee
/*
jpub.mapping=oracle
*/
Jpub.notreally=a jpub option
   jpub.case=lower
jpub.package=corp
    jpub.dir=demo

You must include the jpub. prefix at the beginning of each option name. If you enter anything other than white space or double dash (--) before the option name, then JPublisher ignores the entire line.

The preceding example illustrates that white space before jpub. is okay. It also shows that the jpub. prefix must be all lowercase, otherwise it is ignored. Therefore the following line from the preceding example will be ignored:

Jpub.notreally=a jpub option

INPUT File Structure and Syntax

Specify the name of the INPUT file on the JPublisher command line with the -input option. This file identifies SQL user-defined types and PL/SQL packages that JPublisher should translate. It also controls the naming of the generated classes and packages. Although you can use the -sql command-line option to specify user-defined types and packages, an INPUT file allows you a finer degree of control over how JPublisher translates them.

If you do not specify types or packages to translate in an INPUT file or on the command line, then JPublisher translates all user-defined types and PL/SQL packages in the schema to which it connects.

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.

Note:

If a user-defined type is defined in a case-sensitive way in SQL, then you must specify the name in quotes. For example:
SQL "CaseSenstiveType" AS CaseSensitiveType

Alternatively, you can also specify a schema name that is not case-sensitive:

SQL SCOTT."CaseSensitiveType" AS CaseSensitiveType

You can also specify a case-sensitive schema name:

SQL "Scott"."CaseSensitiveType" AS CaseSensitiveType

The AS clause is optional.

Avoid situations where a period (".") is part of the schema name or the type name itself.

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.

Note:

The Java keyword null has special meaning when used as the target Java name for an attribute or method, such as in the following example:
TRANSLATE FIRSTNAME AS null

When you map a SQL method to null, JPublisher does not generate a corresponding Java method in the mapped Java class. When you map a SQL object attribute to null, JPublisher does not generate the getter and setter methods for the attribute in the mapped Java class.

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.

Note:

If there are conflicting package settings between a -package option setting and a package setting in the INPUT file, then the precedence depends on the order in which the -input and -package options appear on the command line. The -package setting takes precedence if that option is after the -input option, else the INPUT file setting takes precedence.

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/tiger -input=demoin -numbertypes=oracle -usertypes=oracle -dir=demo -d=demo -package=corp -case=same

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 in this example, reflecting the -package, -dir, and -d settings:

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

INPUT File Precautions

This section describes possible INPUT file error conditions that JPublisher will currently not report. There is also a section for reserved terms.

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