3
Command-Line Options and Input Files

This chapter describes the use and syntax details of JPublisher option settings and input files to specify program behavior, organized as follows:

• JPublisher Options
• JPublisher Input Files

JPublisher Options

This section lists and discusses JPublisher command-line options, covering the following topics:

• JPublisher Option Summary
• JPublisher Option Tips
• Notational Conventions
• Detailed Descriptions of Options That Affect Datatype Mappings
• Detailed Descriptions of General JPublisher Options

JPublisher Option Summary

Table 3-1 lists the options that you can use on the JPublisher command line, their syntax, and a brief description. The abbreviation "n/toc.htm" represents "not applicable".

Table 3-1 Summary of JPublisher Options  

JPublisher Option Tips

Be aware of the following usage notes for JPublisher options.

• JPublisher always requires the -user option (or -u, its shorthand equivalent).
• 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.
• If a particular option appears more than once, JPublisher in general uses the value from the last occurrence. This is not true for the following options, however, which are cumulative.

  -sql (or the deprecated -types)

  -addtypemap or -adddefaulttypemap

• In general, options and corresponding option values must be separated by an equals sign ("="). When the following options appear on the command line, however, you are also permitted to use a space as a separator:

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

• It is advisable to specify a Java package for your generated classes, with the -package option, either on the command line or in a properties file. For example, on the command line you could enter:

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

  or in the properties file you could enter:

  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.

  "Properties File Structure and Syntax" describes the properties file.

• 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 follows these notational conventions:

• Angle brackets <...> enclose strings that the user supplies.
• Braces {...} enclose a list of possible values--specify only one of the values within the braces.
• A vertical bar | separates alternatives within brackets or braces.
• Terms in italics are like for values to input--specify an actual value or string.
• Square brackets [...] enclose optional items. In some cases, however, square brackets or parentheses are part of the syntax and need to be entered verbatim. In this case, this manual uses boldface: [...] or (...).
• An ellipsis ... immediately following an item (or items enclosed in brackets) means that you can repeat the item any number of times.
• Punctuation symbols other than those described above are entered as shown. These include "." and "@", for example.

The next section discusses the options that affect datatype mappings. The remaining options are then discussed in alphabetical order.

Detailed Descriptions of Options That Affect Datatype Mappings

The following options control which datatype mappings 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 (possibly in conjunction with the -compatible option for oracle mapping).
• The -numbertypes option controls datatype mappings for numeric types.
• The -lobtypes option controls datatype mappings for the BLOB and CLOB types.
• The -builtintypes option controls datatype mappings for non-numeric, non-LOB, predefined SQL and PL/SQL types.

These four options are known as the type-mapping options. (Another, less flexible option, -mapping, is discussed later. It is deprecated, but still supported for compatibility with older releases of JPublisher.)

In addition, JPublisher code generation is also controlled through entries in the JPublisher user type map or default type map. This is primarily to permit JPublisher to access signatures with PL/SQL types. You can refer to "Using Datatypes Unsupported by JDBC" for more information.

The following options are used in conjunction with JPublisher type mapping, and are described in the general options section:

• -addtypemap, -adddefaulttypemap, -defaulttypemap, and -typemap for specifying type mappings
• -plsqlfile, -plsqlmap, and -plsqlpackage for controlling the generation of PL/SQL wrapper code

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

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.

The -usertypes option 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. In addition, if -usertypes=oracle, you can use the -compatible option to specify using CustomDatum instead of ORAData for Oracle mapping. CustomDatum is replaced by ORAData and deprecated in Oracle9i, but is supported for backward compatibility. (Beyond this, you can use the -compatible option to specify a more general Oracle8i compatibility mode. See "Oracle8i Compatibility Mode".)

See "Details of Datatype Mapping" for more information about the different datatype mappings and factors you should consider in deciding which mappings to use.

The following sections provide additional information about these type mapping options.

Mappings for User-Defined Types (-usertypes)

-usertypes={oracle|jdbc}

The -usertypes option controls whether JPublisher implements the Oracle ORAData interface or the standard SQLData interface in generated classes for user-defined types.

