2
Command-Line Options and Input Files

This chapter describes the use of JPublisher option settings and input files to specify program behavior. The following topics are covered:

• JPublisher Options

• JPublisher Input Files

JPublisher Options

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

• JPublisher Option Summary

• JPublisher Option Tips

• Notational Conventions

• Detailed Descriptions--Options That Affect Datatype Mappings

• Detailed Descriptions--General JPublisher Options

JPublisher Option Summary

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

Table 2-1 Summary of JPublisher Options  

JPublisher Option Tips

Be aware of the following usage notes for JPublisher options:

• JPublisher always requires the -user option, either on the command line or in the properties file.

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

• If a particular option appears more than once, JPublisher uses the value from the last occurrence.

• It is advisable to specify a Java package for your generated classes, either on the command line, with the -package option, or in the 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's 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.

• A vertical bar | separates alternatives within brackets.

• Terms in italics are like variables--specify an actual value or string.

• Square brackets [...] enclose optional items.

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

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

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 backwards 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. This is possibly used in conjunction with the -compatible option, described in "Backwards-Compatible Oracle Mapping for User-Defined Types (-compatible)" below.

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.

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

-compatible={oradata|customdatum|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 backwards compatibility. If -usertypes=jdbc, a -compatible setting of customdatum (or oradata) is ignored.

Alternatively, this option has another mode of operation. With a setting of -compatible=8i, you can specify the general Oracle8i compatibility mode. This not only uses the CustomDatum interface, but also generates the same code that would be generated by Oracle8i JPublisher, and is equivalent to setting other JPublisher options for backwards 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. 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 2-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 2-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 2-3 shows how these types are mapped for -lobtypes=oracle (the default) and for -lobtypes=jdbc.

Table 2-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 2-4 lists the datatypes affected by the -builtintypes option and shows their Java type mappings for -builtintypes=oracle and -builtintypes=jdbc (the default).

Table 2-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 2-5.

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

Detailed Descriptions--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 modifiers that JPublisher includes in generated attribute setter and getter methods and member methods on object type wrapper classes, as well as for wrapper methods on PL/SQL packages.

JPublisher uses the possible option settings as follows:

• public (default)--Results in methods being generated with the public access modifier.

• protected--Results in methods being generated with the protected access modifier.

• package--Results in the access modifier being 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.

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 2-6 describes the possible values for the -case option.

Table 2-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 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 ... ;

Or, 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".)

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

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, in the following command line (which is a single wrap-around line):

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

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_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 URL:

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

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

-input=<filename>

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

Generate Classes for Packages and Wrapper Methods for 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. As of Oracle9i release 9.0.1, 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 backwards 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.

Omit Schema Name from Generated Names (-omit_schema_names)

-omit_schema_names

The presence of the -omit_schema_names option determines whether 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 do not specify -omit_schema_names on the command line, every object type or wrapper name generated by JPublisher is qualified with a schema name.

If you do specify -omit_schema_names on the command line, an object type or wrapper name generated by JPublisher is qualified with a schema name only if:

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

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.

Input Properties File (-props)

-props=<filename>

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

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

-sql=<object type and package translation syntax>

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

You enter -sql=... only once on the command line or properties file, 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

where <schema-name> is the name of the schema containing the top-level subprograms.

Declare 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_b AS name_c

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

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

JPublisher requires the -user option, which specifies an Oracle user name and password. 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. You specify the name of the properties file on the JPublisher command line with the -props option. JPublisher processes the properties file as if its contents were inserted on the command line at that point.

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

jpub.

You cannot use any white space within a line. You can enter any option except the -props option in the properties file.

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 was specified. If you specify an option more than once, JPublisher uses the last value encountered.

For example, consider the following command line (a single wrap-around 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

where my_properties is as follows:

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

"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. The translation statement can also optionally 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 | 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>.

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

For example:

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

-package=a.b 

on the command line and the INPUT file contains the translation statement:

SQL scott.employee AS e.Employee 

then JPublisher will generate the class as:

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 wrap-around line):

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

The INPUT file demoin now contains:

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

For example, if the INPUT file contains: type PERSON translate X as attr1

and X is not an attribute of PERSON, JPublisher will not issue a warning message.