5 Command-Line Options and Input Files

File Containing Names of Objects and Packages to Translate (-input)

-input=filename
-i filename

Both formats are synonymous. The second one is provided for convenience as a command-line abbreviation.

The -input option specifies the name of a file from which JPublisher reads the names of SQL or PL/SQL entities or server-side Java classes to publish, along with any related information or instructions. JPublisher publishes each item in the list. You can think of the INPUT file as a makefile for type declarations, listing the types that need Java class definitions.

In some cases, JPublisher may 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 items to publish in an INPUT file or on the command line, then JPublisher translates all user-defined SQL types and PL/SQL 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".

Declaration of Server-Side Java Classes to Translate (-java)

-java=class_or_package_list

As described in "Publishing Server-Side Java Classes", you can use the -java option to create client-side stub classes to use in accessing server-side classes. This is an improvement over earlier JPublisher releases, in which calling Java stored procedures and functions from a database client required JDBC calls to associated PL/SQL wrappers.

The functionality of the -java option mirrors that of the -sql option, creating a client-side Java stub class to access a server-side Java class, in contrast to creating a client-side Java class to access a server-side SQL object or PL/SQL package.

When using the -java option, specify a comma-delimited list of server-side Java classes or packages.

For example:

-java=foo.bar.Baz,foo.baz.*

Or, to specify the client-side class name corresponding to Baz, instead of using the server-side name by default:

-java=foo.bar.Baz:MyBaz,foo.baz.*

(This setting creates MyBaz, not foo.bar.MyBaz.)

or:

-java=foo.bar.Baz:foo.bar.MyBaz,foo.baz.*

You can also specify a schema:

-java=foo.bar.Baz@SCOTT

If you specify the schema, then only that schema is searched. If you do not specify a schema, then the schema of the logged-in user (according to the -user option setting) is searched. This is likely the most common scenario.

As an example, assume that you want to call the following method in the server:

public String oracle.sqlj.checker.JdbcVersion.to_string();

Use the following -java setting:

-java=oracle.sqlj.checker.JdbcVersion

When you use the -java option, generated code uses the following API:

public class Client
{
   public static String getSignature(Class[]);
   public static Object invoke(Connection, String, String, 
                               String, Object[]);
   public static Object invoke(Connection, String, String, 
                               Class[], Object[]);
}

Classes for the API are located in the package oracle.jpub.reflect, so client applications must import this package.

For a setting of -java=oracle.sqlj.checker.JdbcVersion, JPublisher-generated code includes the following call:

Connection conn = ...;
String serverSqljVersion = (String)
           Client.invoke(conn, "oracle.sqlj.checker.JdbcVersion",
           "to_string", new Class[]{}, new Object[]{});

The Class[] array is for the method parameter types, and the Object[] array is for the parameter values. In this case, because to_string has no parameters, the arrays are empty.

Note the following:

• Any serializable type (such as int[] and String[], for example) can be passed as an argument.

• The semantics of this API are different from the semantics for invoking Java stored procedures or functions through a PL/SQL wrapper, in the following ways.

  • Arguments cannot be OUT or IN OUT. Returned values must all be part of the function result.

  • Exceptions are properly returned.

  • The method invocation uses invoker's rights. (There is no tuning to obtain definer's rights.) See the Oracle Database Java Developer's Guide for information about invoker's rights and definer's rights.

Input Properties File (-props)

-props=filename
-p filename

Both formats are synonymous. The second one is provided for convenience as a command-line abbreviation.

The -props option, entered on the command line, specifies the name of a JPublisher properties file that specifies JPublisher option settings. JPublisher processes the properties file as if its contents were inserted in sequence on the command line at the point of the -props option.

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

Declaration of Object Types and Packages to Translate (-sql)

-sql={toplevel|object_type_and_package_translation_syntax}
-s {toplevel|object_type_and_package_translation_syntax}

Use the -sql option to specify SQL user-defined types (objects or collections) or PL/SQL packages to publish, optionally specifying user subclasses or interfaces to generate. You can publish all or a specified subset of a PL/SQL package. The two formats of this option (-sql and -s) are synonymous. The -s format is provided for convenience as a command-line shortcut.

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. (Alternatively, you can use several -sql options in the same command line, or several jpub.sql options in a properties file.)

You can mix user-defined type names 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 translates all the types and packages in the schema to which you are connected.

In this section, the -sql option is explained in terms of the equivalent INPUT file syntax. "Understanding the Translation Statement" discusses INPUT file syntax.

You can use the any of the following syntax modes:

• -sql=name_a

  Or, in an INPUT file, use:

  SQL name_a
  
  

  JPublisher publishes name_a, naming the generated class according to default settings.

• -sql=name_a:class_c

  Or, in an INPUT file, use:

  SQL name_a AS class_c
  
  

  JPublisher publishes name_a as the generated Java class class_c.

• -sql=name_a:class_b:class_c

  Or, in an INPUT file, use:

  SQL name_a GENERATE class_b AS class_c
  
  

  In this case, name_a must represent an object type. JPublisher generates the Java class class_b and a stub class_c that extends class_b. You provide the code for class_c, which is used to represent name_a in your Java code.

• -sql=name_a:class_b#intfc_b

• -sql=name_a:class_b:class_c#intfc_c

  Use either of these syntax formats to have JPublisher generate a Java interface. This feature is particularly useful for Web services. See "JPublisher Generation of Java Interfaces".

  In the first case, class_b represents name_a and implements intfc_b. In the second case, class_c represents name_a, extends class_b, and implements intfc_c.

  Specify an interface for either the generated class or the user subclass, but not both.

  In an INPUT file, this syntax is as follows:

  SQL name_a
      [GENERATE  class_b
                 [ implements intfc_b] ]
      [AS        class_c
                 [ implements intfc_c ] ]
      ...
  
  

If you enter more than one item for translation, then the items must be separated by commas, without any white space. This example assumes that CORPORATION is a package and that EMPLOYEE and ADDRESS are object types:

-sql=CORPORATION,EMPLOYEE:OracleEmployee,ADDRESS:JAddress:MyAddress

JPublisher interprets command this as follows:

SQL CORPORATION 
SQL EMPLOYEE AS OracleEmployee 
SQL ADDRESS GENERATE JAddress AS MyAddress

And JPublisher executes the following:

• It creates a wrapper class for the CORPORATION package.

• It translates the object type EMPLOYEE as OracleEmployee.

• It generates an object reference class OracleEmployeeRef.

• It translates ADDRESS as JAddress, but generates code and references so that ADDRESS objects will be represented by the MyAddress class.

• It generates a MyAddress stub, where you will write your custom code, that extends JAddress.

• It generates an object reference class MyAddressRef.

If you want JPublisher to translate all the top-level PL/SQL subprograms in the schema to which JPublisher is connected, then 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, toplevel, for the top level subprograms. If you want the class to be generated with a different name, you can declare the name as follows:

-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 the following command.

-sql=schema_name.toplevel

In this example, schema_name is the name of the schema containing the top-level subprograms.

There are also features to publish only a subset of stored procedures in a PL/SQL package or at the top level, using the following syntax:

-sql=plsql_package(proc1+proc2+proc3+...)

Use plus signs ("+") between stored procedure names, as shown.

Alternatively, for the SQL top level, use:

-sql=toplevel(proc1+proc2+proc3+...)

Following is the syntax for a JPublisher INPUT file. Use commas between stored procedure names, as shown:

SQL plsql_package (proc1, proc2, proc3, ...) AS ...

You can also specify the subset according to stored procedure names and argument types, using the following syntax:

myfunc(sqltype1, sqltype2, ...)

In this case, only stored procedures that match in name, as well as in the number and types of arguments, will be published. For example:

-sql=mypackage(myfunc1(NUMBER, CHAR)+myfunc2(VARCHAR2))