When -usertypes=oracle (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--use java.sql.Array for all collection types and java.sql.Ref for all object reference types.

Backward-Compatible Oracle Mapping for User-Defined Types (-compatible)

-compatible={oradata|customdatum|both8i|8i}

If -usertypes=oracle, you have the option of setting -compatible=customdatum to implement the CustomDatum interface instead of the ORAData interface in your generated classes for user-defined types. CustomDatum is replaced by ORAData and deprecated in Oracle9i, but is still supported for backward compatibility. If -usertypes=jdbc, a -compatible setting of customdatum (or oradata) is ignored.

The default setting is oradata.

This option also has another mode of operation. With a setting of -compatible=8i or -compatible=both8i, you can specify the general Oracle8i compatibility mode. This not only uses CustomDatum, but also generates the same code that would be generated by Oracle8i JPublisher, and is equivalent to setting other JPublisher options for backward compatibility to Oracle8i. Behavior of method generation is equivalent to that for a -methods=always setting, and generation of connection context declarations is equivalent to that for a -context=generated setting. See "Oracle8i Compatibility Mode".

Mappings For Numeric Types (-numbertypes)

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

The -numbertypes option controls datatype mappings for numeric SQL and PL/SQL types. The following four choices are available:

• The JDBC mapping maps most numeric datatypes to Java primitive types such as int and float, and maps DECIMAL and NUMBER to java.math.BigDecimal.
• The Object JDBC mapping (the default) maps most numeric datatypes to Java wrapper classes such as java.lang.Integer and java.lang.Float, and maps DECIMAL and NUMBER to java.math.BigDecimal.
• The BigDecimal mapping maps all numeric datatypes to java.math.BigDecimal.
• The Oracle mapping maps all numeric datatypes to oracle.sql.NUMBER.

Table 3-2 lists the SQL and PL/SQL types affected by the -numbertypes option, and shows their Java type mappings for -numbertypes=jdbc and -numbertypes=objectjdbc (the default).

Table 3-2 Mappings for Types Affected by the -numbertypes Option  

Mappings For LOB Types (-lobtypes)

-lobtypes={jdbc|oracle}

The -lobtypes option controls datatype mappings for the LOB types. Table 3-3 shows how these types are mapped for -lobtypes=oracle (the default) and for -lobtypes=jdbc.

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

Mappings For Built-In Types (-builtintypes)

-builtintypes={jdbc|oracle}

The -builtintypes option controls datatype mappings for all the built-in datatypes except the LOB types (controlled by the -lobtypes option) and the different numeric types (controlled by the -numbertypes option). Table 3-4 lists the datatypes affected by the -builtintypes option and shows their Java type mappings for -builtintypes=oracle and -builtintypes=jdbc (the default).

Table 3-4 Mappings for Types Affected by the -builtintypes Option  

Mappings for All Types (-mapping)

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

The -mapping option specifies mapping for all datatypes, so offers little flexibility between types.

The setting -mapping=oracle 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, as summarized in Table 3-5.

Table 3-5 Relation of -mapping Settings to Settings of Other Mapping Options  

Detailed Descriptions of General JPublisher Options

This section discusses the remaining JPublisher options, for settings other than datatype mappings. Options in this section are in alphabetical order.

Method Access (-access)

-access={public|protected|package}

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

JPublisher uses the possible option settings as follows:

• public (default)--Methods are generated with the public access modifier.
• protected--Methods are generated with the protected access modifier.
• package--The access modifier is omitted, which means that generated methods are local to the package.

You might want to use a setting of -access=protected or -access=package if you need to control the usage of the generated JPublisher wrapper classes. Perhaps you are providing your own customized versions of the wrappers 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.

Additional Entry to the Default Type Map (-adddefaulttypemap)

-adddefaulttypemap=<list_of_typemap_entries>

This option permits you to append an entry or a comma-separated list of entries to the default type map used by JPublisher. This option is used internally by JPublisher for setting up its default type map. The format for type map entries is described in "Additional Entry to the User Type Map (-addtypemap)" below.

Additional Entry to the User Type Map (-addtypemap)

-addtypemap=<list_of_typemap_entries>

This option permits you to append an entry or a comma-separated list of entries to the JPublisher user type map. An entry has one of the following formats:

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

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 maximum array length <max_length> and the maximum element size designation <elem_size> can be omitted in certain cases.

The difference between the -addtypemap option and the -typemap option is that -addtypemap appends entries to the user type map, while -typemap replaces the existing type map with the specified entries. See "Replacement of the JPublisher Type Map (-typemap)".

For more information about the first -addtypemap format above, see "Type Mapping Support for OPAQUE Types". The second and third formats are discussed in "Type Mapping Support for Scalar Indexed-by Tables Using JDBC OCI". The last format is explained in "Type Mapping Support Through PL/SQL Conversion Functions".

Case of Java Identifiers (-case)

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

For class or attribute names 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, arguments of generated method names, and Java wrapper names.

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

Table 3-6 Values for the -case Option  

For class or attribute names that you enter with the -sql option, or class names in the INPUT file, JPublisher retains the case of the letters in the specified name, overriding the -case option.

JPublisher will retain, as written, the case of the Java class identifier for an object type specified on the command line or in the INPUT file. For example, if the command line includes the following:

-sql=Worker

then JPublisher generates:

public class Worker ... ;

If the entry in the INPUT file is written as:

SQL wOrKeR

then JPublisher will follow the case for the identifier as it was entered in the INPUT file and generate:

public class wOrKeR ... ;

SQLJ Connection Context Classes (-context)

-context={generated|DefaultContext|user-specified}

The -context option controls the connection context class that JPublisher may use, and possibly declare, for .sqlj wrappers for user-defined object types and PL/SQL packages.

The setting -context=DefaultContext is the default and results in any JPublisher-generated .sqlj source files using the SQLJ default connection context class--sqlj.runtime.ref.DefaultContext--for all connection contexts.

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

The setting -context=generated results in the following inner class declaration in all .sqlj files generated by JPublisher.

#sql static context _Ctx;

This means that each PL/SQL package and each object type wrapper uses its own SQLJ connection context class. (Also see "Use of Connection Contexts and Instances in SQLJ Code Generated by JPublisher".)

Note the following benefits in using the DefaultContext setting or user-specified-class setting:

• No additional context classes are generated.
• You have greater flexibility if you translate and compile your .sqlj files in separate steps (translating with the SQLJ -compile=false setting). Assuming you are not using JDK 1.2-specific types (such as java.sql.BLOB, CLOB, Struct, Ref, or Array), the resulting .java files can be compiled under either JDK 1.1.x or under JDK 1.2.x or higher. This is not the case with the setting -context=generated, because SQLJ connection contexts in JDK 1.1.x use java.util.Dictionary instances for object type maps, while SQLJ connection contexts in JDK 1.2 or higher use java.util.Map instances.

A benefit of using the generated setting, however, is that it permits full control over the way the SQLJ translator performs online checking. Specifically, every object type and every PL/SQL package can be checked against its own 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.

Note that using the user-specified-class setting gives you the flexibility of the generated setting while still giving you the advantages of the DefaultContext setting.

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

See the Oracle9i SQLJ Developer's Guide and Reference for general information about SQLJ connection contexts.

Default Type Map for JPublisher (-defaulttypemap)

-defaulttypemap=[<list_of_typemap_entries>]

This option is used internally by JPublisher to set up predefined type map entries. This is separate from the user type map entries specified with -addtypemap or -typemap. If you want to clear the default type map, you can use the following option setting:

-defaulttypemap=

Output Directory for Generated Files (-dir)

-dir=<directory name>

A non-empty -dir option setting specifies the root of the directory tree within which JPublisher will place Java and SQLJ source files. JPublisher will nest generated packages in this directory. A setting of "." (a period, or "dot") specifies the current directory as the root of the directory tree.

The empty setting, however, installs all generated file directly into the current directory--there is no hierarchy in this case. This is the default setting, but you can also specify it explicitly as follows:

-dir=

If you specify a non-empty setting, JPublisher combines the directory, the package name given with the -package option, and any package name included in a SQL statement in the INPUT file to determine the specific directory within which it will generate a .java or .sqlj file. The "Name for Generated Packages (-package)" section discusses this in more detail.

For example, consider the following command line (which is a single wraparound line):

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

In this case, the demo directory will be the base directory for packages JPublisher generates for object types you specify in the INPUT file demoin.

You can specify -dir on the command line or in a properties file. The default value for the -dir option is empty.

JDBC Driver Class for Database Connection (-driver)

-driver=<driver_class_name>

The -driver option specifies the driver class that JPublisher uses for JDBC connections to the database. The default is:

-driver=oracle.jdbc.OracleDriver

This setting is appropriate for any Oracle JDBC driver.

Java Character Encoding (-encoding)

-encoding=<name_of_character_encoding>

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

As a general rule, you are not required to specify this option unless you specify an -encoding option when you invoke SQLJ and your Java compiler, in which case you should use the same -encoding option for JPublisher.

You can use the -encoding option to specify any character encoding that is 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 URLs:

http://www.javasoft.com/products/jdk/1.2/docs/tooldocs/solaris/native2ascii.html

or:

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

Generation of User Subclasses (-gensubclass)

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

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.

For -gensubclass=true (the default), JPublisher will generate code for the subclass only if it finds that no source file (.java or .sqlj) is present for the user subclass.

The -gensubclass=false setting results in JPublisher not generating any code for user subclasses.

For -gensubclass=force, JPublisher will always generate code for user subclasses. It will overwrite any existing code in the corresponding .java or .sqlj file if it already exists. Use this setting with caution.

The setting -gensubclass=call-super is equivalent to -gensubclass=true, except that JPublisher will generate slightly different code. By default, JPublisher generates only constructors and methods necessary for implementing, 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 methods, getters, and setters are generated as code. The idea is that you can specify this setting if you are using Java development tools that are based on class introspection. Generally only those methods that relate to SQL object attributes and SQL object methods are interesting, while JPublisher implementation details should 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.

File Containing Names of Objects and Packages to Translate (-input)

-input=<filename>
-i <filename>

Both formats are synonymous. The second one is provided for convenience as a command-line abbreviation.

The -input option specifies the name of a file from which JPublisher reads the names of object types and PL/SQL packages to translate, and other information it needs for their translation. JPublisher translates each object type and package in the list. You can think of the INPUT file as a makefile for type declarations--it lists the types that need Java class definitions.

In some cases, JPublisher might 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. For more information on this topic, see "Translating Additional Types".

If you do not specify any packages or object types in an INPUT file or on the command line, then JPublisher translates all object types and packages declared in the database schema to which it is connected.

For more information about the syntax of the INPUT file, see "INPUT File Structure and Syntax".

Generation of Package Classes and Wrapper Methods (-methods)

-methods={true|all|always|named|some|false|none}

The value of the -methods option determines whether JPublisher generates wrapper methods for methods in object types and PL/SQL packages.

For -methods=true or, equivalently, -methods=all (the default), JPublisher generates wrapper methods for all the methods in the object types and PL/SQL packages it processes. In Oracle9i, this results in generation of a .sqlj source file whenever the underlying SQL object or package actually defines methods, but a .java source if not. (In previous releases, .sqlj source files were always generated for a true or all setting.)

The -methods=always setting also results in wrapper methods being generated; however, for backward compatibility to earlier JPublisher versions, this setting always results in .sqlj files being generated for all SQL object types, regardless of whether the types define methods.

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

For -methods=false or, equivalently, -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.

The default is -methods=all.

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

Omission of Schema Name from Generated Names (-omit_schema_names)

-omit_schema_names

Specifying -omit_schema_names determines that certain object type names generated by JPublisher include the schema name. 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 was invoked, as long as the object types and packages you use are declared identically in the two schemas.

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

If you specify -omit_schema_names, every object type or wrapper name generated by JPublisher is qualified with a schema name.

If you do not specify -omit_schema_names, an object type or wrapper name generated by JPublisher is qualified with a schema name only under the following circumstances:

• You declare the object type or wrapper in a schema other than the one to which JPublisher is connected.

or:

• You declare the object type or wrapper with a schema name on the command line or INPUT file.

That is, an object type or wrapper from another schema requires a schema name to identify it, and the use of a schema name with the type or package on the command line or INPUT file overrides the -omit_schema_names option.

Name for Generated Packages (-package)

-package=<package_name>

The -package option specifies the name of the package JPublisher generates. The name of the package appears in a package declaration in each .java or .sqlj file. The directory structure also reflects the package name. An explicit name in the INPUT file, after the -sql option, overrides the value given to the -package option.

Example 1

If the command line includes the following:

-dir=/a/b -package=c.d -case=mixed 

and the INPUT file contains the following line (and assuming the SQL type PERSON has methods defined on it):

SQL PERSON AS Person 

then in the following cases, JPublisher creates the file /a/b/c/d/Person.sqlj:

-sql=PERSON:Person
-sql=PERSON
SQL PERSON AS Person
SQL PERSON

The Person.sqlj file contains (among other things) the following package declaration:

package c.d;

Example 2

Now assume the following is again in the command line:

-dir=/a/b -package=c.d -case=mixed

but is followed by specification of an INPUT file containing the following:

-sql=PERSON:e.f.Person
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 creates the file a/b/e/f/Person.sqlj, which includes the following package declaration:

package e.f;

If you do not supply a package name for a class by any of the means described in this section, then JPublisher will not supply a name for the package containing the class. In addition, JPublisher will not generate a package declaration, and it will put the file containing the declaration of the class in the directory specified by the -dir option.

Occasionally, JPublisher might need to translate a type not explicitly listed in the INPUT file, because the type is used by another type that must be translated. In this case, the file declaring the required type is placed in the default package named on the command line, in a properties file, or in the INPUT file. JPublisher does not translate non-specified packages, because packages do not have dependencies on other packages.

File for Generated PL/SQL Wrapper Code (-plsqlfile)

-plsqlfile=<name_of_file_for_generated_PLSQL_code>

The -plsqlfile option specifies the name of the file into which JPublisher writes PL/SQL wrapper stored procedures and functions. If this file already exists, it will be silently overwritten. By default, JPublisher writes PL/SQL code to the file plsql_wrapper.sql.

Also note that it is your responsibility to load the generated file into the database (using SQL*Plus, for example).

Generation of PL/SQL Wrapper Code (-plsqlmap)

-plsqlmap={true|false|always}

The -plsqlmap option specifies how JPublisher generates PL/SQL wrapper procedures and functions.

If this option is set to true (the default), JPublisher will generate PL/SQL wrapper procedures and functions as needed and, whenever possible, use conversion functions only.

If this option is set to false, JPublisher will not generate PL/SQL wrapper procedures or functions. If it encounters in a signature a PL/SQL type that cannot be supported by conversion functions alone (in other words, that would require generation of a PL/SQL wrapper), then JPublisher will skip generation of Java code for this particular procedure or function.

The setting always specifies that JPublisher will generate a PL/SQL wrapper procedure or function for every stored procedure or function that uses a PL/SQL type. This is useful for generating a "proxy" PL/SQL package that complements an original PL/SQL package. The proxy provides Java-accessible signatures for those functions or procedures that are not directly accessible from JDBC or SQLJ in the original package.

Package for Generated PL/SQL Wrapper Code (-plsqlpackage)

-plsqlpackage=<name_of_PLSQL_package_to_hold_generated_PLSQL_code>

The -plsqlpackage option specifies the name of a PL/SQL package into which JPublisher places any generated PL/SQL wrapper stored procedures and functions. By default, JPublisher uses the package JPUB_PLSQL_WRAPPER.

Note that it is your responsibility to create this package in the database by running the SQL script generated by JPublisher. See "File for Generated PL/SQL Wrapper Code (-plsqlfile)".

Input Properties File (-props)

-props=<filename>
-p <filename>

Both formats are synonymous. The second one is provided for convenience as a command-line abbreviation.

The -props option, entered on the command line, specifies the name of a JPublisher properties file that lists the values of commonly used options. JPublisher processes the properties file as if its contents were inserted in sequence on the command line at that point.

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

For information on the contents of the properties file, see "Properties File Structure and Syntax".

Serializability of Generated Object Wrappers (-serializable)

-serializable={true|false}

The boolean option -serializable specifies whether the Java classes that JPublisher generates for SQL object types implement the java.io.Serializable interface. The default setting is -serializable=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 will be 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 severed, 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:

  public void restoreConnection(Connection)
  
  

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

Declaration of Object Types and Packages to Translate (-sql)

-sql={toplevel|object type and package translation syntax}
-s {toplevel|object type and package translation syntax}

The two formats are synonymous. The second one is provided for convenience as a 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.) Currently, JPublisher supports translation of object types and packages. JPublisher also translates the top-level subprograms in a schema, just as it does for subprograms in a PL/SQL package.

