Oracle8i JPublisher User's Guide Release 2 (8.1.6) Part Number A81357-01 |
Library | Service | Contents | Index

## Using JPublisher

This section has the following subsections:

- Creating Types and Packages in the Database

- Overview of JPublisher Input and Output

- JPublisher Command Line Syntax

- JPublisher Options

Before you run JPublisher, you must create any new database types that you will require. You must also ensure that any PL/SQL packages, methods, and subprograms that you want to invoke from Java are also installed in the database. Once you have done that, you can invoke JPublisher from the command line.

### Creating Types and Packages in the Database

Use the SQL `CREATE` `TYPE` statement to create object, `varray`, and nested table types in the database. JPublisher supports the mapping of these datatypes to Java classes. JPublisher also generates classes for `REF`s to object types. `REF` types are not explicitly declared in SQL. For more information on creating object types, see the Oracle8i SQL Reference.

Use the `CREATE` `PACKAGE` and `CREATE` `PACKAGE` `BODY` statements to create PL/SQL packages and store them in the database. PL/SQL furnishes all the capabilities necessary to implement the methods associated with object types. These methods (functions and procedures) reside on the server as part of a user's schema. You can implement the methods in PL/SQL or Java.

Packages are often implemented to provide advantages in these areas:

- encapsulation of related procedures and variables

- declaration of public and private procedures, variables, constants, and cursors

- better performance

For more information on PL/SQL and creating PL/SQL packages, see the PL/SQL User's Guide and Reference.

### Overview of JPublisher Input and Output

You can specify input options on the command line and in the properties file. In addition to producing `.java` files for the translated objects, JPublisher writes the names of the translated objects and packages to ``standard output.

#### JPublisher Input

You can specify JPublisher options on the command line or in a properties file. "JPublisher Options" describes all the JPublisher options.

In addition, you can use a file known as the `INPUT` file to specify the object types and PL/SQL packages JPublisher should translate. It also controls the naming of the generated packages and classes. "INPUT File Structure and Syntax" describes INPUT file syntax.

A properties file is an optional text file that you can use to specify frequently-used options. You name the properties file on the command line. JPublisher processes the properties file as if its contents were inserted, in sequence, on the command line at that point. For more information about this file, see "Properties File Structure and Syntax".

#### JPublisher Output

JPublisher generates a Java class for each object type that it translates. For each object type, JPublisher generates a <type>`.sqlj` file (or a <type>`.java` file if wrapper methods were suppressed) for the class code and a <type>`Ref.java` file for the code for the `REF` class of the Java type. For example, if you define an `employee` SQL object type, JPublisher generates an `employee.sqlj` file and an `employeeRef.java` file.

For each collection type (nested table or `varray`) it translates, JPublisher generates a <type>`.java` file. For nested tables, the generated class has methods to `get` and `set` the nested table as an entire array and to `get` and `set` individual elements of the table. JPublisher translates collection types when generating `CustomDatum` classes, but not when generating `SQLData` classes.

For PL/SQL packages, JPublisher generates classes containing wrapper methods as `.sqlj` files.

When JPublisher generates the class files and wrappers, it also writes the names of the translated types and packages to ``standard output.

### JPublisher Command Line Syntax

The JPublisher command-line syntax consists of the keyword `jpub`, followed by a list of JPublisher options. Consult your platform-specific documentation for instructions on how to invoke JPublisher on your platform.

Enter options on the JPublisher command line using this format:

-option=value

Your option entry is the literal option string and your value entry is a valid option setting. The literal option string is in lower case, and the value entry is case-sensitive. Separate command-line options with either spaces or tabs.

If you execute JPublisher without any options on the command line, it displays an option reference list and then terminates.

The following is an example of a JPublisher command line statement (enter it as one line, allowing it to wrap, as necessary):

    jpub -user=scott/tiger -input=demoin -numbertypes=jdbc -case=lower -package=corp
    -dir=demo

Notes: No spaces are permitted around the equals sign (=).

The next section, "JPublisher Options", describes all the JPublisher options.

### JPublisher Options

