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

## Input Files

These sections describe the structure and contents of JPublisher's 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 prefix "`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 from left to right, 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 (right-most) value.

For example, the options in this command line:

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

can be represented on the command line as:

    jpub -props=my_properties

In this case, the contents of the properties file my_properties would be:

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

Note: You must include the "`jpub.`" prefix at the beginning of each option name. If you enter anything else before the option name, JPublisher will ignore the entire line.

"JPublisher Options" describes all the JPublisher options.

### INPUT File Structure and Syntax

You 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 an `INPUT` file or specify individual types or packages on the command line with the `-sql` (or `-types`) option, 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`, you can enter `TYPE` <type_name> if you are specifying only object types.

Note: The `TYPE` syntax is currently supported for compatibility, but deprecated. Please use the `SQL` syntax instead.

You can also 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>.

##### GENERATE <java_name_1>] Clause

This clause specifies the name of the class that JPublisher generates. You use the `GENERATE` clause in conjunction with the `AS` clause. The `AS` clause specifies the name of the class that your Java program will use to represent the database object type. When the `GENERATE` clause does not appear, JPublisher generates this class (the class in the `AS` clause). But when the `GENERATE` clause is used, the user writes the class in the `AS` clause, and JPublisher generates the class in the `GENERATE` clause.

You use the `GENERATE` clause when you want to extend the class generated by JPublisher and map the database object type to the subclass.

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. For more information on this clause see "Extending JPublisher Classes".

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

##### [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. It can include a package identifier. The Java name's case 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 in conjunction with the `GENERATE` clause, the java_name_2 is the name of the class that the user writes. For more information, see "GENERATE <java_name_1>] Clause" and "Extending JPublisher 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.

- The programmer prefers a different name.

Remember that your attribute names will appear embedded within `get` and `set` 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.

##### 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". If 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
    );

then 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, we take the example in "Sample JPublisher Translation" and make it more complex. For the command 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 an object type in the database 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 file:

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

This indicates that the Java source file `Employee.java` 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`.

#### Extending JPublisher Classes

You might want to enhance the functionality of a custom Java class generated by JPublisher by adding methods and transient fields to it. The preferred way to enhance the functionality of a generated class is to extend the class: that is, treat the JPublisher-generated class as a superclass, write a subclass to extend its functionality, and then map the object type to the subclass.

For example, suppose you want JPublisher to generate the class `JAddress` from the SQL object type `ADDRESS`. You also want to write a class `MyAddress` to represent `ADDRESS` objects, where `MyAddress` extends the functionality `JAddress` provides.

Under this scenario, you can use JPublisher to generate a custom Java class JAddress, and then write a subclass, MyAddress, which contains the added functionality. You then use JPublisher to map ADDRESS objects to the `MyAddress` class--not to the JAddress class. JPublisher will also produce a reference class for MyAddress, not JAddress.

To do this, JPublisher must alter the code it generates in the following ways:

- JPublisher will generate the `REF` class `MyAddressRef,` rather than `JAddressRef`.

- JPublisher will use the `MyAddress` class, instead of the `JAddress` class, to represent attributes whose database type is `ADDRESS`.

- JPublisher will use the `MyAddress` class, instead of the `JAddress` class, to represent `varray` and nested table elements whose database type is `ADDRESS`.

- JPublisher will use the `MyAddress` factory, instead of the `JAddress` factory, when the `CustomDatumFactory` interface is used to construct Java objects whose database type is `ADDRESS`.

JPublisher has functionality to streamline the process of mapping to alternative classes. Use the following syntax in your `-sql` command line option setting:

    -sql=object_type:generated_class:map_class

For the above scenario, this would be:

    -sql=ADDRESS:JAddress:MyAddress

If you were to enter the line in the `INPUT` file, instead of on the command line, it would look like this:

    SQL ADDRESS GENERATE JAddress AS MyAddress

In this syntax, the `JAddress` indicates the name of the class that JPublisher will generate (as `JAddress.java`), and `MyAddress` specifies the name of the class that you have written. JPublisher will map the object type `ADDRESS` to the `MyAddress` class, not to the `JAddress` class. Therefore, if you retrieve an object from the database that has an `ADDRESS` attribute, then this attribute will be created as an instance of `MyAddress` in Java. Or if you retrieve an `ADDRESS` object directly, you will retrieve it into an instance of `MyAddress`.

For an example of how you would use JPublisher to generate the `JAddress` class, see "Example: Generating a SQLData Class".

##### Writing the Class that Extends the Generated Class

The class that you create (for example, `MyAddress.java`) must have the following features. "Example: Generating a SQLData Class" illustrates all these features.

- The class must have a no-argument constructor. The easiest way to construct a properly initialized object is to invoke the constructor of the superclass, either explicitly or implicitly.

- The class must implement the `CustomDatum` interface or the `SQLData` interface. The simplest way to do this is to inherit the necessary methods from the superclass.

- If you are extending a `CustomDatum` class, you must also implement the `CustomDatumFactory` interface, either in the same class or in a different one. For example, you could have a class `Employee` that implements `CustomDatum` and a class `EmployeeFactory` that implements `CustomDatumFactory`.

##### Adding Methods to JPublisher-generated Classes

Another way to enhance the functionality of a JPublisher-generated class is to add methods to it. However, we do not recommend adding methods to the generated class if you anticipate running JPublisher at some future time, to regenerate the class. If you regenerate a class that you have modified in this way, your changes (that is, the methods you have added) will be overwritten. Even if you direct JPublisher output to a separate file, you will still need to merge your changes into the file.

### INPUT File Precautions

This section describes some of the common errors it is possible to make in the `INPUT` file. 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 the file 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 `get` and `set` 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 `get` methods with the same name and the two `set` 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.

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