You can mix object types 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. More information on the toplevel keyword is provided later in this section.

If you do not enter any types or packages to translate in the INPUT file or on the command line, then JPublisher will translate all the types and packages in the schema to which you are connected.

In this section, the -sql option is explained by translating it to the equivalent INPUT file syntax. INPUT file syntax is explained in "Understanding the Translation Statement".

The JPublisher command-line syntax for -sql lets you indicate three possible type translations.

• -sql=name_a

  JPublisher interprets this syntax as: SQL name_a

• -sql=name_a:name_c

  JPublisher interprets this syntax as: SQL name_a AS name_c

• -sql=name_a:name_b:name_c

  JPublisher interprets this syntax as:
  SQL name_a GENERATE name_b AS name_c

  In this case, name_a must represent an object type.

  Important: Only non-case-sensitive SQL names are supported on the JPublisher command line. If a user-defined type was defined in a case-sensitive way (in quotes) in SQL, then you must specify the name in the JPublisher INPUT file instead of on the command line, and in quotes. See "INPUT File Structure and Syntax" for information.

  Note: The name_a:name_b:name_c translation syntax is not meaningful when name_a represents a package.

Enter -sql=... followed by one or more object types and packages (including top-level "packages") that you want JPublisher to translate. If you enter more than one item for translation, they must be separated by commas, without any white space. This example assumes that CORPORATION is a package, and EMPLOYEE and ADDRESS are object types:

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