Table 1-1 lists the options that you can use on the JPublisher command line, their syntax, and a brief description. Following the table, you can find a detailed description of each option. The abbreviation "n/a" represents "not applicable".

##### Table 1-1 JPublisher Option Quick Guide

Option Name | Description | Default Value
--- | --- | ---
`-builtintypes` | Specifies the type mappings (`jdbc` or `oracle`) for non-numeric, non-LOB built-in database types. | `jdbc`
`-case` | Specifies the case of Java identifiers that JPublisher generates. | `mixed`
`-dir` | Specifies the directory that holds generated packages. | current directory
`-driver` | Specifies the JDBC driver JPublisher uses to connect to the database. | `oracle.jdbc.driver.OracleDriver`
`-encoding` | Specifies the Java encoding of JPublisher's input files and output files. | the value of the System property `file.encoding`
`-input` | Specifies the file that lists the types and packages JPublisher translates. | n/a
`-lobtypes` | Specifies the type mappings (`jdbc` or `oracle`) that JPublisher uses for BLOB and CLOB types. | `oracle`
`-mapping` | Specifies which object attribute type and method argument type mapping the generated methods support. | `objectjdbc`
`-methods` | Determines whether JPublisher generates classes for PL/SQL packages and wrapper methods for methods in packages and object types, and whether JPublisher generates all methods or just the ones the user specifies. | `all`
`-numbertypes` | Specifies the type mappings (`jdbc`, `objectjdbc`, `bigdecimal`, or `oracle`) JPublisher uses for numeric database types. | `objectjdbc`
`-omit_schema_names` | Specifies whether all object type and package names JPublisher generates include the schema name. | do not omit schema names
`-package` | Specifies the name of the Java package for which JPublisher is generating a Java wrapper. | n/a
`-props` | Specifies a file that contains JPublisher options in addition to those listed on the command line. | n/a
`-sql` | Specifies object types and packages for which JPublisher will generate code. | n/a
`-types` | Specifies object types for which JPublisher will generate code. Note: The `-types` option is currently supported for compatibility, but deprecated in favor of `-sql`. | n/a
`-url` | Specifies the URL JPublisher uses to connect to the database. | `jdbc:oracle:oci8:@`
`-user` | Specifies an Oracle username and password. | n/a
`-usertypes` | Specifies the types mappings (`jdbc` or `oracle`) JPublisher uses for used-defined database types. | `oracle`

#### JPublisher Option Tips

- 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 occur. Options from an INPUT file are processed at the point where the `-input` option occurs.

- If a particular option appears more than once, JPublisher uses the option's value from its last occurrence.

- We recommend that you 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 -types=Person -package=e.f ...

  or in the properties file you could enter:

      jpub.types=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.

- On the command line, if you do not specify a type or package in the `INPUT` file ``or with the `-sql` or `-types` option, then JPublisher translates all types and packages in the user's schema according to the options you specify 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.

- You enter terms in UPPERCASE as shown, except that case is not significant.

- Terms in italics are like variables: you must specify an actual value or string.

- Square brackets `[`...`]` enclose optional items.

- Braces `{`...`}` enclose a list of possible values; you 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 so on.

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

#### Options That Affect Type Mappings

The following options control which type mappings JPublisher uses to translate object types, collection types, REF types, and PL/SQL packages to Java classes:

- The `-builtintypes` option controls type mappings for non-numeric, non-lob, predefined SQL and PL/SQL types.

- The `-lobtypes` option controls type mappings for the BLOB and CLOB types.

- The `-numbertypes` option controls type mappings for numeric types.

- The `-usertypes` option controls JPublisher's behavior for user-defined types.

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

For an object type, JPublisher applies the mappings specified by the type mapping options to the object's 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 `get` methods return and the `set` 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 generates CustomDatum classes or S`QLData` classes and whether JPublisher generates code for collection and REF types.

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

Next, we discuss the preceding four possibilities.

##### JDBC Mapping

