JPublisher

Input Files

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

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.