JPublisher will interpret this as follows:

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

And JPublisher executes the following:

• It creates a wrapper for the CORPORATION package.
• It translates the object type EMPLOYEE as oracleEmployee.
• It translates ADDRESS as JAddress, generating code so that ADDRESS objects will be represented by the MyAddress class that you will write to extend JAddress.
• It creates the references to the MyAddress class that you will write to extend JAddress.

If you want JPublisher to translate all the top-level PL/SQL subprograms in the schema to which JPublisher is connected, 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, known as toplevel, for the top level subprograms. If you want the class to be generated with a different name, you can declare the name with the -sql=name_a:name_b syntax. For example:

-sql=toplevel:myClass 

Note that this is synonymous with the 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, enter:

-sql=<schema_name>.toplevel

In this example, <schema_name> is the name of the schema containing the top-level subprograms.

When you request generation of top-level subprograms, you can also supply a list of names, in which case JPublisher will only generate code for those top-level functions or procedures mentioned in the list. The list of names must follow the TOPLEVEL token and be enclosed in (...), and the function names must be separated with "+" (the plus character). Consider the following example:

-sql=toplevel(BOOL2INT+INT2BOOL):Conversions

Function and procedure names specified in the list are sensitive to case. You must specify them in uppercase if they were defined in a case-insensitive way. Also note that if you want to use this option, your operating system shell may require that this option be quoted in the JPublisher command line.