The JDBC mapping maps most numeric database types to Java primitive types such as `int` and `float`, and maps DECIMAL and NUMBER to `java.math.BigDecimal`. Lob types and other non-numeric built-in types map to standard JDBC Java types such as `java.sql.Blob` and `java.sql.Timestamp`. For object types, JPublisher generates `SQLData` classes. Predefined data types that are Oracle extensions (such as `BFILE` and `ROWID`) do not have JDBC mappings, so only the `oracle.sql.*` mapping is supported for these types.

The Java primitive types used in the JDBC mapping do not support NULL values and do not guard against integer overflow or floating-point loss of precision. If you are using the JDBC mapping and you attempt to call an accessor or method to get an attribute of a primitive type (`short`, `int`, `float,` or `double`) whose database value is `NULL`, an exception is thrown. If the primitive type is `short` or `int`, then an exception is thrown if the value is too large to fit in a `short` or `int.`

##### Object JDBC Mapping

The Object JDBC mapping maps most numeric database types to Java wrapper classes such as `java.lang.Integer` and `java.lang.Float`, and maps DECIMAL and NUMBER to `java.math.BigDecimal`. It differs from the JDBC mapping only in that it does not use primitive types.

When you use the Object JDBC mapping, all your returned values are objects. If you attempt to get an attribute whose database value is NULL, a null object is returned.

The Java wrapper classes used in the Object JDBC mapping do not guard against integer overflow or floating-point loss of precision. If you call an accessor method to get an attribute that maps to `java.lang.Integer`, an exception is thrown if the value is too large to fit`.`

This is the default mapping for numeric types.

##### BigDecimal Mapping

The BigDecimal mapping, as the name implies, maps all numeric database types to `java.math.BigDecimal.` It supports NULL values and very large values.

##### Oracle Mapping

In the Oracle mapping, JPublisher maps any numeric, lob, or other built-in type to a class in the `oracle.sql` package. For example, the `DATE` type is mapped to `oracle.sql.DATE`, and all numeric types are mapped to o`racle.sql.NUMBER.` For object, collection, and REF types, JPublisher generates `CustomDatum` classes.

Because the Oracle mapping uses no primitive types, it can represent a database NULL value as a Java null in all cases. Because it uses the `oracle.sql.NUMBER` class for all numeric types, it can represent the largest numeric values that can be stored in the database.

##### More Information About Type Mappings

For an example of JPublisher output when `-mapping=objectjdbc` and when `-mapping=jdbc`, see "JPublisher Translation with the Oracle mapping" and "".

See "Understanding Datatype Mappings" for more information about these mappings and for specific Oracle, JDBC, and Object JDBC type mappings.

See "Understanding Datatype Mappings" for information about the factors you should consider when you decide which type mappings to use.

The next five sections discuss each of the type mapping options in detail.

##### Mappings For Built-In Types (-builtintypes)

`-builtintypes={jdbc|oracle}`

The `-builtintypes` option controls type mappings for all the built-in database types except the LOB and BLOB types (controlled by the `-lobtypes` option) and the different numeric types (controlled by the `-numbertypes` option). The following table lists the database types affected by the`-builtintypes` option, and shows their Java type mappings for `-builtintypes=oracle` and for `-builtintypes=jdbc` (the default).

#####

SQL or PL/SQL Datatype | Oracle Mapping Class | JDBC Mapping Class
--- | --- | ---
CHAR, CHARACTER, LONG, STRING, VARCHAR, VARCHAR2 | oracle.sql.CHAR | java.lang.String
RAW, LONG RAW | oracle.sql.RAW | byte[ ]
DATE | oracle.sql.DATE | java.sql.Timestamp

##### Mappings For LOB Types (-lobtypes)

`-lobtypes={jdbc|oracle}`

The `-lobtypes` option controls type mappings for the LOB and BLOB types. The following table shows how these types are mapped for `-lobtypes=oracle` (the default) and for `-lobtypes=jdbc`.

#####

SQL and PL/SQL Datatype | Oracle Mapping Class | Object JDBC Mapping Class
--- | --- | ---
CLOB | `oracle.sql.CLOB` | `java.sql.CLOB`
BLOB | `oracle.sql.BLOB` | `java.sql.BLOB`

