Skip Headers

Oracle9i JPublisher User's Guide
Release 1 (9.0.1)

Part Number A90214-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

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

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

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  
Option Name  Description  Default Value 

-access 

Determines the access modifiers that JPublisher includes in generated method definitions. 

public 

-builtintypes 

Specifies the datatype mappings (jdbc or oracle) for non-numeric, non-LOB built-in datatypes. 

jdbc 

-case 

Specifies the case of Java identifiers that JPublisher generates.  

mixed 

-compatible 

Specifies the general Oracle8i compatibility mode, or the particular interface to implement in generated classes for Oracle mapping of user-defined types--ORAData or CustomDatum (supported for backwards compatibility); modifies the behavior of -usertypes=oracle

oradata 

-context 

Specifies what JPublisher uses for connection contexts--the SQLJ DefaultContext class, a user-specified class, or a JPublisher-generated inner class. 

DefaultContext 

-dir 

Specifies the directory that holds generated files/packages (an empty directory name results in all generated files being placed in the current directory; a non-empty directory name specifies a directory to be used as the root directory of a class hierarchy). 

empty 

-driver 

Specifies the driver class that JPublisher uses for JDBC connections to the database. 

oracle.jdbc.OracleDriver 

-encoding 

Specifies the Java encoding of JPublisher 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 datatype 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.

Note: This is deprecated in favor of the "XXXtypes" mapping options, but is supported for backwards compatibility. 

objectjdbc 

-methods 

Determines whether JPublisher generates wrapper methods for SQL object methods and PL/SQL package methods. (As secondary effects, determines whether JPublisher generates .sqlj files or .java files, and whether it generates PL/SQL wrapper classes at all.) 

all 

-numbertypes 

Specifies the datatype mappings (jdbc, objectjdbc, bigdecimal, or oracle) JPublisher uses for numeric datatypes. 

objectjdbc 

-omit_schema_names 

Specifies whether all object types and package names JPublisher generates include the schema name. 

do not omit schema names 

-package 

Specifies the name of the Java package into which JPublisher is generating Java wrappers. 

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: This option is deprecated in favor of -sql, but is supported for backwards compatibility.  

n/a 

-url 

Specifies the URL JPublisher uses to connect to the database. 

jdbc:oracle:oci:@

Note: With the Oracle9i release, use "oci" in the connect string for the Oracle JDBC OCI driver in any new code. For backwards compatibility, however, "oci8" and "oci7" are still accepted. 

-user 

Specifies an Oracle username and password. 

n/a 

-usertypes 

Specifies the types mappings (jdbc or oracle) JPublisher uses for user-defined SQL types. 

oracle 

JPublisher Option Tips

Be aware of the following usage notes for JPublisher options:

Notational Conventions

The JPublisher option syntax used in the following sections follows these notational conventions:

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:

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.


Note:

The -usertypes=jdbc setting requires JDK 1.2 or higher, because the SQLData interface is a JDBC 2.0 feature. 


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


Note:

If you use JPublisher in an environment that does not support the ORAData interface (such as Oracle8i JDBC 8.1.7 or prior releases), then the CustomDatum interface is used automatically if -usertypes=oracle. (You will receive an informational warning if -compatible=oradata, but the generation will take place.) 


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:

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  
SQL or PL/SQL Datatype  JDBC Mapping Type  Object JDBC Mapping Type 

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 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  
SQL or PL/SQL Datatype  Oracle Mapping Type  JDBC Mapping Type 

CLOB 

oracle.sql.CLOB 

java.sql.Clob 

BLOB 

oracle.sql.BLOB 

java.sql.Blob 

BFILE 

oracle.sql.BFILE 

oracle.sql.BFILE 


Notes:

  • BFILE is an Oracle-specific SQL type, so there is no standard java.sql.Bfile Java type.

  • The java.sql.Clob and java.sql.Blob interfaces are new in JDK 1.2. If you use JDK 1.1, you should not select -lobtypes=jdbc.

 

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  
SQL or PL/SQL Datatype  Oracle Mapping Type  JDBC Mapping Type 

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 All Types (-mapping)

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

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