Generation of toString() Method on Object Wrappers (-tostring)

-tostring={true|false}

You can use the boolean option -tostring 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.

Replacement of the JPublisher Type Map (-typemap)

-typemap=[<list_of_typemap_entries>]

The difference between the -addtypemap option and the -typemap option is that -addtypemap appends entries to the user type map, while -typemap replaces the existing type map with the specified entries. Thus, if you want to clear the user type map, you can use the following option setting.

-typemap=

Note that this does not clear the content of the default type map, which is controlled independently from the user type map with the -defaulttypemap and -adddefaulttypemap options. The format of the type map entries is described in "Additional Entry to the User Type Map (-addtypemap)".

Declaration of Object Types to Translate (-types)

-types=<type_translation_syntax>

You can use the -types option, for object types only, when you do not need the generality of an INPUT file. The -types option lets you list one or more individual object types that you want JPublisher to translate. 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 with the -types or -sql options, then JPublisher will translate 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 syntax has the same functionality as SQL, SQL...AS and SQL...GENERATE...AS syntax. See "Understanding the Translation Statement".

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

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

JPublisher will interpret this as:

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

Connection URL for Target Database (-url)

-url=<url>

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

-url=jdbc:oracle:oci:@

You can follow the "@" symbol with an Oracle SID.