Declaration of SQL Statements to Translate (-sqlstatement)

-sqlstatement.class=ClassName:UserClassName#UserInterfaceName
-sqlstatement.methodName=sqlStatement
-sqlstatement.return={both|resultset|beans}

The JPublisher -sqlstatement option enables you to publish SELECT, INSERT, UPDATE, or DELETE statements as Java methods. JPublisher generates SQLJ classes for this functionality.

Use -sqlstatement.class to specify the Java class in which the method will be published. In addition to the JPublisher-generated class, you can optionally specify a user subclass of the generated class, or a user interface for the generated class (or subclass, if applicable) to implement, or both. Functionality for subclasses and interfaces is the same as for the -sql option. If you also use the JPublisher -package option, then the class you specify will be in the specified package. The default class is SQLStatements.

Use -sqlstatement.methodName to specify the desired Java method name and the SQL statement.

For a SELECT statement, use -sqlstatement.return to specify whether JPublisher should generate a method that returns a generic java.sql.ResultSet instance, a method that returns an array of JavaBeans, or both methods. "Generic" means the column types of the result set are unknown or unspecified. For queries, however, the column types are actually known, allowing the option of returning specific results through an array of beans.

The name of the method returning ResultSet will be methodName(). The name of the method returning JavaBeans will be methodNameBeans().

JPublisher INPUT file syntax is as follows:

SQLSTATEMENTS_TYPE ClassName AS UserClassName
                             IMPLEMENTS UserInterfaceName
SQLSTATEMENTS_METHOD aSqlStatement AS methodName

Here is a set of sample settings:

-sqlstatement.class=MySqlStatements
-sqlstatement.getEmp="select ename from emp
                      where ename=:{myname VARCHAR}"
-sqlstatement.return=both

These settings result in the generated code shown in "Generated Code: SQL Statement".

In addition, be aware that a style file specified through the -style option is relevant to the -sqlstatement option. See "JPublisher Styles and Style Files". If a SQL statement uses Oracle datatype X, which corresponds to Java type Y, and type Y is mapped to Java type Z in the style file, then methods generated as a result of the -sqlstatement option will use Java type Z, not type Y.

For SELECT or DML statement results, you can use a style file to map the results to javax.xml.transform.Source, oracle.jdbc.rowset.OracleWebRowSet, or org.w3c.dom.Document. See "Mapping of REF CURSOR Types and Result Sets".

This example shows the use of an XML type, SYS.XMLTYPE, with the -sqlstatement option. Assume the following table is created using SQL*Plus:

SQL>  create table xmltab (a xmltype);

Now assume the following (wraparound) JPublisher command to publish an INSERT statement:

% jpub  -u scott/tiger -style=webservices10
        -sqlstatement.addEle="insert into xmltab values(:{a sys.xmltype})"

This command directs generation of the following methods.

public int addEle(javax.xml.transform.Source a) throws java.rmi.RemoteException;
public int addEleiS(javax.xml.transform.Source[] a) 
                                        throws java.rmi.RemoteException;

This is because SYS.XMLTYPE is mapped to oracle.sql.SimpleXMLType, which the webservices10 style file further maps to javax.xml.transform.Source.

The method name "addEleiS" is to avoid method overloading according to JPublisher naming conventions, with "i" reflecting the int return type and "S" reflecting the Source parameter type.

Declaration of Object Types to Translate (-types)

-types=type_translation_syntax

You can use the -types option, for SQL 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 on the command line, then JPublisher translates 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_a AS name_b
  
  

• -types=name_a:name_b:name_c

  JPublisher interprets this syntax as:

  TYPE name_a GENERATE name_b AS name_c
  
  

TYPE, TYPE...AS, and TYPE...GENERATE...AS commands have 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, then the items must be separated by commas without any white space. For example, if you enter:

-types=CORPORATION,EMPLOYEE:OracleEmployee,ADDRESS:JAddress:MyAddress

JPublisher interprets this command as:

TYPE CORPORATION 
TYPE EMPLOYEE AS OracleEmployee 
TYPE ADDRESS GENERATE JAddress AS MyAddress 

SQLJ Connection Context Classes (-context)

-context={generated|DefaultContext|user_defined}

The -context option specifies the connection context class that JPublisher uses, and possibly declares, for SQLJ classes that JPublisher produces.

The setting -context=DefaultContext is the default and results in any JPublisher-generated SQLJ classes using the SQLJ default connection context class, sqlj.runtime.ref.DefaultContext, for all connection contexts. This is sufficient for most uses.

Alternatively, you can specify any user-defined 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.

The setting -context=generated results in an inner class declaration for the connection context class _Ctx in all SQLJ classes generated by JPublisher. So, each class uses its own SQLJ connection context class. (Also see "More About Connection Contexts and Instances in SQLJ Classes".) This setting may be appropriate for Oracle8i compatibility mode (see the notes immediately following), but is otherwise not recommended. Using the DefaultContext class or a user-defined class avoids having additional connection context classes generated.

You can specify the -context option on the command line or in a properties file.

If you use a backward compatibility mode (through a -compatible setting of sqlj, 9i, 8i, or both8i) and, therefore, use .sqlj files and the SQLJ translator directly, a -context=DefaultContext setting gives you greater flexibility if you translate and compile your .sqlj files in separate steps, translating with the SQLJ -compile=false setting. If you are not using JDK 1.2-specific types—such as java.sql.BLOB, CLOB, Struct, Ref, or Array—then you can compile the resulting .java files under JDK 1.1 or under JDK 1.2 or higher. This is not the case with the setting -context=generated, because SQLJ connection context classes in JDK 1.1 use java.util.Dictionary instances for object type maps, while SQLJ connection context classes in JDK 1.2 or higher use java.util.Map instances.

A benefit of using the -context=generated setting if you are directly manipulating .sqlj files is that it permits full control over the way the SQLJ translator performs online checking. Specifically, you can check SQL user-defined types and PL/SQL packages against an appropriate 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.

JDBC Driver Class for Database Connection (-driver)

-driver=driver_class_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.

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

To specify the Thin driver, use a setting of the following form:

-url=jdbc:oracle:thin:@host:port/servicename

In this syntax, host is the name of the host on which the database is running, port is the port number, and servicename is the name of the database service. (The use of SIDs is deprecated in Oracle Database 10g, but is still supported for backward compatibility. Their use is of the form host:port:sid.)

User Name and Password for Database Connection (-user)

-user=username/password
-u username/password

Both formats are equivalent. The second one is provided for convenience as a command-line shortcut.

JPublisher requires the -user option, which specifies an Oracle user name and password, so that it can connect to the database. 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 user name scott and password tiger:

% jpub -user=scott/tiger -input=demoin -dir=demo -mapping=oracle -package=corp

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 5-2 lists the datatypes affected by the -builtintypes option and shows their Java type mappings for -builtintypes=oracle and -builtintypes=jdbc (the default).

Mappings For LOB Types (-lobtypes)

-lobtypes={jdbc|oracle}

The -lobtypes option controls datatype mappings for LOB ("large object") types. Table 5-3 shows how these types are mapped for -lobtypes=oracle (the default) and for -lobtypes=jdbc.

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:

• In JDBC mapping, most numeric datatypes are mapped to Java primitive types such as int and float, and DECIMAL and NUMBER are mapped to java.math.BigDecimal.

• In Object JDBC mapping (the default), most numeric datatypes are mapped to Java wrapper classes such as java.lang.Integer and java.lang.Float, and DECIMAL and NUMBER are mapped to java.math.BigDecimal.

• In BigDecimal mapping, all numeric datatypes are mapped to java.math.BigDecimal.

• In Oracle mapping, all numeric datatypes are mapped to oracle.sql.NUMBER.

