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 REFs 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 SQLData 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 oracle.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 

---