6 Command-Line Options and Input Files

File Containing Names of Objects and Packages to Translate

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, which lists the types that need Java class definitions.

The syntax of the -input option is as follows:

-input=filename
-i filename

Both formats are synonymous. The second one is a convenient command-line shortcut.

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.

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.

Declaration of Server-Side Java Classes to Publish

The -java option enables you to create client-side stub classes to access 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 syntax of the -java option is as follows:

-java=class_or_package_list

The functionality of the -java option mirrors that of the -sql option. It creates 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 and 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 the most likely scenario.

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

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

Use the following -java setting:

-java=oracle.sqlj.checker.JdbcVersion

Code Generation for -java Option 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 oracle.jpub.reflect package, 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[] or String[], 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 be part of the function result.

  • Exceptions are properly returned.

  • Method invocation uses invoker's rights. There is no tuning to obtain definer's rights.

    See Also:

    Oracle Database Java Developer's Guide for information about invoker's rights and definer's rights

Declaration of Server-Side Java Classes to Publish

The related options for publishing a server-side Java class are:

• -dbajva=class_list
  
  

• -proxyopts=single|multiple|static|arrayin|arrayout|arrayinout|arrayall|noload
  
  

• -compatible=10.1
  
  

• -sysuser=user/password
  
  

• -plsqlfile=wrapper[,dropper]
  
  

• -plsqlpackage=name
  
  