Table 5-4 lists the datatypes affected by the -numbertypes option, and shows their Java type mappings for -numbertypes=jdbc and -numbertypes=objectjdbc (the default).

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.

When -usertypes=jdbc, JPublisher generates SQLData classes for object types. JPublisher does not generate classes for collection or object reference types in this case; you must use java.sql.Array for all collection types and java.sql.Ref for all object reference types.

Mappings for All Types (-mapping)

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

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

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

Style File for Java-to-Java Type Mappings (-style)

-style=stylename

JPublisher style files allow you to specify Java-to-Java type mappings. One use for this is to ensure that generated classes can be used in Web services.

Use the -style option to specify the name of a style file. You can use the -style option multiple times; the settings accumulate in order.

Typically, Oracle supplies the style files, but there may be situations in which you would edit or create your own. To use the Oracle style file for Web services in Oracle Database 10g, for example, use the following setting:

-style=webservices10

See "JPublisher Styles and Style Files" for more information.

Additional Entry to the Default Type Map (-adddefaulttypemap)

-adddefaulttypemap=list_of_typemap_entries

Use this option to append an entry or a comma-delimited list of entries to the JPublisher default type map. (In addition, JPublisher uses this option internally.) The format for type map entries is described in the top-level section, "Options for Type Maps".

Additional Entry to the User Type Map (-addtypemap)

-addtypemap=list_of_typemap_entries

Use this option to append an entry or a comma-delimited list of entries to the JPublisher user type map. The format for type map entries is described in the top-level section, "Options for Type Maps".

Default Type Map for JPublisher (-defaulttypemap)

-defaulttypemap=list_of_typemap_entries

JPublisher uses this option internally to set up predefined type map entries in the default type map.

The difference between the -adddefaulttypemap option and the -defaulttypemap option is that -adddefaulttypemap appends entries to the default type map, while -defaulttypemap replaces the existing default type map with the specified entries. To clear the default type map, use the following setting:

-defaulttypemap=

You may want to do this to avoid conflicts between the default type map and the user type map, for example. See "JPublisher User Type Map and Default Type Map" for additional information, including a caution about conflicts between the type maps.

Replacement of the JPublisher Type Map (-typemap)

-typemap=list_of_typemap_entries

Use this option to specify an entry or a comma-delimited list of entries to set up the user type map.

The difference between the -typemap option and the -addtypemap option is that -typemap replaces the existing user type map with the specified entries; -addtypemap appends entries to the user type map. To clear the user type map, use the following setting.

-typemap=

You may want to do this to avoid conflicts between the default type map and the user type map, for example. See "JPublisher User Type Map and Default Type Map" for additional information, including a caution about conflicts between the type maps.

The format for type map entries is described in the top-level section, "Options for Type Maps".

Method Access (-access)

-access={public|protected|package}

The -access option determines the access modifier that JPublisher includes in generated constructors, attribute setter and getter methods, member methods on object wrapper classes, and methods on PL/SQL packages.

JPublisher uses the possible option settings as follows:

• public (default): Methods are generated with the public access modifier.

• protected: Methods are generated with the protected access modifier.

• package: The access modifier is omitted, so generated methods are local to the package.

You may want to use a setting of -access=protected or -access=package if you want to control the usage of the generated JPublisher wrapper classes, for example. Perhaps you are providing your own customized versions of the wrapper classes 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.

Case of Java Identifiers (-case)

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

For class or attribute names that 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, and arguments of generated method names.

Table 5-6 describes the possible values for the -case option.

For class or attribute names that you specify through JPublisher options or the INPUT file, JPublisher retains the case of the letters in the specified name, overriding the -case option.

Method Filtering According to Parameter Modes (-filtermodes)

-filtermodes=list_of_modes_to_filter_out_or_filter_in

In some cases, particularly for code generation for Web services, not all parameter modes are supported in method signatures or attributes for the target usage of your code. The -filtermodes option enables you to filter generated code according to parameter modes. (Also see the -filtertypes option, following.)

You can specify the following for the -filtermodes option:

• in

• out

• inout

• return

Start the option setting with a "1" to include all possibilities by default (no filtering), then list specific modes or types followed by minus signs ("-") for what to exclude. Alternatively, start with a "0" to include no possibilities by default (total filtering), then list specific modes or types followed by plus signs ("+") for what to allow.

The following examples would have the same result, allowing only methods that have parameters of the in or return mode. Separate the entries by commas.

-filtermodes=0,in+,return+

-filtermodes=1,out-,inout-

Method Filtering According to Parameter Types (-filtertypes)

-filtertypes=list_of_types_to_filter_out_or_filter_in

In some cases, particularly for code generation for Web services, not all parameter types are supported in method signatures or attributes for the target usage of your code. The -filtertypes option enables you to filter generated code according to parameter types. (Also see the -filtermodes option, preceding.)

You can specify the following settings for the -filtertypes option.

• Any qualified Java type name: Specify package and class, such as java.sql.SQLData, oracle.sql.ORAData.

• .ORADATA: This setting indicates any ORAData or SQLData implementations.

• .STRUCT, .ARRAY, .OPAQUE, .REF: Each of these settings indicates any types that implement ORAData or SQLData with the corresponding _SQL_TYPECODE specification.

• .CURSOR: This setting indicates any SQLJ iterator types and java.sql.ResultSet.

• .INDEXBY: This setting indicates any indexed-by table types.

• .ORACLESQL: This setting indicates all oracle.sql.XXX types.

Start the option setting with a "1" to include all possibilities by default (no filtering), then list specific modes or types followed by minus signs ("-") for what to exclude. Alternatively, start with a "0" to include no possibilities by default (total filtering), then list specific modes or types followed by plus signs ("+") for what to allow.

In the following examples, the first filters out only .ORADATA and .ORACLESQL. The second filters everything except .CURSOR and .INDEXBY.

-filtertypes=1,.ORADATA-,.ORACLESQL-

-filtertypes=0,.CURSOR+,.INDEXBY+

The .STRUCT, .ARRAY, .OPAQUE, and .REF settings are subcategories of the .ORADATA setting, so you can have specifications such as the following, which filters out all ORAData and SQLData types except those with a typecode of STRUCT:

-filtertypes=1,.ORADATA-,.STRUCT+

Alternatively, to allow ORAData or SQLData types in general, with the exception of those with a typecode of ARRAY or REF:

-filtertypes=0,.ORADATA+,.ARRAY-,.REF-

Code Generation Adherence to the JavaBeans Specification (-generatebean)

-generatebean={true|false}

The -generatebean option is a flag that you can use to ensure that generated classes follow the JavaBeans specification. The default setting is -generatebean=false.

With the setting -generatebean=true, some generated methods are renamed so that they are not assumed to be JavaBean property getter or setter methods. This is accomplished by prefixing the method names with an underscore ("_"). For example, for classes generated from SQL table types, VARRAY types, or indexed-by table types, method names are changed as follows.

Method names are changed from:

public int getBaseType() throws SQLException; 
public int getBaseTypeName() throws SQLException; 
public int getDescriptor() throws SQLException;

Method names are changed to:

public int _getBaseType() throws SQLException;
public String _getBaseTypeName() throws SQLException; 
public ArrayDecscriptor _getDescriptor() throws SQLException; 

The changes in return types are necessary because the JavaBeans specification says that a getter method must return a bean property, but getBaseType(), getBaseTypeName(), and getDescriptor() do not return a bean property.

Class and Interface Naming Pattern (-genpattern)

-genpattern=pattern_specifications

It is often desirable to follow a certain naming pattern for Java classes, user subclasses, and interfaces generated for user-defined SQL types or packages. The -genpattern option, which you can use in conjunction with the -sql or -sqlstatement option, enables you to define such patterns conveniently and generically.

Consider the following explicit command-line options:

-sql=PERSON:PersonBase:PersonUser#Person
-sql=STUDENT:StudentBase:StudentUser#Student
-sql=GRAD_STUDENT:GradStudentBase:GradStudentUser#GradStudent

The following pair of options is equivalent to the preceding set of options:

-genpattern=%1Base:%1User#%1
-sql=PERSON,STUDENT,GRAD_STUDENT

"%1", by definition, refers to the default base names that JPublisher would create for each SQL type. By default, JPublisher would create the Java type Person for the SQL type PERSON, the Java type Student for the SQL type STUDENT, and the Java type GradStudent for the SQL type GRAD_STUDENT. So "%1Base" becomes PersonBase, StudentBase, and GradStudentBase, respectively. Similarly for "%1User".

If the -sql option specifies the output names, then "%2", by definition, refers to the specified names. For example, the following pair of options has the same effect as the earlier pair:

-genpattern=%2Base:%2User#%2
-sql=PERSON:Person,STUDENT:Student,GRAD_STUDENT:GradStudent

Following is an example that combines the -genpattern option with the -sqlstatement option:

-sqlstatement.class=SqlStmts -genpattern=%2Base:%2User:%2

These settings are equivalent to the following:

-sqlstatement.class=SqlStmtsBase:SqlStmtsUser#SqlStmts

Generation of User Subclasses (-gensubclass)

-gensubclass={true|false|force|call-super}

The value of the -gensubclass option determines whether JPublisher generates initial source files for user-provided subclasses and, if so, what format these subclasses should have.

For -gensubclass=true (the default), JPublisher generates code for the subclass only if it finds that no source file is present for the user subclass.

The -gensubclass=false setting results in JPublisher not generating any code for user subclasses.

For -gensubclass=force, JPublisher always generates code for user subclasses. It overwrites any existing content in the corresponding .java and .class files if they already exist. Use this setting with caution.

The setting -gensubclass=call-super is equivalent to -gensubclass=true, except that JPublisher generates slightly different code. By default, JPublisher generates only constructors and methods necessary for implementing, for example, the ORAData interface. JPublisher indicates how superclass methods or attribute setter and getter methods can be called, but places this code inside comments. With the call-super setting, all getters, setters, and other methods are generated. The idea is that you can specify this setting if you use Java development tools based on class introspection. Only methods relating to SQL object attributes and SQL object methods are of interest; JPublisher implementation details should remain hidden. In this case you can point the tool at the generated user subclass.

You can specify the -gensubclass option on the command line or in a properties file.

Generation of Package Classes and Wrapper Methods (-methods)

-methods={all|none|named|always,overload|unique}

The settings of the -methods option determine two things regarding the generation of wrapper methods:

• Whether JPublisher generates wrapper methods for methods (stored procedures) in SQL object types and PL/SQL packages (through a setting of all, none, named, or always)

• Whether overloaded method names are allowed (through a setting of overload or unique)

For -methods=all (the default among the first group of settings), JPublisher generates wrapper methods for all the methods in the object types and PL/SQL packages it processes. This results in generation of a SQLJ class if the underlying SQL object or package actually defines methods, but a non-SQLJ class if not. (Prior to Oracle Database 10g, SQLJ classes were always generated for the all setting.)

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

For -methods=named, JPublisher generates wrapper methods only for the methods explicitly named in the INPUT file.

The -methods=always setting also results in wrapper methods being generated; however, for backward compatibility to Oracle8i and Oracle9i JPublisher versions, this setting always results in SQLJ classes being generated for all SQL object types, regardless of whether the types define methods.

Among the overload and unique settings, -methods=overload is the default and specifies that method names in the generated code can be overloaded, such as the following:

int foo(int);
int foo(String);

Alternatively, the setting -methods=unique specifies that all method names must be unique. This is required for Web services, for example.

Consider the following functions:

function foo (a VARCHAR2(40)) return VARCHAR2;
function foo ( x int, y int) return int;

With the default -methods=overload setting, these functions are published as follows:

String foo(String a);
java.math.BigDecimal foo(java.math.BigDecimal x, java.math.BigDecimal y);

With the -methods=unique setting, they are published as follows, using a method renaming mechanism based on the first letter of the return type and argument types, as "Translation of Overloaded Methods" describes.

String foo(String a);
java.math.BigDecimal fooBBB(java.math.BigDecimal x, java.math.BigDecimal y);

To specify a setting of all, none, named, or always at the same time as you specify a setting of overload or unique, use a comma to separate the two settings, as in the following example:

-methods=always,unique

You can specify the -methods option on the command line or in a properties file.

Omission of Schema Name from Name References (-omit_schema_names)

-omit_schema_names

In publishing SQL user-defined (object and collection) types, when JPublisher references the type names in Java wrapper classes, it generally qualifies the type names with the database schema name, such as SCOTT.EMPLOYEE for the EMPLOYEE type in the SCOTT schema.

However, by specifying the -omit_schema_names option, you instruct JPublisher not to qualify SQL type names with schema names. In this case, names are qualified with a schema name only under the following circumstances:

• You declare the user-defined SQL type in a schema other than the one to which JPublisher is connected. A type from another schema always requires a schema name to identify it.

or:

• You declare the user-defined SQL type with a schema name on the command line or INPUT file. The use of a schema name with the type name on the command line or INPUT file overrides the -omit_schema_names option.

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 SQL types that you use are declared identically in the two schemas.

ORAData and SQLData classes generated by JPublisher include a static final String field that names the user-defined SQL type matching the generated class. When the code generated by JPublisher executes, the SQL type name in the generated code is used to locate the SQL type in the database. If the SQL 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 SQL type name does include the schema name, the type is looked up in that schema.

When the -omit_schema_names option is enabled, JPublisher generates the following code in the Java wrapper class for a SQL object type (and similar code to wrap a collection type):

public Datum toDatum(Connection c) throws SQLException
    { 
      if (__schemaName != null) 
      { 
        return _struct.toDatum(c, __schemaName + "." + _SQL_NAME); 
      } 
      return _struct.toDatum(c, typeName); 
    } 
    private String __schemaName = null; 
    public void __setSchemaName(String schemaName) { __schemaName = schemaName; }
  } 
  

The __setSchemaName() method enables you to explicitly set the schema name at runtime so that SQL type names can be qualified by schema even if JPublisher was run with the -omit_schema_names option enabled. Being qualified by schema is necessary if a SQL type will be accessed from another schema.

Holder Types for Output Arguments (-outarguments)

-outarguments={array|holder|return}

There are no OUT or IN OUT designations in Java, but values can be returned through holders. In JPublisher, you can specify one of three alternatives for holders:

• Arrays (the default)

• JAX-RPC holder types

• Function returns

The -outarguments option enables you to specify which mechanism to use, through a setting of array, holder, or return, respectively. This feature is particularly useful for Web services.

See "JPublisher Treatment of Output Parameters" for details about the meaning and ramifications of each of these settings.

Name for Generated Java Package (-package)

-package=package_name

The -package option specifies the name of the Java package that JPublisher generates. The name appears in a package declaration in each generated class.

If you use the -dir and -d options, the directory structure in which JPublisher places generated files reflects the package name as well as the -dir and -d settings. See "Output Directories for Generated Source and Class Files (-dir and -d)" for information about those options.

Assume the following command line:

% jpub -dir=/a/b -d=/a/b -package=c.d -sql=PERSON:Person ...

JPublisher generates the files /a/b/c/d/Person.java and /a/b/c/d/Person.class.

Additionally, the Person class includes the following package declaration:

package c.d;

Now assume the following command line:

% jpub -dir=/a/b -d=/a/b -package=c.d -sql=PERSON:Person -input=myinputfile

And assume myinputfile includes the following:

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 generates the files /a/b/e/f/Person.java and /a/b/e/f/Person.class, with the Person class including the following package declaration:

package e.f;