The BFILE type does not appear in this table, because it has only one mapping. It is always mapped to `oracle.sql.BFILE`, because there is no `java.sql.BFILE` class.

The `java.sql.CLOB` and `java.sql.BLOB` classes are new in JDK 1.2. If you use JDK 1.1, you should not select `-lobtypes=jdbc`.

##### Mappings For Numeric Types (-numbertypes)

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

The `-numbertypes` option controls type mappings for numeric SQL and PL/SQL types. Four choices are available:

- The JDBC mapping maps most numeric database types 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 database types 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 database types to java.math.BigDecimal.

- The Oracle mapping maps all numeric database types to oracle.sql.NUMBER.

The following table 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).

#####

SQL and PL/SQL Datatype | JDBC Mapping Class | Object JDBC Mapping Class
--- | --- | ---
BINARY_INTEGER, INT, INTEGER, NATURAL, NATURALN, PLS_INTEGER, POSITIVE, POSITIVEN, SIGNTYPE | int | java.lang.Integer
SMALLINT | short | java.lang.Integer
REAL | float | java.lang.Float
DOUBLE PRECISION, FLOAT | double | java.lang.Double
DEC, DECIMAL, NUMBER, NUMERIC | java.math.BigDecimal | java.math.BigDecimal

##### Mappings for User-Defined Types (-usertypes)

`-usertypes={oracle|jdbc}`

The `-usertypes` option controls whether JPublisher generates `CustomDatum` classes or `SQLData` classes for user-defined types.

When `-usertypes=oracle` (the default), JPublisher generates `CustomDatum` classes for object, collection, and REF types.

When`-usertypes=jdbc`, JPublisher generates `SQLData` classes for object types. JPublisher does not generate anything for collection or REF types. Use `java.sql.Array` for all collection types, and `java.sql.Ref` for all REF types.

##### Type Mappings for All Types (-mapping)

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

You can use the `-mapping` option as an abbreviation for several common combinations of the type mapping options. This option is less flexible than setting the type mapping options individually and is supported mainly for compatibility with earlier versions of JPublisher.

`-mapping=oracle` is equivalent to setting all the type mapping options to `oracle` . The other mapping choices are equivalent to setting `-numbertypes` equal to the value of `-mapping` and setting the other type mapping options to their defaults, as shown in the following table:

#####

| -mapping=oracle | -mapping=jdbc | -mapping=objectjdbc | -mapping=bigdecimal
--- | --- | --- | --- | ---
-builtintypes= | oracle | jdbc | jdbc | jdbc
-numbertypes= | oracle | jdbc | objectjdbc | bigdecimal
-lobtypes= | oracle | oracle | oracle | oracle
-usertypes= | oracle | oracle | oracle | oracle

If you do not specify a value for the `-mapping` option on the command line, then JPublisher assumes that `-mapping=objectjdbc`.

Because options are processed in the order in which they occur, if the `-mapping` option precedes one of the type mapping options (`-builtintypes`, `-lobtypes`, `-numbertypes`, or `-usertypes`) the type mapping option overrides the `-mapping` option for the types the type mapping option affects. If the `-mapping` option follows one of the type mapping options, the type mapping option is ignored.

#### Other Options

Next, we discuss the remaining options in alphabetical order.

#### Case of Java Identifiers (-case)``

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

The `-case` option affects the case of certain Java identifiers that JPublisher generates, including class names, method names, attribute names embedded within `get` and `set` method names, arguments of generated method names, and Java wrapper names. For class or attribute names that you enter with the `-sql` or `-types` option, or class names in the INPUT file, JPublisher retains the case of the letters in the name, overriding the `-case` option.

Table 1-2 describes the possible values for the `-case` option.

##### Table 1-2 Values for the -case Option