To specify the Thin driver, enter:

-url=jdbc:oracle:thin:@host:port:sid

In this example, host is the name of the host on which the database is running, port is the port number, and sid is the Oracle SID.

User Name and Password for Database Connection (-user)

-user=<username/password>
-u <username/password>

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

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, JPublisher prints an error message and stops execution.

For example, the following command line directs JPublisher to connect to your database with username scott and password tiger:

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

JPublisher Input Files

These sections describe the structure and contents of JPublisher input files:

• Properties File Structure and Syntax
• INPUT File Structure and Syntax
• INPUT File Precautions

Properties File Structure and Syntax

A properties file is an optional text file where you can specify frequently used options. Specify the name of the properties file on the JPublisher command line with the -props option. (And -props is the only option that you cannot specify in a properties file.)

In a properties file, enter one option with its associated value on each line. Enter each option name with the following prefix (including the period), case-sensitive:

jpub.

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 using the following prefix, which resembles the syntax of SQL line comments.

-- jpub.

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

Additionally, you can use line continuation to spread a JPublisher option over several lines in the properties file. A line that is to be continued must have "\" (backslash character) as the last character, immediately after the text of the line. Any leading space, or any leading "--" (SQL comment designation), on the following line 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

Because of this functionality, it is straightforward to embed JPublisher options in SQL scripts. This can 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 specified. If you specify an option more than once, the last value encountered by JPublisher will override previous values, except for the following options, which are cumulative:

• jpub.sql
• jpub.type
• jpub.addtypemap
• jpub.adddefaulttypemap

For example, consider the following command line (a single wraparound line):

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

This is equivalent to the following:

jpub -props=my_properties

if you assume my_properties has a definition like 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 (including the period) at the beginning of each option name. If you enter anything else except white space or "--" before the option name, JPublisher will ignore the entire line.

This example also illustrates that the "jpub." prefix must be all lowercase, otherwise it is ignored, as for "Jpub.notreally=a jpub option".

"JPublisher Options" describes all the JPublisher options.

INPUT File Structure and Syntax

Specify the name of the INPUT file on the JPublisher command line with the -input option. This file identifies the object types and PL/SQL packages 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 object types and packages, an INPUT file allows you a finer degree of control over how JPublisher translates object types and PL/SQL packages.

If you do not specify types or packages to translate in an INPUT file or on the command line, then JPublisher translates all object 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 object 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:

( 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> Clause

Enter SQL <name> to identify an object type or a PL/SQL package that you want JPublisher to translate. JPublisher examines the <name>, determines whether it is an object type or a package name, 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, TYPE syntax is deprecated in Oracle9i.

You can enter <name> as <schema_name>.<name> to specify the schema to which the object 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>), a comma-separated list of names, enclosed in parentheses, that are to be published. JPublisher will consider only top-level functions and procedures that match this list. If you do not specify this list, JPublisher will generate code for all top-level subprograms.

SQL "CaseSenstiveType" AS CaseSensitiveType

SQL SCOTT."CaseSensitiveType" AS CaseSensitiveType

SQL "Scott"."CaseSensitiveType AS CaseSensitiveType

AS <java_name_2> Clause

This clause optionally specifies the name of the Java class that represents the user-defined type or PL/SQL package. The <java_name_2> can be any legal Java name and can include a package identifier. The case of the Java name overrides the value of the -case option. For more information on how to name packages, see "Package Naming Rules in the INPUT File".

When you use the AS clause without a GENERATE clause, the class in the AS clause is what JPublisher generates and is mapped to the SQL type.

When you use the AS clause with a GENERATE clause, JPublisher generates the class in the GENERATE clause but maps the SQL type to the class in the AS clause. You manually create the class in the AS clause, extending the class that JPublisher generates.

Also see "Extending JPublisher-Generated Classes".

GENERATE <java_name_1> Clause

This clause specifies the name of the class that JPublisher generates when you want to create a subclass for mapping purposes. Use the GENERATE clause in conjunction with the AS clause. JPublisher generates the class in the GENERATE clause. The AS clause specifies the name of the subclass that you create and that your Java program will use to represent the SQL object type.

The <java_name_1> can be any legal Java name and can include a package identifier. Its case overrides the value of the -case option.

Use the GENERATE clause only when you are translating object types. When you are translating an object type, the code JPublisher generates mentions both the name of the class that JPublisher generates and the name of the class that your Java program will use to represent the SQL object type. When these are two different classes, use GENERATE...AS.

Do not use this clause if you are translating PL/SQL packages. When you are translating a PL/SQL package, the code JPublisher generates mentions only the name of the class that JPublisher generates, so there is no need to use the GENERATE clause in this case.