If you do not supply a package name, then JPublisher does not generate any package declaration. Output .java files are placed directly into the directory specified by the -dir option (or into the current directory by default), and output .class files are placed directly into the directory specified by the -d option (or into the current directory).

Sometimes JPublisher translates a type that you do not explicitly request, because the type is required by another type that is translated. (It may be an attribute of the requested type, for example.) In this case, the .java and .class files declaring the required type are also placed into the package specified on the command line, in a properties file, or in the INPUT file.

By contrast, JPublisher never translates packages or stored procedures that you do not explicitly request, because packages or stored procedures are never strictly required by SQL types or by other packages or stored procedures.

Serializability of Generated Object Wrapper Classes (-serializable)

-serializable={true|false}

The -serializable flag specifies whether the Java classes that JPublisher generates for SQL object types implement the java.io.Serializable interface. The default setting is -serializable=false. Please note the following if you choose to set -serializable=true:

• Not all object attributes are serializable. In particular, none of the Oracle LOB types, such as oracle.sql.BLOB, oracle.sql.CLOB, or oracle.sql.BFILE, can be serialized. Whenever you serialize objects with such attributes, the corresponding attribute values are initialized to null after deserialization.

• If you use object attributes of type java.sql.Blob or java.sql.Clob, then the code generated by JPublisher requires that the Oracle JDBC rowset implementation be available in the classpath. This is provided in the ocrs12.jar library at ORACLE_HOME/jdbc/lib. In this case, the underlying value of Clob and Blob objects is materialized, serialized, and subsequently retrieved.

• Whenever you deserialize objects containing attributes that are object references, the underlying connection is severed, and you cannot issue setValue() or getValue() calls on the reference. For this reason, JPublisher generates the following method into your Java classes whenever you specify -serializable=true:

  void restoreConnection(Connection)
  
  

  After deserialization, call this method once for a given object or object reference to restore the current connection into the reference or, respectively, into all transitively embedded references.

Generation of toString() Method on Object Wrapper Classes (-tostring)

-tostring={true|false}

You can use the -tostring flag to tell JPublisher to generate an additional toString() method for printing out an object value. The output resembles SQL code you would use to construct the object. The default setting is false.

File Names for PL/SQL Scripts (-plsqlfile)

-plsqlfile=plsql_wrapper_script,plsql_dropper_script

This option specifies the name of a wrapper script and a dropper script generated by JPublisher. The wrapper script contains instructions to create SQL types to map to PL/SQL types, and instructions to create the PL/SQL package that JPublisher uses for any PL/SQL wrappers (call specs), conversion functions, wrapper functions, and table functions. The dropper script contains instructions to drop these entities.

You must load the generated files into the database (using SQL*Plus, for example) and run the wrapper script to install the types and package in the database.

If the files already exist, they are overwritten. If no file names are specified, JPublisher writes to files named plsql_wrapper.sql and plsql_dropper.sql.

JPublisher outputs a note about the generated scripts, such as the following:

J2T-138, NOTE: Wrote PL/SQL package JPUB_PLSQL_WRAPPER to
file plsql_wrapper.sql. Wrote the dropping script to file plsql_dropper.sql.

Generation of PL/SQL Wrapper Functions (-plsqlmap)

-plsqlmap={true|false|always}

This option specifies whether JPublisher generates wrapper functions for stored procedures that use PL/SQL types. Each wrapper function calls the corresponding stored procedure and invokes the appropriate PL/SQL conversion functions for PL/SQL input or output of the stored procedure. Only the corresponding SQL types are exposed to Java. The setting can be any of the following:

• true (default): JPublisher generates PL/SQL wrapper functions only as needed. For any given stored procedure, if the Java code to call it and convert its PL/SQL types directly is simple enough, and if PL/SQL types are used only as IN parameters or for the function return, then generated code instead calls the stored procedure directly, processing its PL/SQL input or output through the appropriate conversion functions.

• false: JPublisher does not generate PL/SQL wrapper functions. If it encounters a PL/SQL type in a signature that cannot be supported by direct call and conversion, then it skips generation of Java code for the particular stored procedure.

• always: JPublisher generates a a PL/SQL wrapper function for every stored procedure that uses a PL/SQL type. This is useful for generating a "proxy" PL/SQL package that complements an original PL/SQL package, providing Java-accessible signatures for those functions or procedures inaccessible from Java in the original package.

See "Type Mapping Support Through PL/SQL Conversion Functions" and "Direct Use of PL/SQL Conversion Functions Versus Use of Wrapper Functions" for related information.

Package for Generated PL/SQL Code (-plsqlpackage)

-plsqlpackage=name_of_PLSQL_package

The -plsqlpackage option specifies the name of a PL/SQL package into which JPublisher places any generated PL/SQL code, including PL/SQL wrappers (call specs), conversion functions to convert between PL/SQL types and SQL types, wrapper functions to wrap stored procedures that use PL/SQL types, and table functions.

(Regarding conversion functions and wrapper functions, see "Type Mapping Support Through PL/SQL Conversion Functions" and "Direct Use of PL/SQL Conversion Functions Versus Use of Wrapper Functions" for related information.)

By default, JPublisher uses the package JPUB_PLSQL_WRAPPER.

Note that it is your responsibility to create this package in the database by running the SQL script generated by JPublisher. See "File Names for PL/SQL Scripts (-plsqlfile)".

No Compilation or Translation (-compile)

-compile={true|false|notranslate}

Use this option to suppress the compilation of generated .java files and, for backward compatibility modes, to optionally suppress the translation of generated .sqlj files. With the default true setting, all generated classes are compiled into .class files.

If you are in a backward compatibility mode (-compatible=both8i , 8i, 9i, or sqlj), then you can use a setting of -compile=notranslate to suppress SQLJ translation and Java compilation of generated source files. This leaves you with .sqlj output from JPublisher, which you can translate and compile manually, using either the JPublisher -sqlj option or the SQLJ command-line utility directly. Or you can use a setting of -compile=false to proceed with SQLJ translation, but skip Java compilation. This leaves you with .java output from JPublisher, which you can compile manually.

If you are not in a backward compatibility mode, such as if you use the default -compatible setting (oradata), you can use a setting of -compile=false to skip compilation. In this scenario, the notranslate setting is not supported, given that visible .sqlj files are not produced if you are not in a backward compatibility mode.

See "Backward Compatibility Option" for information about the -compatible option, and "Option to Access SQLJ Functionality" for information about the -sqlj option.

Output Directories for Generated Source and Class Files (-dir and -d)

-dir=directory_path
-d=directory_path

Use the -dir option to specify the root of the directory tree within which JPublisher places .java source files (or .sqlj source files for backward compatibility modes). A setting of "." (a period, or "dot") explicitly specifies the current directory as the root of the directory tree.

Similarly, use the -d option to specify the root of the directory tree within which JPublisher places compiled .class files, with the same functionality for a "." setting.

For each option, with any nonempty setting, JPublisher also uses package information from the -package option or any package name included in a SQL option setting in the INPUT file to determine the complete directory hierarchy for generated files. Also see "Name for Generated Java Package (-package) ".

For example, consider the following JPublisher (wraparound) command line:

% jpub -user=scott/tiger -d=myclasses -dir=mysource -package=a.b.c
       -sql=PERSON:Person,STUDENT:Student

This results in the following output, relative to the current directory:

mysource/a/b/c/Person.java
mysource/a/b/c/PersonRef.java
mysource/a/b/c/Student.java
mysource/a/b/c/StudentRef.java

myclasses/a/b/c/Person.class
myclasses/a/b/c/PersonRef.class
myclasses/a/b/c/Student.class
myclasses/a/b/c/StudentRef.class

By default, source and class files are placed directly into the current directory, with no package hierarchy (regardless of the -package setting or any package specification in the INPUT file). Or you can explicitly specify this behavior with empty settings:

%jpub ... -d= -dir=

You can set these options on the command line or in a properties file.

Java Character Encoding (-encoding)

-encoding=name_of_character_encoding

The -encoding option specifies the Java character encoding of the INPUT file that JPublisher reads and the source files that 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 do not have to set this option unless you specify an encoding for the SQLJ translator and Java compiler, which you can do with a SQLJ -encoding setting through the JPublisher -sqlj option. Under this scenario, you should specify the same encoding for JPublisher as for SQLJ and the compiler.

You can use the -encoding option to specify any character encoding 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://java.sun.com/j2se/1.3/docs/tooldocs/solaris/native2ascii.html

Mechanisms Used in Exposing Java to PL/SQL

Part of the JPublisher functionality for Web services call-outs from Oracle Database is to expose Java functionality to PL/SQL so that a Web services client can be called from PL/SQL. Or there may be other reasons for wanting to access Java from PL/SQL stored procedures.

JPublisher implements this functionality by generating PL/SQL wrappers, otherwise known as PL/SQL call specs. A PL/SQL wrapper is a PL/SQL package that can invoke methods of one or more given Java classes. (See the Oracle Database Java Developer's Guide for additional information.)

PL/SQL supports only static methods. Java classes with only static methods (or for which you want to expose only static methods) can be wrapped in a straightforward manner. For Java classes that have instance methods that you want to expose, however, an intermediate wrapper class is necessary to expose the instance methods as static methods for use by PL/SQL.

A wrapper class is also required if the Java class to be wrapped uses anything other than Java primitive types in its method calling sequences.

For instance methods in a class to be wrapped, JPublisher can use either or both of the following mechanisms in the wrapper class:

• Each wrapped class can be treated as a singleton, meaning that a single default instance is used. This instance is created the first time a method is called and is reused for each subsequent method call. Handles are not necessary and are not used. This mechanism is referred to as the singleton mechanism and is the default behavior for when JPublisher provides wrapper classes for Web services client proxy classes.

  A releaseXXX() method is provided to remove the reference to the default instance and permit it to be garbage-collected.

  See "Wrapper Class Generation without Handles" for details about code generation.

• Instances of the wrapped class can be identified through handles (ID numbers). JPublisher uses long numbers as handles, and creates static methods in the wrapper class with modified method signatures (in comparison to the signatures of the original instance methods) to also take the handle of the instance on which to invoke a method. This allows the PL/SQL wrapper to use the handles in accessing instances of the wrapped class. In this scenario, you must create an instance of each wrapped class to obtain a handle. Then you provide a handle for each subsequent instance method invocation. This mechanism is referred to as the handle mechanism.

  A releaseXXX(long) method is provided for releasing an individual instance according to the specified handle. A releaseAllXXX() method is provided for releasing all existing instances.

  See "Wrapper Class Generation with Handles" for a details about code generation.

Classes for Java and PL/SQL Wrapper Generation (-proxyclasses)

-proxyclasses[@server]=class_or_jar_list

You can use this option to specify a comma-delimited list of Java classes (either loose classes or JAR files) for which JPublisher creates PL/SQL wrappers. Depending on the situation, JPublisher may also create Java wrapper classes to afford access from PL/SQL. Each of the classes processed must have either public static methods or, for classes in which you want to publish instance methods, a public zero-argument constructor.

To summarize: for each class being processed, the following are generated, depending on settings of the -proxyopts option.

• A PL/SQL wrapper to allow access from PL/SQL (always produced)

• A wrapper class to expose Java instance methods as static methods, if there are any instance methods to publish

  Instance methods must be exposed as static methods to allow access from PL/SQL. A wrapper class is also necessary if the wrapped class uses anything other than Java primitive types in method calling sequences.

For Web services, use -proxywsdl instead of -proxyclasses, which is used behind the scenes and is set automatically as appropriate. Typically, the default -proxyopts setting is sufficient in this scenario.

Alternatively, you can use -proxyclasses directly, for general purposes, any time you want to create PL/SQL wrappers for Java classes. In this scenario, set -proxyclasses and -proxyopts as appropriate.

See "Mechanisms Used in Exposing Java to PL/SQL" for related information.

In using the -proxyclasses option directly, you can specify JAR files, client-side Java classes, server-side Java classes, or server-side Java packages. The option has two forms, as follows.

• -proxyclasses=class_or_jar_list, a comma-delimited list of classes or JAR files

• -proxyclasses@server=class_list, a comma-delimited list of server-side classes at the specified server

Classes and JAR files can be specified as follows.

• Class name, such as foo.bar.Baz or foo.bar.Baz.class

• Package name, such as foo.bar.* (for @server mode only)

• JAR (or ZIP) file name, such as foo/bar/baz.jar or Baz.zip

• JAR (or ZIP) file name followed by parenthesized list of classes or packages, such as baz.jar (foo.MyClass1, foo.bar.MyClass2, foo1.*)

See "Generated Code: Java and PL/SQL Wrappers for General Use" for code examples.

Settings for Java and PL/SQL Wrapper Generation (-proxyopts)

-proxyopts=setting1,setting2,...

This option is used as input by the -proxywsdl and -proxyclasses options and specifies JPublisher behavior in generating wrapper classes and PL/SQL wrappers for server-side Java classes. This is usually, but not necessarily, for Web services.

The -proxyopts option uses the basic settings listed immediately below, which can be used individually or in combinations. In this discussion, "processed classes" are the classes being wrapped—either Web services client proxy classes according to a WSDL document, if you use the -proxywsdl option, or the classes that you directly specify through the -proxyclasses option.

Where Java wrapper classes are generated, the wrapper class for a class foo.bar.MyClass would be foo.bar.MyClassJPub, unless the package is overridden by a setting of the -package option.

• Use the static setting to specify treatment of static methods of processed classes. This functions as follows:

  static: In the PL/SQL wrapper, a wrapper procedure is generated for each static method. Without this setting, static methods are ignored. For classes with only static methods, wrapper classes are not required for processed classes that use only Java primitive types in their method calling sequences.

• Use the multiple or single setting to specify treatment of instance methods of processed classes, where you want instance methods exposed as static methods. In either case, for each processed class, JPublisher generates an intermediate Java class that wraps instance methods with static methods, in addition to generating a PL/SQL wrapper.

  Use the instance setting to specify treatment of instance methods of processed classes, where you want instance methods maintained as instance methods. (This is not appropriate for Web services.)

  These settings function as follows:

  multiple: For each processed class, the Java wrapper class has a static equivalent for each instance method through the use of "handles", which identify instances of wrapped classes.

  single: With this setting, only a single default instance of each wrapped class is used during runtime. Therefore, for each processed class, the Java wrapper class has static wrapper methods for instance methods without requiring the use of handles. This is the singleton mechanism.

  instance: Instance methods are wrapped as instance methods in the Java wrapper class.

  Without one of these settings (or a jaxrpc or soap setting, which implies single), instance methods are ignored. For either of these settings, only classes that provide a public zero-argument constructor are processed. You can use both settings to generate wrapper classes of both styles.

  See "Mechanisms Used in Exposing Java to PL/SQL" for information about the handle and singleton mechanisms.

• Use the jaxrpc or soap setting to publish instance methods of Web services client proxy classes. These settings function as follows:

  jaxrpc (default setting): This is a convenience setting for wrapping JAX-RPC client proxy classes, which is appropriate for use with 10.0.x releases of Oracle Application Server 10g. JPublisher creates a Java wrapper class for each processed class, as well as creating the PL/SQL wrapper. Client proxy classes do not have static methods to be published, and, by default, instance methods are published using the singleton mechanism. So, when processing JAX-RPC client proxy classes, -proxyopts=jaxprc implies -proxyopts=single. The jaxrpc setting also results in generation of special code that is specific to JAX-RPC clients.

  soap: This setting is equivalent to the jaxrpc setting, but is for wrapping SOAP client proxy classes instead of JAX-RPC client proxy classes. This is appropriate for use with the 9.0.4 release of Oracle Application Server 10g, or any earlier releases of the application server.

Here are some basic uses of the -proxyopts option:

-proxyopts=jaxrpc

-proxyopts=soap

-proxyopts=static

-proxyopts=static,instance

-proxyopts=single

-proxyopts=single,multiple

-proxyopts=static,multiple

The static,instance setting publishes static and instance methods, maintaining instance methods as instance methods. The single,multiple setting publishes only instance methods, using both the singleton mechanism and the handle mechanism. The static,multiple setting publishes static and instance methods, using the handle mechanism to expose instance methods as static methods.

There are additional, more advanced, -proxyopts settings as well:

• noload: Do not load generated code into the database. (By default it is loaded.)

• recursive: When processing a class that extends another class, also create wrappers (PL/SQL, and Java if appropriate) for inherited methods.

• tabfun: Use this with the jaxrpc or soap setting to have JPublisher generate PL/SQL table functions for the PL/SQL package for each of the wrapped Web services operations. This exposes data through database tables rather than stored procedures or functions. Also see "Code Generation for Table Functions".

• deterministic: Use this to indicate in the generated PL/SQL wrapper that the wrapped methods are deterministic. This would typically be used with the tabfun setting. Deterministic is a PL/SQL annotation. A function declared as deterministic returns the same result given the same inputs, by definition, so that a subsequent call with the same parameter settings can be bypassed, reusing a cached result from a previous call instead.

• main(0,...): Use this with the static setting to define the wrapper methods to be generated if there is a public void String main(String[]) method in the class. A separate method is generated for each number of arguments you want to support. You can use commas or hyphens, as in the following examples:

  • main or main(0) produces a wrapper method only for zero arguments.

  • main(0,1) produces wrapper methods for zero arguments and one argument. This is the default setting.

  • main(0-3) produces wrapper methods for zero, one, two, and three arguments.

  • main(0,2-4) produces wrapper methods for zero, two, three, and four arguments.

  The maximum number of arguments in the wrapper method for the main() method is according to PL/SQL limitations.

Here is an example using the jaxrpc basic setting by default. It also uses table functions and indicates that wrapped methods are deterministic:

-proxyopts=tabfun,deterministic

Here is an example that explicitly sets static mode (presumably processing classes that are not client proxy classes) and specifies that generated code is not loaded into the database:

-proxyopts=static,noload

WSDL Document for Java and PL/SQL Wrapper Generation (-proxywsdl)

-proxywsdl=WSDL_URL

This option is used as follows:

% jpub -proxywsdl=META-INF/HelloServiceEJB.wsdl ...

Given the Web services WSDL document at the specified URL, JPublisher directs the generation of Web services client proxy classes and generates appropriate Java and PL/SQL wrappers for Web services call-outs from the database. Classes to generate and process are determined from the WSDL document. JPublisher automatically sets the -proxyclasses option accordingly, uses the -proxyopts setting (often just the default setting) as input, and executes the following steps:

1. Invokes the Oracle Database Web services assembler tool to produce Web services client proxy classes based on the WSDL document. These classes use the Oracle Database Web services client runtime to access the Web services specified in the WSDL document.

2. As appropriate or necessary, creates Java wrapper classes for the Web services client proxy classes. For each proxy class that has instance methods (as is typical), a wrapper class is necessary to expose the instance methods as static methods. Even if there are no instance methods, a wrapper class is necessary if methods of the proxy class use anything other than Java primitive types in their calling sequences.

3. Creates PL/SQL wrappers (call specs) for the generated classes, to make them accessible from PL/SQL. Because PL/SQL supports only static methods, this step requires the wrapping of instance methods by static methods that is performed in the previous step.

4. Loads generated code into the database, assuming you have specified -user and -url settings and JPublisher has established a connection, unless you specifically bypass loading through the -proxyopts=noload setting.

The -endpoint option is typically used in conjunction with the -proxywsdl option. See the next section, "Web Services Endpoint (-endpoint)".

Refer to the following sections for additional related information:

• "Mechanisms Used in Exposing Java to PL/SQL"

• "Classes for Java and PL/SQL Wrapper Generation (-proxyclasses)"

• "Settings for Java and PL/SQL Wrapper Generation (-proxyopts)"

Also see "Generated Code: Java and PL/SQL Wrappers for Web Services" for code examples.

Web Services Endpoint (-endpoint)

-endpoint=Web_services_endpoint

You can use the -endpoint option in conjunction with the -proxywsdl option to specify the Web services endpoint. The endpoint is the URL to which the Web service is deployed and from which the client accesses it.

Use this option as follows.

% jpub -proxywsdl=META-INF/HelloServiceEJB.wsdl ...
       -endpoint=http://localhost:8888/javacallout/javacallout

With this command, the Java wrapper class generated by JPublisher includes the following code:

((Stub)m_port0)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, 
                     "http://localhost:8888/javacallout/javacallout");