Oracle Database 10g release 1 (10.1) introduces the -java option to publish server-side Java classes. Oracle Database 10g release 2 (10.2) introduces a new approach toward server-side Java class publishing. The -dbjava option publishes a server-side Java class into PL/SQL, or into client-side Java class. The class_list specification is a comma-delimited list of server-side classes at the specified server. The class_list item is of the form classname[:name[#interface]]. It can also be a package name. Consider the option:

-dbajva=classname[:name[#interface]]

If name is not specified, then the server-side Java class, classname, is published into PL/SQL, else into the client-side Java class, name. If interface is specified, then the interface file is generated for the client-side Java class.

When used with -dbjava, the -proxyopts option indicates whether to map instance methods using a singleton instance or using multiple instances, and also whether to map methods with array parameters assuming arrays as IN, OUT, IN OUT, or all the modes. The -proxyopts=static setting specifies that only static methods should be published. The default setting, -proxyopts=single,arrayin, indicates that instance methods are called using a singleton instance and array parameters are considered as input. The -proxyopts=noload setting forbids JPublisher from loading the generated PL/SQL and Java stored procedure wrappers.

The -compatible=10.1 option makes -dbjava equivalent to -java.

Declaration of Server-Side Java Classes to Publish

The related options for publishing server-side Java class are:

• -proxyclasses=class_or_jar_list
  
  

• -proxyopts=single|multiple|static|arrayin|arrayout|arrayinout|arrayall
  
  

• -plsqlfile=wrapper[,dropper]
  
  

• -plsqlpackage=name
  
  

The -proxyclasses option is similar to -dbjava. While -dbjava requires that the classes to be published exist in the database, -proxyclasses requires that the classes appear in the classpath. Typically, by using -proxyclasses, you can load the exposed classes and the generated wrappers into the database later.

The -proxyclasses option generates only a PL/SQL wrapper. Unlike -dbjava, it will not generate client-side Java code for a server-side Java class. Also, unlike -dbjava, -proxyclasses does not load the generated Java stored procedure into the database.

You can use the -proxyclasses option to specify a comma-delimited list of Java classes, either loose classes or Java Archive (JAR) files, for which JPublisher creates PL/SQL wrappers. Depending on the situation, JPublisher can 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, the following are generated for each class being processed, depending on the -proxyopts option settings:

• A PL/SQL wrapper to allow access from PL/SQL. This is always generated.

• 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 the method calling sequences.

While using the -proxyclasses option directly, you can specify JAR files and Java classes that exist in the classpath. 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.*)

Settings for Java and PL/SQL Wrapper Generation

The -proxyopts option is used as input by the -dbjava, -proxywsdl, and -proxyclasses options and specifies JPublisher behavior in generating wrapper classes and PL/SQL wrappers for server-side Java classes.

The syntax of the -proxyopts option is as follows:

-proxyopts=setting1,setting2,...

This option uses the basic settings, which can be used individually or in combinations. In this discussion, processed classes are the classes that are wrapped by using the -dbjava, -proxywsdl, or -proxyclasses options.

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.

You can use the basic -proxyopts settings as follows:

• Use the static setting to specify the treatment of static methods of processed classes.

  With this setting, 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.

  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

    Only a single default instance of each wrapped class is used during run time. 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.

    Note:

    The instance setting is not appropriate for Web services.

  The instance methods are ignored if one of these settings or a jaxrpc or soap setting, which implies single, is not specified. 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.

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

  • jaxrpc

    This is the default setting. It is a convenient setting for wrapping JAX-RPC client proxy classes, which is appropriate for use with Oracle Application Server 10g 10.0.1 and later releases. JPublisher creates a Java wrapper class for each processed class and also creates the PL/SQL wrapper. Client proxy classes do not have static methods to be published, and instance methods are published using the singleton mechanism by default. Therefore, when processing JAX-RPC client proxy classes, -proxyopts=jaxrpc 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 used for wrapping SOAP client proxy classes instead of JAX-RPC client proxy classes. This is appropriate for use with Oracle Application Server 10g 9.0.4 and earlier releases.

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. 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, advanced -proxyopts settings as well. The functionality of each setting is as follows:

• noload

  Use this to indicate that the generated code need not be loaded into the database. By default, the generated code is loaded.

• recursive

  Use this to indicate that when processing a class that extends another class, also create PL/SQL and Java wrappers, if appropriate, for inherited methods.

• tabfun

  Use this with the jaxrpc or soap setting for JPublisher to 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.

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

  See Also:

  Oracle Database SQL Reference for information about DETERMINISTIC functions

• 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 that you want to support. You can use commas or hyphens when indicating the number of arguments, 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.

The following example uses the jaxrpc basic setting by default. It also uses table functions and indicates that wrapped methods are deterministic:

-proxyopts=tabfun,deterministic

The following example explicitly sets the static mode, processing classes that are not client proxy classes, and specifies that the generated code should not be loaded into the database:

-proxyopts=static,noload

Input Properties File

The -props option 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 where the -props option is specified.

The syntax of the -props option is as follows:

-props=filename
-p filename

Both formats are synonymous. The second one is provided as a convenient command-line shortcut.

If more than one properties file appears on the command line, then JPublisher processes them with the other command-line options, in the order in which they appear.

Declaration of Object Types and Packages to Translate

The -sql option is used to specify the user-defined SQL types, such as objects or collections, or the PL/SQL packages that need to be published. Optionally, you can specify the user subclasses or interfaces that should be generated. You can publish all or a specific subset of a PL/SQL package.

The syntax of the -sql option is as follows:

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

The two formats of this option, -sql and -s, are synonymous. The -s format is provided as a convenient 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.

If you do not specify 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.

You can use the any of the following syntax modes:

• -sql=name_a

  JPublisher publishes name_a, naming the generated class according to the default settings. In an INPUT file, you specify this options as follows:

  SQL name_a
  
  

• -sql=name_a:class_c

  JPublisher publishes name_a as the generated Java class class_c. In an INPUT file, you specify this options as follows:

  SQL name_a AS class_c
  
  

• -sql=name_a:class_b:class_c

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

  SQL name_a GENERATE class_b AS class_c
  
  

• -sql=name_a:class_b#intfc_b

• -sql=name_a:class_b:class_c#intfc_c

  You can use either of these syntax formats to have JPublisher generate a Java interface. This feature is particularly useful for Web services. 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.

  See Also:

  "Generation of Java Interfaces"

  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 this command as follows:

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

JPublisher performs the following actions:

• Creates a wrapper class for the CORPORATION package.

• Translates the EMPLOYEE object type as OracleEmployee.

• Generates an object reference class, OracleEmployeeRef.

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

• Generates a MyAddress stub, which extends JAddress, where you can write your custom code.

• 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 following 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, then enter:

-sql=schema_name.toplevel

In this example, schema_name is the name of the schema containing the top-level subprograms. In addition, there are 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 a plus sign (+) between stored procedure names. Alternatively, for the SQL top level, use:

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

The following syntax is for a JPublisher INPUT file, where commas are used between stored procedure names:

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

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

myfunc(sqltype1, sqltype2, ...)

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

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

Declaration of SQL Statements to Translate

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

The syntax of the -sqlstatement option is as follows:

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

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, a user interface for the generated class or subclass, 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. Generic implies that the column types of the result set are unknown or unspecified.

For queries, however, the column types are actually known. This provides 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. If a SQL statement uses an Oracle data type X, which corresponds to a Java type Y, and type Y is mapped to a Java type Z in the style file, then methods generated as a result of the -sqlstatement option will use Z, and not 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.

Example: Using an XML Type 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 JPublisher command to publish an INSERT statement:

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

This command causes the 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 used 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

The -types option lets you list one or more individual object types that you want JPublisher to translate. The syntax of the -types option is as follows:

-types=type_translation_syntax

You can use the -types option, for SQL object types only and when you do not need the generality of an INPUT file. 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.

Enter -types=... on the command line, followed by one or more object type translations that 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

The -context option specifies the connection context class that JPublisher uses, and possibly declares, for SQLJ classes that JPublisher produces. The syntax of the -context option is as follows:

-context={generated|DefaultContext|user_defined}

The -context=DefaultContext setting 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 exists in the classpath. The specified class will be used for all connection contexts.

The -context=generated setting results in an inner class declaration for the _Ctx connection context class in all SQLJ classes generated by JPublisher. So, each class uses its own SQLJ connection context class. This setting may be appropriate for Oracle8i compatibility mode, but it is otherwise not recommended. Using the DefaultContext class or a user-defined class avoids the generation of additional connection context classes. You can specify the -context option on the command line or in a properties file.

Notes for -context Usage in Backward-Compatibility Modes

If you use a backward-compatibility mode and use .sqlj files and the SQLJ translator directly, then 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, JDK 1.2, or later. This is not the case with the -context=generated setting, 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 later 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.

The Default datasource Option

You can use -datasource to specify the default data source for publishing SQL, PL/SQL, AQ, and server-side Java classes. With -datasource set, if the JDBC connection is not explicitly set by the application at run time, then the generated code will look up the specified Java Naming and Directory Interface (JNDI) location to get the data source and further get the JDBC connection from that data source.

The syntax of the -datasource option is as follows:

-datasource=jndi_location

JDBC Driver Class for Database Connection

The -driver option specifies the driver class that JPublisher uses for JDBC connections to the database. The syntax of this option is as follows:

-driver=driver_class_name

The default setting is:

-driver=oracle.jdbc.OracleDriver

This setting is appropriate for any Oracle JDBC driver.

Connection URL for Target Database

You can use the -url option to specify the URL of the database to which you want to connect. The syntax of the -url option is as follows:

-url=URL

The default setting is:

-url=jdbc:oracle:oci:@

To specify the JDBC 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.

User Name and Password for Database Connection

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, then JPublisher prints an error message and stops execution.

The syntax of the -user option is as follows:

-user=username/password
-u username/password

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

For example, the following command directs JPublisher to connect to the database with the user name scott and password tiger:

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

Mappings for Built-In Types

The -builtintypes option controls data type mappings for all the built-in data types except the LOB types, which are controlled by the -lobtypes option, and the different numeric types, which are controlled by the -numbertypes option. The syntax of the -builtintypes option is as follows:

-builtintypes={jdbc|oracle}

Table 6-2 lists the data types affected by the -builtintypes option and shows their Java type mappings for -builtintypes=oracle and -builtintypes=jdbc, which is the default.

Mappings for LOB Types

The -lobtypes option controls data type mappings for LOB types. The syntax of the -lobtypes option is as follows:

-lobtypes={jdbc|oracle}

Table 6-3 shows how these types are mapped for -lobtypes=oracle, which is the default, and for -lobtypes=jdbc.

Mappings for Numeric Types

The -numbertypes option controls data type mappings for numeric SQL and PL/SQL types. The syntax of the -numbertypes option is as follows:

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

The following choices are available:

• In JDBC mapping, most numeric data types 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, which is the default, most numeric data types are mapped to Java wrapper classes, such as java.lang.Integer and java.lang.Float. DECIMAL and NUMBER are mapped to java.math.BigDecimal.

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

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

Table 6-4 lists the data types affected by the -numbertypes option and shows their Java type mappings for -numbertypes=jdbc and -numbertypes=objectjdbc, which is the default.

Mappings for User-Defined Types

The -usertypes option controls whether JPublisher implements the Oracle ORAData interface or the standard SQLData interface in generated classes for user-defined types. The syntax of the -usertypes option is as follows:

-usertypes={oracle|jdbc}

When -usertypes=oracle, which is 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

The -mapping option specifies mapping for all data types, so offers little flexibility between types. The syntax of the -mapping option is as follows:

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

The -mapping=oracle setting 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. This is summarized in Table 6-5.

Style File for Java-to-Java Type Mappings

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. You 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. The syntax of the -style option is as follows:

-style=stylename

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

Adding an Entry to the Default Type Map

Use the -adddefaulttypemap 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 syntax of this option is:

-adddefaulttypemap=list_of_typemap_entries

Additional Entry to the User Type Map

Use the -addtypemap option to append an entry or a comma-delimited list of entries to the JPublisher user type map. The syntax of this option is:

-addtypemap=list_of_typemap_entries

Default Type Map for JPublisher

JPublisher uses the -defaulttypemap option internally to set up predefined type map entries in the default type map. The syntax of this option is:

-defaulttypemap=list_of_typemap_entries

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.

Replacement of the JPublisher Type Map

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

-typemap=list_of_typemap_entries

The difference between the -typemap option and the -addtypemap option is that -typemap replaces the existing user type map with the specified entries and -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.

Method Access

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. The syntax of this option is:

-access={public|protected|package}

JPublisher uses the possible option settings as follows:

• public

  Methods are generated with the public access modifier. This is the default option setting.

• 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, when you provide 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

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. The syntax of this option is:

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

Table 6-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 and overrides the -case option.

Method Filtering According to Parameter Modes

In some cases, particularly for generating code 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. The syntax of this option is:

-filtermodes=list_of_modes_to_filter_out_or_filter_in

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, which would mean no filtering. Then list specific modes or types each followed by a minus sign (-), indicating that the mode or type should be excluded. Alternatively, start with a 0 to include no possibilities by default, which would mean total filtering, then list specific modes or types each followed by a plus sign (+), indicating that the mode or type should be allowed.

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

In some cases, particularly for generating code 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. The syntax of this option is:

-filtertypes=list_of_types_to_filter_out_or_filter_in

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, indicating no filtering, then list specific modes or types each followed by a minus sign (-), indicating that the mode or type should be excluded. Alternatively, start with a 0 to include no possibilities by default, indicating total filtering, then list specific modes or types each followed by a plus sign (+), indicating that the mode or type should be allowed.

This first example filters out only .ORADATA and .ORACLESQL. The second example 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. Therefore, 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

The -generatebean option is a flag that you can use to ensure that generated classes follow the JavaBeans specification. The syntax of this option is:

-generatebean={true|false}

The default setting is -generatebean=false. With the -generatebean=true setting, 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, or indexed-by table, 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;

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