Also see "Extending JPublisher-Generated Classes".

TRANSLATE <database_member_name> AS <simple_java_name> Clause

This clause optionally specifies a different name for an attribute or method. The <database_member_name> is the name of an attribute of an object type, or a method of a type or package, which is to be translated to the following <simple_java_name>. The <simple_java_name> can be any legal Java name, and its case overrides the value of 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 as modified according to the value of the -case option. Reasons why you might want to rename an attribute name 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 might want to capitalize the first letter of your attribute names. For example, if you enter:

TRANSLATE FIRSTNAME AS FirstName

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

TRANSLATE FIRSTNAME AS firstName

JPublisher will generate a getfirstName() method and a setfirstName() method.

TRANSLATE FIRSTNAME AS null

Package Naming Rules in the INPUT File

If you use a simple Java identifier to name a class in the INPUT file, its full class name will include the package name from the -package option. If the class name in the INPUT file is qualified with a package name, then that package name overrides the value of the -package option and becomes the full package name of the class.

Note the following:

• If you enter the syntax:

  SQL A AS B 
  
  

  then JPublisher uses the value that was entered for -package on the command line or the properties file.

• If you enter the syntax:

  SQL A AS B.C
  
  

  then JPublisher interprets B.C to represent the full class name.

For example, if you enter the following on the command line:

-package=a.b 

and the INPUT file contains the following translation statement:

SQL scott.employee AS e.Employee 

then JPublisher will generate the class as follows:

e.Employee

For more examples of how the package name is determined, see "Name for Generated Packages (-package)".

Translating Additional Types

It might be necessary for JPublisher to translate additional types 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 other types as necessary. Recall the example in "Sample JPublisher Translation". Assume the object type definition for EMPLOYEE had included an attribute called ADDRESS, and ADDRESS was 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 packages you do not request. Because packages do not have attributes, they do not have any dependencies on other packages.

Sample Translation Statement

To better illustrate the function of the INPUT file, consider a more complicated version of the example in "Sample JPublisher Translation". Consider the following command line (a single wraparound line):

jpub -user=scott/tiger -input=demoin -dir=demo -numbertypes=oracle -package=corp 
-case=same

And assume the INPUT file demoin contains the following:

SQL employee AS c.Employee
  TRANSLATE NAME AS Name
            HIRE_DATE AS HireDate 

The -case=same option indicates that generated Java identifiers should maintain the same case as in the database. Any identifier in a CREATE TYPE or CREATE PACKAGE declaration is stored in upper case in the database unless it is quoted. However, the -case option is applied only to those identifiers not explicitly mentioned in the INPUT file. Therefore, Employee will appear as written. The attribute identifiers not specifically mentioned (that is, EMPNO, DEPTNO, and SALARY) will remain in upper case, but JPublisher will translate the specifically mentioned NAME and HIRE_DATE attribute identifiers as shown.

The translation statement specifies a SQL object type to be translated. In this case, there is only one object type, Employee.

The AS c.Employee clause causes the package name to be further qualified. The translated type will be written to the following file:

./demo/corp/c/Employee.sqlj           (UNIX)
.\demo\corp\c\Employee.sqlj           (Windows NT)

(This assumes the object type defines methods; otherwise Employee.java will be generated instead.)

The generated file is written in package corp.c in output directory demo. Note that the package name is reflected in the directory structure.

The TRANSLATE...AS clause specifies that the name of any mentioned object attributes should be changed when the type is translated into a Java class. In this case, the NAME attribute is changed to Name and the HIRE_DATE attribute is changed to HireDate.

INPUT File Precautions

This section describes some of the common errors made in INPUT files. Check for these errors before you run JPublisher. Although JPublisher reports most of the errors that it finds in the INPUT file, it does not report these.

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 will silently overwrite the first. For example, if the INPUT file contains:

type PERSON1 as Person
TYPE PERSON2 as Person

JPublisher will create the file Person.java for PERSON1 and will then overwrite it for type PERSON2.

Requesting the Same Attribute Name for Different Object Attributes

If you request the same attribute name for two different object attributes, JPublisher will generate 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, JPublisher will ignore it without issuing a warning message.

Consider the following example from an INPUT file:

type PERSON translate X as attr1

A situation where X is not an attribute of PERSON would not cause JPublisher to issue a warning message.