Without the -endpoint option, there would instead be the following commented code:

// Specify the endpoint and then uncomment the statement below
      // ((Stub)m_port0)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, 
      //                "<endpoint not provided>");

If you do not specify the endpoint in the JPublisher command line, then you must manually alter the generated wrapper class to uncomment this code and specify the appropriate endpoint.

This endpoint example is taken from the wrapper code in "Generated Code: Java and PL/SQL Wrappers for Web Services".

Proxy URL for WSDL (-httpproxy)

-httpproxy=proxy_URL

If a WSDL document used for Web services call-outs is accessed through a firewall, use this option in conjunction with the -proxywsdl option to specify a proxy URL to use in resolving the URL of the WSDL document. For example:

% jpub ... -httpproxy=http://www-proxy.oracle.com:80

Superuser for Permissions to Run Client Proxies (-sysuser)

-sysuser=superuser_name/superuser_password

Use this option to specify the name and password of a superuser account. This account is used in running the JPublisher-generated PL/SQL script that grants permissions that allow client proxy classes to access Web services using HTTP protocol. For example:

-sysuser=sys/change_on_install

Without a -sysuser setting, JPublisher does not load the generated script granting permissions. Instead, it asks you to execute the script separately.

See "Additional PL/SQL Utility Scripts" for examples of scripts to grant and revoke permissions.

Settings for the SQLJ Translator (-sqlj)

-sqlj=sqlj_options

In Oracle Database 10g, SQLJ translation is automatic by default when you run JPublisher, as discussed in "JPublisher Usage of the Oracle SQLJ Implementation". Translation is transparent, with no visible .sqlj files resulting from JPublisher code generation.

For those familiar with SQLJ options and functionality, however, you can still specify SQLJ settings for the JPublisher invocation of the SQLJ translator. Use the JPublisher -sqlj option for this, as in the following example:

% jpub -user=scott/tiger -sqlj -optcols=true -optparams=true
       -optparamdefaults=datatype1(size1),datatype2(size)

Note the following:

• There is no "=" (equals sign) following "-sqlj".

• All other JPublisher options must precede the -sqlj option. Any option setting following "-sqlj" is taken to be a SQLJ option and is passed to the SQLJ translator. In this example, -optcols, -optparams, and -optparamdefaults are SQLJ options.

You can also run JPublisher solely to translate .sqlj files that have already been produced explicitly, such as if you run JPublisher with a setting of -compatible=sqlj, which skips the automatic SQLJ translation step and results in .sqlj output files from JPublisher. In this case, use no JPublisher options aside from -sqlj. (This is a way to accomplish manual SQLJ translation if the sqlj front-end script or executable is unavailable.)

The commands following "-sqlj" are equivalent to the command line you would give to the SQLJ translator utility directly. Here is an example:

% jpub -sqlj -d=outclasses -warn=none -encoding=SJIS Foo.sqlj

This is equivalent to the following, if the SQLJ command-line translator is available:

% sqlj -d=outclasses -warn=none -encoding=SJIS Foo.sqlj

Backward-Compatible Oracle Mapping for User-Defined Types (-compatible)

-compatible={oradata|customdatum|both8i|8i|9i|sqlj}

The -compatible option has two modes of operation:

• Through a setting of oradata or customdatum, you can explicitly specify an interface to be implemented by JPublisher-generated custom Java classes (classes representing SQL user-defined types).

or:

• Through a setting of sqlj, 8i, both8i, or 9i, you can specify a backward compatibility mode.

You can use one mode or the other, but not both.

Classpath for Translation and Compilation (-classpath)

-classpath=path1:path2:...:pathN

Use this option to specify the Java classpath for JPublisher to use in resolving Java source and classes during translation and compilation. The following (wraparound) command line shows an example of its usage, adding new paths to the existing classpath:

% jpub -user=scott/tiger -sql=PERSON:Person,STUDENT:Student
       -classpath=.:$ORACLE_HOME/jdbc/lib/ocrs12.jar:$CLASSPATH

Java Compiler (-compiler-executable)

-compiler-executable=path_to_compiler_executable

Use this option if you want Java code generated by JPublisher to be compiled by anything other than the compiler that JPublisher would use by default on your system. Specify the path to an alternative compiler executable file. See the next section, "Java Version (-vm)", for an example.

Java Version (-vm)

-vm=path_to_JVM_executable

Use this option if you want to use a Java virtual machine other than the JVM that JPublisher would use by default on your system. Specify the path to an alternative Java executable file.

As an example, assume that JDK 1.4 is installed on a UNIX system at the location JDK14, relative to the current directory. Run JPublisher with the following (wraparound) command line to use the JDK 1.4 JVM and compiler when publishing Web services client proxy classes:

% jpub -vm=JDK14/bin/java -compiler-executable=JDK14/bin/javac
       -proxywsdl=hello.wsdl

Understanding the Translation Statement

The translation statement in the INPUT file identifies the names of the user-defined types and PL/SQL packages that you want JPublisher to translate. Optionally, the translation statement can also 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 as follows:

( SQL name
| SQL [schema_name.]toplevel  [(name_list)]
| 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.

Enter SQL name to identify a SQL type or a PL/SQL package that you want JPublisher to translate. JPublisher examines the name, determines whether it is for a user-defined type or a PL/SQL package, 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 TYPEtype_name if you are specifying only object types; however, TYPE syntax is deprecated.

You can enter name as schema_name.name to specify the schema to which the SQL type or package belongs. If you enter schema_name.toplevel, JPublisher translates the top-level subprograms in schema schema_name. In conjunction with TOPLEVEL, you can also supply (name_list), a comma-delimited list of names, enclosed in parentheses, to be published. JPublisher considers only top-level functions and procedures that match this list. If you do not specify this list, JPublisher generates code for all top-level subprograms.

SQL "CaseSenstiveType" AS CaseSensitiveType

SQL SCOTT."CaseSensitiveType" AS CaseSensitiveType

SQL "Scott"."CaseSensitiveType" AS CaseSensitiveType

The AS clause specifies the name of the Java class that represents the SQL user-defined type or PL/SQL package being translated.

When you use the AS clause without a GENERATE clause, JPublisher generates the class in the AS clause and maps it to the SQL type or PL/SQL package.

When you use both the GENERATE clause and the AS clause for a SQL user-defined type, the GENERATE clause specifies the name of the Java class that JPublisher generates, referred to as the base class, and the AS clause specifies the name of a Java class, referred to as the user subclass, that extends the generated base class. JPublisher produces an initial version of the user subclass, and you will typically add code for your desired functionality. JPublisher maps the SQL type to the user subclass, not to the base class. If you later run the same JPublisher command to republish the SQL type, the generated class is overwritten but the user subclass is not. (Also see "Extending JPublisher-Generated Classes".)

The java_name_1 and java_name_2 can be any legal Java names and can include package identifiers. The case of the Java names override the -case option. For more information on how to name packages, see "Package Naming Rules in the INPUT File ".

This clause optionally specifies a different name for an attribute or method. The database_member_name is the name of an attribute of a SQL object type or the name of a method (stored procedure) of an object type or PL/SQL package. The attribute or method is to be translated to simple_java_name, which can be any legal Java name. Its case overrides 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 (modified according to the setting of the -case option, if applicable). Reasons why you may want to rename an attribute 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.

Remember that your attribute names will appear embedded within getXXX() and setXXX() method names, so you may want to capitalize the first letter of your attribute names. For example, if you enter:

TRANSLATE FIRSTNAME AS FirstName

JPublisher generates a getFirstName() method and a setFirstName() method. In contrast, if you enter:

TRANSLATE FIRSTNAME AS firstName

JPublisher generates a getfirstName() method and a setfirstName() method.

TRANSLATE FIRSTNAME AS null

You can specify a package name by using a fully qualified class name in the INPUT file. If you use a simple, non-qualified class name in the INPUT file, then the fully qualified class name includes the package name from the -package option, if applicable. This is demonstrated in the following examples:

• Assume the following in the INPUT file:

  SQL A AS B 
  
  

  And assume the setting -package=a.b. In this case, a.b is the package and a.b.B is the fully qualified class name.

• Assume that you enter the following in the INPUT file and there is no -package setting:

  SQL A AS b.C
  
  

  The package is b, and b.C is the fully qualified class name.

For more examples of how the package name is determined, see "Name for Generated Java Package (-package) ".

It may 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 any additional required types. Recall the example in "Sample JPublisher Translation". Assume that 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 PL/SQL packages you do not request, because user-defined types or other PL/SQL packages cannot have dependencies on PL/SQL packages.

Sample Translation Statement

To better illustrate the function of the INPUT file, consider an updated version of the example in "Sample JPublisher Translation". Consider the following command line (a single wraparound line):

% jpub -user=scott/tiger -input=demoin -numbertypes=oracle -usertypes=oracle
       -dir=demo -d=demo -package=corp -case=same

And assume that the INPUT file demoin contains the following:

SQL employee AS Employee
  TRANSLATE NAME AS Name
            HIRE_DATE AS HireDate 

The -case=same option specifies that generated Java identifiers maintain the same case as in the database, except where you specify otherwise. (Any identifier in a CREATE TYPE or CREATE PACKAGE declaration is stored in upper case in the database unless it is quoted.)

In this example, the -case option does not apply to the EMPLOYEE type, because EMPLOYEE is specified to be translated as the Java class Employee.

For attributes, attribute identifiers not specifically mentioned in the INPUT file remain in upper case, but JPublisher translates NAME and HIRE_DATE as Name and HireDate, as specified.

The translated EMPLOYEE type is written to the following files, relative to the current directory (for UNIX in this example), reflecting the -package, -dir, and -d settings:

demo/corp/Employee.java
demo/corp/Employee.class

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 silently overwrites the first. For example, if the INPUT file contains:

type PERSON1 as Person
type PERSON2 as Person

JPublisher creates the file Person.java for PERSON1 and then overwrites 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 generates 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 ignores it without issuing a warning message.

Consider the following example from an INPUT file:

type PERSON translate X as attr1

A situation in which X is not an attribute of PERSON does not cause JPublisher to issue a warning message.

JPublisher Reserved Terms

Do not use the following reserved terms as SQL or Java identifiers in the INPUT file.

AS 
GENERATE 
IMPLEMENTS 
SQLSTATEMENTS_TYPE 
SQLSTATEMENTS_METHOD 
SQL 
TRANSLATE 
TOPLEVEL 
TYPE 
VERSION