Note:

This option is deprecated in favor of the more specific type mapping options: -usertypes, -numbertypes, -builtintypes, and -lobtypes. It is still supported, however, for backwards compatibility. 


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  
  -builtintypes=  -numbertypes=  -lobtypes=  -usertypes= 
-mapping=oracle 

oracle 

oracle 

oracle 

oracle 

-mapping=jdbc 

jdbc 

jdbc 

oracle 

oracle 

-mapping=objectjdbc 

jdbc 

objectjdbc 

oracle 

oracle 

-mapping=bigdecimal 

jdbc 

bigdecimal 

oracle 

oracle 


Note:

Because options are processed in the order in which they appear on the command line, if the -mapping option precedes one of the specific type mapping options (-builtintypes, -lobtypes, -numbertypes, or -usertypes) the specific type mapping option overrides the -mapping option for the relevant types. If the -mapping option follows one of the specific type mapping options, the specific type mapping option is ignored. 


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:

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.


Note:

Constructors of JPublisher-generated classes, as well as wrappers for object references, VARRAYs, and nested tables, are not affected by the value of the -access option. 


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  
-case Option Value  Description 

mixed (default) 

The first letter of every word-unit of a class name or every word-unit after the first word-unit of a method name is in uppercase. All other characters are in lower case. An underscore (_) or dollar sign ($), or any character that is illegal in Java, constitutes a word-unit boundary and is silently removed. A word-unit 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 illegal in Java 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 illegal in Java 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 illegal in Java and issues a warning message.  

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.


Note:

With a user-specified class setting, instances of that class must be used for output from the getConnectionContext() method or input to the setConnectionContext() method. See "Considerations in Using Connection Contexts and Connection Instances" for information about these methods. 


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:

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


Note:

Encoding settings, either set through the JPublisher -encoding option or the Java file.encoding setting, do not apply to Java properties files, including those specified through the JPublisher -props option. Properties files always use the encoding 8859_1. This is a feature of Java in general, not JPublisher in particular. You can, however, use Unicode escape sequences in a properties file.  


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:

or:

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


Note:

Encoding settings, either set through the JPublisher -encoding option or the Java file.encoding setting, do not apply to Java properties files, including those specified through the -props option. Properties files always use the encoding 8859_1. This is a feature of Java in general, not JPublisher in particular. You can, however, use Unicode escape sequences in a properties file.  


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.

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:

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.

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.


Note:

With the Oracle9i release, use "oci" in the connect string for the Oracle JDBC OCI driver in any new code. For backwards compatibility, however, "oci8" and "oci7" are still accepted. 


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

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


Note:

You must include the jpub. prefix (including the period) 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

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


Important:

If a user-defined type was defined in a case-sensitive way (in quotes) in SQL, then you must specify the name in quotes. For example:

SQL "CaseSenstiveType" AS CaseSensitiveType

Or, if also specifying a non-case-sensitive schema name:

SQL SCOTT."CaseSensitiveType" AS CaseSensitiveType

Or, if also specifying a case-sensitive schema name:

SQL "Scott"."CaseSensitiveType AS CaseSensitiveType

(The AS clauses, described below, are optional.)

Avoid situations where a dot (".") is part of the schema name or type name itself. 



Note:

The TYPE syntax is currently supported for compatibility, but deprecated. Use the SQL syntax instead.  


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:

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.


Note:

The Java keyword null has special meaning when used as the target Java name for an attribute or method, such as in the following example:

TRANSLATE FIRSTNAME AS null

When you map a SQL method to null, JPublisher does not generate a corresponding Java method in the mapped Java class. When you map a SQL object attribute to null, JPublisher does not generate the getter and setter methods for the attribute in the mapped Java class. 


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:

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.


Go to previous page Go to next page
Oracle
Copyright © 1996-2001, Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index