-case Option Value | Description
--- | ---
`mixed` (default) | The first letter of every word of a class name or every word after the first word of a method name is in uppercase. All other characters are in lower case. An underscore (_), a dollar sign ($), and any character that is not a Java letter or digit constitutes a word boundary and is silently removed. A word boundary also occurs after `get` or `set` in a method name.
`same` | JPublisher does not change the case of letters from the way they are represented in the database. Underscores and dollar signs are retained. JPublisher removes any other character that is not a Java letter or digit and issues a warning message.
`upper` | JPublisher converts lowercase letters to uppercase and retains underscores and dollar signs. It removes any other character that is not a Java letter or digit and issues a warning message.
`lower` | JPublisher converts uppercase letters to lowercase and retains underscores and dollar signs. It removes any other character that is not a Java letter or digit and issues a warning message.

If you do not enter a value for `-case` on the command line, JPublisher assumes that `-case=mixed`.

The `-case` option affects only those identifiers (attributes or types) that the `INPUT` file or `-sql` option does not explicitly mention. JPublisher performs case conversion after it generates a legal identifier.

##### Case of Java Class Identifiers

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

#### Output Directory for Generated Files (-dir)

`-dir=`<directory name>

The `-dir` option 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.

JPublisher combines the directory specified by `-dir`, 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` file. The "Name for Generated Packages (-package)" section discusses this in more detail.

For example, in the following command line:

    jpub -user=scott/tiger -input=demoin -mapping=oracle -case=lower -types=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 the current directory.

#### JDBC Driver for Database Connection (-driver)

`-driver=`<driver_name>

The `-driver` option specifies the JDBC driver that JPublisher uses when it connects to the database. The default is:

    -driver=oracle.jdbc.driver.OracleDriver

This string, `oracle.jdbc.driver.OracleDriver`, 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, which represents ISO Latin-1.

As a general rule, you need not 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 by going to the URL http://www.javasoft.com and searching for "native-to-ascii".

#### 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 an `INPUT` file, or a package or object type with `-sql` or `-types` 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|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,` JPublisher generates wrapper methods for all the methods in the object types and PL/SQL packages it processes. 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 at all, 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.

`CustomDatum` and SQLData classes generated by JPublisher include a static final String that names the database 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` file. The directory structure also reflects the package name. An explicit name in the `INPUT` file, after the `-sql` or `-types` option, overrides the value given to the `-package` option.

##### Example

If `-dir=/a/b -package=c.d -case=mixed` appears on the command line, and the `INPUT` file contains the line:

    SQL PERSON AS Person

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

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

The `Person.java` file contains (among other things) the package declaration "`package c.d;`".

Given the same command line and `INPUT` file contents as above, JPublisher creates the file `a/b/e/f/Person.java` in the following cases:

    -sql=PERSON=e.f.Person;
    -types=PERSON:e.f.Person;
    SQL PERSON AS e.f.Person;
    TYPE PERSON AS e.f.Person;

The `Person.java` file contains (among other things) the package declaration "`package e.f;`".

If you do not supply a package name for a class by any of the methods 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 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.

Note: The `-props` option is not allowed in the properties file.

If you do not specify a properties file, then JPublisher will use the processing commands entered on the command line.

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

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

This section explains the -sql option syntax by translating it to the equivalent INPUT file syntax. "INPUT File Structure and Syntax" explains the INPUT file syntax.

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. For more information on the `toplevel` keyword, see "Translating Top Level PL/SQL Subprograms".

If you do not enter any types or packages to translate in the `INPUT` file or with the `-sql` or `-types` options, then JPublisher will translate all the types and packages in the schema to which you are connected.

In this section, we explain the `-sql` option 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.

    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:MyAddress:JAddress

JPublisher will interpret this as:

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

JPublisher

- creates a wrapper for the `CORPORATION` package

- translates the object type `Employee` as `oracleEmployee`

- translates `ADDRESS` as `JAddress`, generating code so that ADDRESS objects will be represented by the `MyAddress` class that you will write to extend `JAddress`

- and creates the references to the `MyAddress` class that you will write to extend `JAddress`.

##### Translating Top Level PL/SQL Subprograms

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

``

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

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.

  For more information on the `TYPE`, `TYPE`...`AS`, and `TYPE`...`GENERATE`...`AS` syntax, see "Understanding the Translation Statement".

You 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:MyAddress:JAddress

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:oci8:@

where you can follow the `@` symbol by the 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

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index