Oracle® Database JPublisher User's Guide 10g Release 1 (10.2) Part Number B14188-01 |
|
|
View PDF |
This chapter describes the usage and syntax details of JPublisher option settings and input files to specify program behavior. It is organized into the following sections:
The following sections list and discuss JPublisher command-line options:
Table 6-1 summarizes JPublisher options. For default values, the abbreviation, NA, means not applicable. The Category column refers to the corresponding conceptual area, indicating the section of this chapter where the option is discussed.
Table 6-1 Summary of JPublisher Options
Option Name | Description | Default Value | Category |
---|---|---|---|
|
Determines the access modifiers that JPublisher includes in generated method definitions. |
|
Java code generation |
|
Appends an entry to the JPublisher default type map. |
NA |
Type maps |
|
Appends an entry to the JPublisher user type map. |
NA |
Type maps |
|
Specifies the data type mappings, |
|
Data type mappings |
|
Specifies the case of Java identifiers that JPublisher generates. |
|
Java code generation |
|
Adds to the Java classpath for JPublisher to resolve Java source and classes during translation and compilation. |
Empty |
Java environment |
|
Specifies a compatibility mode and modifies the behavior of See Also: "JPublisher Backward-Compatibility Modes and Settings" |
|
Backward compatibility |
|
Determines whether to proceed with Java compilation or suppress it. This option also affects SQLJ translation for backward-compatibility modes. |
|
Input/output |
|
Specifies a Java compiler version, in case you want a version other than the default. |
NA |
Java environment |
|
Specifies the class that JPublisher uses for SQLJ connection contexts. This can be the |
|
Connection |
|
Sets the default type map that JPublisher uses. |
Type maps |
|
|
Specifies the root directory for placement of compiled class files. |
Empty (all files directly present in the current directory) |
Input/output |
|
Specifies the root directory for placement of generated source files. |
Empty (all files directly present in the current directory) |
Input/output |
|
Specifies the driver class that JPublisher uses for Java Database Connectivity (JDBC) connections to the database. |
|
Connection |
|
Specifies the Java encoding of JPublisher input and output files. |
The value of the system property |
Input/output |
|
Specifies a Web service endpoint. This option is used in conjunction with the |
NA |
Web services |
|
Filters code generation according to specified parameter modes. |
NA |
Java code generation |
|
Filters code generation according to specified parameter types. |
NA |
Java code generation |
|
Ensures that generated code conforms to the JavaBeans specification. |
|
Java code generation |
|
Defines naming patterns for generated code. |
NA |
Java code generation |
|
Specifies whether and how to generate stub code for user subclasses. |
|
Java code generation |
|
Specifies a proxy URL to resolve the URL of a Web Services Description Language (WSDL) document for access through a firewall. This option is used in conjunction with the |
NA |
Web services |
|
Specifies a file that lists the types and packages that JPublisher translates. |
NA |
Input files/items |
|
Specifies server-side Java classes for which JPublisher generates client-side classes. |
NA |
Input files/items |
|
Specifies the |
|
Data type mappings |
|
Specifies the mapping that generated methods support for object attribute types and method argument types. Note: This option is deprecated in favor of the " |
|
Data type mappings |
|
Determines whether JPublisher generates wrapper methods for stored procedures of translated SQL objects and PL/SQL packages. This option also determines whether JPublisher generates SQLJ classes or non-SQLJ classes, and whether it generates PL/SQL wrapper classes at all. There are settings to specify whether overloaded methods are allowed. |
|
Java code generation |
|
Specifies the data type mappings, such as |
|
Data type mappings |
|
Instructs JPublisher not to include the schema in SQL type name references in generated code. |
Disabled (schema included in type names) |
Java code generation |
|
Specifies the holder type, such as arrays, Java API for XML-based Remote Procedure Call (JAX-RPC) holders, or function returns, for Java implementation of PL/SQL output parameters. |
|
Java code generation |
|
Specifies whether to ignore naming conflicts when creating SQL types. |
|
PL/SQL code generation |
|
Specifies the name of the Java package into which JPublisher generates Java wrapper classes. |
NA |
Java code generation |
|
Specifies a wrapper script to create and a dropper script to drop SQL conversion types for PL/SQL types and the PL/SQL package that JPublisher will use for generated PL/SQL code. |
|
PL/SQL code generation |
|
Specifies whether to generate PL/SQL wrapper functions for stored procedures that use PL/SQL types. |
|
PL/SQL code generation |
|
Specifies the PL/SQL package into which JPublisher generates PL/SQL code, such as call specifications, conversion functions, and wrapper functions. |
|
PL/SQL code generation |
|
Specifies a file that contains JPublisher options in addition to those listed on the command line. |
NA |
Input files/items |
|
Specifies Java classes for which JPublisher generates wrapper classes and PL/SQL wrappers according to the |
NA |
Web services |
|
Specifies required layers of Java and PL/SQL wrappers and additional related settings. Is used as input for the |
|
Web services |
|
Specifies the URL of a WSDL document for which Web services client proxy classes and associated Java wrapper classes are generated along with PL/SQL wrappers. |
NA |
Web services |
|
Specifies whether the code generated for object types implements the |
|
Java code generation |
|
Specifies object types and packages, or subsets of packages, for which JPublisher generates Java classes, and optionally subclasses and interfaces. |
NA |
Input files/items |
|
Specifies SQLJ option settings for the JPublisher invocation of the SQLJ translator. |
NA |
SQLJ |
|
Specifies SQL queries or data manipulation language (DML) statements for which JPublisher generates Java classes, and optionally subclasses and interfaces, with appropriate methods. |
NA |
Input files/items |
|
Specifies the name of a "style file" for Java-to-Java type mappings. |
NA |
Data type mappings |
|
Specifies the name and password for a superuser account that can be used to grant permissions to execute wrappers that access Web services client proxy classes in the database. |
NA |
Web services |
|
Specifies whether to generate a |
|
Java code generation |
|
Specifies the JPublisher type map. |
Empty |
Type maps |
|
Specifies object types for which JPublisher generates code. Note: This option is deprecated in favor of |
NA |
Input files/items |
|
Specifies the URL that JPublisher uses to connect to the database. |
|
Connection |
|
Specifies an Oracle user name and password for connection. |
NA |
Connection |
|
Specifies the |
|
Data type mappings |
|
Specifies a Java version, in case you want a version other than the default. |
NA |
Java environment |
Be aware of the following usage notes for JPublisher options:
JPublisher always requires the -user
option or its shorthand equivalent -u
.
Options are processed in the order in which they appear. Options from an INPUT
file are processed at the point where the -input
or -i
option occurs. Similarly, options from a properties file are processed at the point where the -props
or -p
option occurs.
As a rule, if a particular option appears more than once, JPublisher uses the value from the last occurrence. However, this is not true for the following options, which are cumulative:
-sql
-types
, which is deprecated
-java
-addtypemap
or -adddefaulttypemap
-style
In general, separate options and corresponding option values by an equal sign (=
). However, when the following options appear on the command line, you can also use a space as a separator:
-sql
or -s
, -user
or -u
, -props
or -p
, and -input
or -i
With the -sqlj
option, you must use a space instead of an equal sign, because SQLJ settings following the -sqlj
option use equal signs. Consider the following example, where each entry after "-sqlj
" is a SQLJ option:
% jpub -user=scott/tiger -sql=PERSON:Person -sqlj -optcols=true -optparams=true -optparamdefaults=datatype1(size1),datatype2(size)
It is advisable to specify a Java package for generated classes with the -package
option, either on the command line or in a properties file. For example, you could enter the following on the command line:
% jpub -sql=Person -package=e.f ...
Alternatively, you could enter the following in the properties file:
jpub.sql=Person jpub.package=e.f ...
These statements direct JPublisher to create the class Person
in the Java package e.f
, that is, to create the class e.f.Person
.
See Also:
"Properties File Structure and Syntax"If you do not specify a type or package in the INPUT
file or on the command line, then JPublisher translates all types and packages in the user schema according to the options specified on the command line or in the properties file.
The JPublisher option syntax used in the following sections uses the following notational conventions:
Braces {...}
enclose a list of possible values. Specify only one of the values within the braces.
A vertical bar |
separates alternatives within braces.
Terms in italics
are for user input. Specify an actual value or string.
Terms in boldface indicate default values.
Square brackets [...]
enclose optional items. In some cases, however, square brackets or parentheses are part of the syntax and must be entered verbatim. In this case, this manual uses boldface: [
...]
or (
...)
.
Ellipsis points ...
immediately following an item, or items enclosed in brackets, mean that you can repeat the item any number of times.
Punctuation symbols other than those described in this section are entered as shown in this manual. These include ".
" and "@
", for example.
This section documents the following JPublisher options that specify key input, either JPublisher input files, such as INPUT
files or properties files, or items to publish, such as SQL objects, PL/SQL packages, SQL queries, SQL DML statements, or server-side Java classes:
Options for input files: -input
, -props
Options for items to publish: -java
, -sql
, -sqlstatement
, -types
These options are discussed in alphabetic order.
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.
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.
Notes:
To use the -java
option, you must also specify the -user
and -url
settings for a database connection.
Functionality of the -java
option requires the sqljutl.jar
library to be loaded in the database. For more information, refer to "Required Database Setup".
It is advisable to use the same Java Development Kit (JDK) on the client as on the server.
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
Note:
If JPublisher cannot find a specified class in the schema, a specified schema or the schema of the logged-in user, then it uses theClass.forName()
method to search for the class among system classes in the Java virtual machine (JVM), typically Java run-time environment (JRE) or JDK classes.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 rightsThe 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
.
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.*)
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:
Theinstance
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.
Note:
It is typical to explicitly use the-proxyopts
option with the -proxyclasses
option than with the -proxywsdl
option. For the use of -proxywsdl
with 10.0.x releases of Oracle Application Server 10g, the default -proxyopts=jaxrpc
setting is sufficient.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.
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
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.
See Also:
"Properties File Structure and Syntax"Note:
Encoding settings, either set through the JPublisher-encoding
option or the Java file.encoding
setting, do not apply to Java properties files. Properties files always use the 8859_1
encoding. This is a feature of Java in general, and not of JPublisher in particular. However, you can use Unicode escape sequences in a properties file.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 ] ] ...
Notes:
Only SQL names that are not case-sensitive are supported on the JPublisher command line. If a user-defined type was defined in a case-sensitive way in SQL, using quotes, then you must specify the name in the JPublisher INPUT
file instead of specifying the user-defined type, in quotes, on the command line.
If your desired class and interface names follow a pattern, you can use the -genpattern
command-line option for convenience.
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 ...
Notes:
In an INPUT
file, put a stored procedure name in quotes if it is case-sensitive. For example, "proc1
". JPublisher assumes that names that are not in quotes are not case-sensitive.
Case-sensitive names are not supported on the JPublisher command line.
Specified stored procedure names can end in the wildcard character, "%
". The specification "myfunc%
", for example, matches all stored procedures that have their name starting with myfunc
, such as myfunc1
.
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))
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 methodName
Beans()
.
Note:
If your desired class and interface names follow a pattern, then you can use the-genpattern
option for convenience.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.
Note:
This example assumes that JDK 1.4 is installed and used by JPublisher. If it is installed but not used by default, then you can set the-vm
and -compiler-executable
options to specify a JDK 1.4 JVM and compiler. For more information, refer to"Java Environment Options".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
Note:
The-types
option is currently supported for compatibility, but it is deprecated. Use the -sql
option instead.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
This section documents options related to the database connection that JPublisher uses. The options are discussed in the alphabetic order.
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.
Note:
With a user-defined class, instances of that class must be used for output from thegetConnectionContext()
method or for input to the setConnectionContext()
method. Refer to "Connection Contexts and Instances in SQLJ Classes", for information about these methods.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.
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
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.
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.
Note:
The use of system identifiers (SIDs) is deprecated in Oracle Database 10g, but it is still supported for backward compatibility. Their use is of the formhost
:
port
:
sid
.
For the Oracle JDBC Oracle Call Interface (OCI) driver, use oci
in the connect string in any new code. For backward compatibility, however, oci8
is still accepted for Oracle8i drivers.
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
The following options control the data type mappings that JPublisher uses to translate object types, collection types, object reference types, and PL/SQL packages to Java classes:
The -usertypes
option controls JPublisher behavior for user-defined types, in conjunction with the -compatible
option for oracle
mapping. Specifically, it controls whether JPublisher implements the Oracle ORAData
interface or the standard SQLData
interface in generated classes, and whether JPublisher generates code for collection and object reference types.
The -numbertypes
option controls data type mappings for numeric types.
The -lobtypes
option controls data type mappings for the BLOB
, CLOB
, and BFILE
types.
The -builtintypes
option controls data type mappings for non-numeric, non-LOB, and predefined SQL and PL/SQL types.
These four options are known as the type-mapping options.
For an object type, JPublisher applies the mappings specified by the type-mapping options to the object attributes and the arguments and results of any methods included with the object. The mappings control the types that the generated accessor methods support. For example, they support the types the get
XXX
()
methods return and the set
XXX
()
methods take.
For a PL/SQL package, JPublisher applies the mappings to the arguments and results of the methods in the package. For a collection type, JPublisher applies the mappings to the element type of the collection.
In addition, there is a subsection here for the -style
option, which you can use to specify Java-to-Java type mappings, typically to support Web services. This involves an extra JPublisher step. A SQL type is mapped to a Java type that is not supported by Web services, in the JPublisher-generated base class. Then this Java type is mapped to a Java type that is supported by Web services, in the JPublisher-generated user subclass.
See Also:
"JPublisher Styles and Style Files"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.
Table 6-2 Mappings for Types Affected by the -builtintypes Option
SQL Data Type | Oracle Mapping Type | JDBC Mapping Type |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
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
.
Table 6-3 Mappings for Types Affected by the -lobtypes Option
SQL Data Type | Oracle Mapping Type | JDBC Mapping Type |
---|---|---|
|
|
|
|
|
|
|
|
|
Notes:
BFILE
is an Oracle-specific SQL type, so there is no standard java.sql.Bfile
Java type.
NCLOB
is an Oracle-specific SQL type. It denotes an NCHAR
form of use of a CLOB
and is represented as an instance of oracle.sql.NCLOB
in Java.
The java.sql.Clob
and java.sql.Blob
interfaces were introduced in the JDK 1.2 versions.
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.
Table 6-4 Mappings for Types Affected by the -numbertypes Option
SQL Data Type | JDBC Mapping Type | Object JDBC Mapping Type |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
Notes:
The -usertypes=jdbc
setting requires JDK 1.2 or later, because the SQLData
interface is a JDBC 2.0 feature.
With certain settings of the -compatible
option, a -usertypes=oracle
setting results in classes that implement the deprecated CustomDatum
interface instead of ORAData
.
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}
Note:
This option is deprecated in favor of the more specific type mapping options:-usertypes
, -numbertypes
, -builtintypes
, and -lobtypes
. However, it is still supported for backward compatibility.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.
Table 6-5 Relation of -mapping Settings to Other Mapping Option Settings
-mapping Setting | -builtintypes= | -numbertypes= | -lobtypes= | -usertypes= |
---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Note:
Options are processed in the order in which they appear on the command line. Therefore, if the-mapping
option precedes one of the specific type mapping options, -builtintypes
, -lobtypes
, -numbertypes
, or -usertypes
, then the specific type mapping option overrides the -mapping
option for the relevant types. If the -mapping
option follows one of the specific type mapping options, then the specific type mapping option is ignored.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
See Also:
"JPublisher Styles and Style Files"JPublisher code generation is influenced by entries in the JPublisher user type map or default type map, primarily to make signatures with PL/SQL types accessible to JDBC. A type map entry has one of the following formats:
-type_map_option=opaque_sql_type:java_type -type_map_option=numeric_indexed_by_table:java_numeric_type[max_length] -type_map_option=char_indexed_by_table:java_char_type[max_length](elem_size) -type_map_option=plsql_type:java_type:sql_type:sql_to_plsql_func:plsql_to_sql_func
In the type map syntax, sql_to_plsql_func
and plsql_to_sql_func
are for functions that convert between SQL and PL/SQL. Note that [
...]
and (
...)
are part of the syntax. Also note that some operating systems require you to quote command-line options that contain special characters.
The related options, which are discussed in alphabetic order in the following sections, are -addtypemap
, -adddefaulttypemap
, -defaulttypemap
, and -typemap
. The difference between -addtypemap
and -typemap
is that -addtypemap
appends entries to the user type map, while -typemap
replaces the existing user type map with the specified entries. Similarly, -adddefaulttypemap
appends entries to the default type map, while -defaulttypemap
replaces the existing default type map with the specified entries.
See Also:
"Type Mapping Support for OPAQUE Types", "Type Mapping Support for Scalar Index-by Tables", and "Type Mapping Support Through PL/SQL Conversion Functions"Here are some sample type map settings, from a properties file that uses the -defaulttypemap
and -adddefaulttypemap
options:
jpub.defaulttypemap=SYS.XMLTYPE:oracle.xdb.XMLType jpub.adddefaulttypemap=BOOLEAN:boolean:INTEGER: SYS.SQLJUTL.INT2BOOL:SYS.SQLJUTL.BOOL2INT jpub.adddefaulttypemap=INTERVAL DAY TO SECOND:String:CHAR: SYS.SQLJUTL.CHAR2IDS:SYS.SQLJUTL.IDS2CHAR jpub.adddefaulttypemap=INTERVAL YEAR TO MONTH:String:CHAR: SYS.SQLJUTL.CHAR2IYM:SYS.SQLJUTL.IYM2CHAR
Be aware that you must avoid conflicts between the default type map and user 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
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
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.
See Also:
"JPublisher User Type Map and Default Type Map" for additional information, including a caution about conflicts between the type maps.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.
This section documents options that specify JPublisher characteristics and behavior for Java code generation. For example, there are options to accomplish the following:
Filter generated code according to parameter modes or parameter types
Ensure that generated code conforms to the JavaBeans specification
Specify naming patterns
Specify how stubs are generated for user subclasses
Specify whether generated code is serializable
The following options are described in alphabetical order: -access
, -case
, -filtermodes
, -filtertypes
, -generatebean
, -genpattern
, -gensubclass
, -methods
, -omit_schema_names
, -outarguments
, -package
, -serializable
, and -tostring
.
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.
Note:
Wrapper classes for object references andVARRAY
and nested table types are not affected by the value of the -access
option.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 get
XXX
()
and set
XXX
()
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.
Table 6-6 Values for the -case Option
-case Option Value | Description |
---|---|
|
The first letter of every word unit of a class name or of every word unit after the first word unit of a method name is in uppercase. All other characters are in lowercase. An underscore (_), a dollar sign ($), or any character illegal in Java constitutes a word unit boundary and is removed without warning. A word unit boundary also occurs after |
|
JPublisher does not change the case of letters from the way they are represented in the database. Underscores and dollar signs are retained. JPublisher removes any other character illegal in Java and issues a warning message. |
|
JPublisher converts lowercase letters to uppercase and retains underscores and dollar signs. It removes any other character illegal in Java and issues a warning message. |
|
JPublisher converts uppercase letters to lowercase and retains underscores and dollar signs. It removes any other character illegal in Java and issues a warning message. |
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.
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-
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-
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 property, but getBaseType()
, getBaseTypeName()
, and getDescriptor()
do not return a bean property.
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. The syntax of this option is:
-genpattern=pattern_specifications
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
By definition, %1
refers to the default base names that JPublisher would create for each SQL type. By default, JPublisher would create the Person
Java type for the PERSON
SQL type, the Student
Java type for the STUDENT
SQL type, and the GradStudent
Java type for the GRAD_STUDENT
SQL type. So %1Base
becomes PersonBase
, StudentBase
, and GradStudentBase
, respectively. Similar results are produced 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
Note:
This is the pattern expected for Web services. Specify an output name and use that as the interface name, and appendBase
for the generated class and User
for the user subclass.The following example 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
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. The syntax of this option is:
-gensubclass={true|false|force|call-super}
For -gensubclass=true
, which is 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 an interface, 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, and JPublisher implementation details 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.
The -methods
option determines whether:
JPublisher generates wrapper methods for methods, or stored procedures in SQL object types and PL/SQL packages.
Overloaded method names are allowed.
Methods will attempt to reestablish a JDBC connection if an SQLException
is caught.
The syntax for the -methods
option is:
-methods={all|none|named|always,overload|unique,noretry|retry}
For -methods=all
, which is the default setting among the first group of settings, JPublisher generates wrapper methods for all the methods in the SQL 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 and if not, a non-SQLJ class. 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 with the 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.
Note:
For backward compatibility, JPublisher also supports the settingtrue
as equivalent to all
, the setting false
as equivalent to none
, and the setting some
as equivalent to named
.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 -methods=unique
setting specifies that all method names must be unique. This is required for Web services. 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, these functions are published using a method-renaming mechanism based on the first letter of the return type and argument types, as shown in the following example:
String foo(String a); java.math.BigDecimal fooBBB(java.math.BigDecimal x, java.math.BigDecimal y);
See Also:
"Translation of Overloaded Methods"With the -methods=retry
setting, JPublisher generates constructors with DataSource
arguments and extra code for each method published. A JDBC operation in a method is enclosed within a try...catch
block. If an SQLException
is raised when the method is processed, then the extra code will attempt to reestablish the JDBC connection and process the SQL operation again. If the attempt to reconnect fails, then the original SQLException
is thrown again.
For -methods=retry
, JPublisher generates code different from that generated for -methods=noretry
, in two respects:
An additional constructor, which takes a DataSource
object as parameter, is generated. The DataSource
object is used to get a new connection at operation invocation time.
A new JDBC connection is requested if an SQLException
is thrown.
The -methods=retry
setting takes effect only for PL/SQL stored procedures, SQL statements, AQ, and Web services call-ins for Java classes.
Note:
The use oforacle.jdbc.pool.OracleDataSource
requires JDK 1.3 or later.To specify a setting of all
, none
, named
, or always
at the same time as you specify a setting of overload
or unique
and a setting for retry
or noretry
, use a comma to separate the settings. This is shown in the following example:
-methods=always,unique,retry
You can specify the -methods
option on the command line or in a properties file.
In publishing user-defined SQL types, such as objects and collections, 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. The syntax of this option is:
-omit_schema_names
When this option is specified, 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.
You declare the user-defined SQL type with a schema name on the command line or in an 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 is 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 is processed, 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, then the type is looked up in the schema associated with the current connection when the code generated by JPublisher is processed. If the SQL type name includes the schema name, then 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 run time 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 needs to be accessed from another schema.
Note:
Although this option behaves as a boolean option, you cannot specify-omit_schema_names=true
or -omit_schema_names=false
. Specify -omit_schema_names
to enable it, and do nothing to leave it disabled.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, which is the default
JAX-RPC holder types
Function returns
The -outarguments
option enables you to specify the mechanism to use, through a setting of array
, holder
, or return
, respectively. This feature is particularly useful for Web services. The syntax of this option is:
-outarguments={array|holder|return}
See Also:
"Treatment of Output Parameters"The -package
option specifies the name of the Java package that JPublisher generates. The name appears in a package declaration in each generated class. The syntax for this option is:
-package=package_name
If you use the -dir
and -d
options, the directory structure in which JPublisher places the generated files reflects the package name as well as the -dir
and -d
settings.
Notes:
If there are conflicting package settings between a -package
option setting and a package setting in the INPUT
file, the precedence depends on the order in which the -input
and -package
options appear on the command line. The -package
setting takes precedence if that option is after the -input
option. Otherwise, the INPUT
file setting takes precedence.
If you do not use the -dir
and -d
options, or if you explicitly give them empty settings, then JPublisher places all generated files directly in the current directory, with no package hierarchy, regardless of the -package
setting.
Example 1 Consider the following command:
% 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
.
In addition, the Person
class includes the following package declaration:
package c.d;
Example 2 Now consider the following command:
% jpub -dir=/a/b -d=/a/b -package=c.d -sql=PERSON:Person -input=myinputfile
Assume that 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 specify a package name, then JPublisher does not generate any package declaration. The output .java
files are placed directly into the directory specified by the -dir
option or into the current directory by default. The 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. For example, it may be an attribute of the requested type. 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 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.
The -serializable
option specifies whether the Java classes that JPublisher generates for SQL object types implement the java.io.Serializable
interface. The default setting is -serializable=false
. The syntax for this option is:
-serializable={true|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 lost, 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.
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
. The syntax for this option is:
-tostring={true|false}
You can use -nomain=true
to avoid generating Java methods with the signature main(String[])
. This option applies to SQL publishing and server-side Java class publishing. The syntax for this option is:
-nomain[=true|false]
The -dbjava
option automatically sets -nomain=true
because of Java stored procedure limitation. In case a method with the signature main(String[])
is to be generated with the -nomain=true
setting, then JPublisher will rename the method, for example, into main0(Stringp[])
.
The default setting is:
-nomain=false
This section documents the following options that specify JPublisher behavior in generating PL/SQL code:
-overwritedbtypes
Specifies whether naming conflicts are checked before creating SQL types.
-plsqlfile
Specifies scripts to use in creating and dropping SQL types and PL/SQL packages.
-plsqlmap
Specifies whether PL/SQL wrapper functions are generated
-plsqlpackage
Specifies the name of the PL/SQL package in which JPublisher generates PL/SQL call specs, conversion functions, wrapper functions, and table functions.
These options are mostly used to support Java calls to stored procedures that use PL/SQL types. The options specify the creation and use of corresponding SQL types and the creation and use of PL/SQL conversion functions and PL/SQL wrapper functions that use the corresponding SQL types for input or output. This enables access through JDBC.
JPublisher may generate new SQL types when publishing PL/SQL types and generating PL/SQL wrappers for server-side Java classes. The -overwritedbtypes
option determines how JPublisher names the generated SQL types. The syntax for this option is:
-overwritedbtypes={true|false}
Prior to Oracle Database 10g release 2 (10.2), JPublisher checked the database for naming conflicts and chose a name, which was not already in use, for the generated SQL type. In Oracle Database 10g release 2 (10.2), JPublisher generates SQL type names by default, regardless of the existing type names in the database. The -overwritedbtypes=true
setting, which is the default, overwrites the existing types if the type name is the same as that of the generated SQL type. This enables JPublisher to generate exactly the same PL/SQL wrappers over different runs.
To ensure that JPublisher does not overwrite any type inside the database while executing the generated PL/SQL wrapper, you must explicitly specify -overwritedbtypes=false
.
A frequently reported problem in releases prior to Oracle Database 10g release 2 (10.2) is that after the generated PL/SQL wrapper is processed, rerunning the JPublisher command generates a different set of SQL types. A workaround for this problem is to run the PL/SQL dropper script before the JPublisher command is rerun.
The -plsqlfile
option specifies the name of a wrapper script and a dropper script generated by JPublisher. The syntax for this option is:
-plsqlfile=plsql_wrapper_script,plsql_dropper_script
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 or 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, then they are overwritten. If no file names are specified, then JPublisher writes to files named plsql_wrapper.sql
and plsql_dropper.sql
.
JPublisher writes 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.
The -plsqlmap
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 syntax for this option is:
-plsqlmap={true|false|always}
The setting can be any of the following:
true
This is the 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 the PL/SQL types are used only as IN
parameters or for the function return, then the generated code calls the stored procedure directly. It processes the 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 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 that are inaccessible from Java in the original package.
The -plsqlpackage
option specifies the name of the PL/SQL package into which JPublisher places any generated PL/SQL code. This includes PL/SQL wrappers or call specifications, conversion functions to convert between PL/SQL and SQL types, wrapper functions to wrap stored procedures that use PL/SQL types, and table functions. The syntax for this option is:
-plsqlpackage=name_of_PLSQL_package
By default, JPublisher uses the package JPUB_PLSQL_WRAPPER
.
Note:
You must create this package in the database by running the SQL script generated by JPublisher.Use -plsqlindextable=array
or -plsqlindextable=
int
to specify that PL/SQL index-by table of numeric and character types be mapped to Java array. The syntax for this option is:
-plsqlindextable=array|custom|int
The int
specification defines the capacity of the Java array. The default capacity is 32768. The -plsqlindextable=custom
setting specifies that PL/SQL index-by table be mapped to custom JDBC types, such as a class implementing ORAData
.
The default setting is:
-plsqlindextable=custom
This section documents options related to JPublisher input and output files and locations. These are listed in the order in which they are discussed:
-compile
Use this option if you want to suppress compilation, and optionally, SQLJ translation, if JPublisher is in a backward-compatibility mode.
-dir
Use this option to specify where the generated source files are placed.
-d
Use this option to specify where the compiled class files are placed.
-encoding
Use this option to specify the Java character encoding of the INPUT
file that JPublisher reads and the .sqlj
and .java
files that JPublisher writes.
Use the -compile
option to suppress the compilation of the generated .java
files and, for backward-compatibility modes, to optionally suppress the translation of generated .sqlj
files. The syntax for this option is:
-compile={true|false|notranslate}
With the default true
setting, all generated classes are compiled into .class
files. If you are in a backward-compatibility mode, then you can use the -compile=notranslate
setting 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 by using either the JPublisher -sqlj
option or the SQLJ command-line utility directly. You can also use the -compile=false
setting 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=oradata
setting, then you can use a setting of -compile=false
to skip compilation. In this scenario, the notranslate
setting is not supported, because visible .sqlj
files are not produced if you are not in a backward-compatibility mode.
Use the -dir
option to specify the root of the directory tree within which JPublisher places the .java
source files or the .sqlj
source files for backward-compatibility modes. The syntax for this option is:
-dir=directory_path -d=directory_path
A setting of a period (.
) 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 period (.
) setting.
For each option with any nonempty setting, JPublisher also uses package information from the -package
option or any package name included in an SQL
option setting in the INPUT
file. This information is used to determine the complete directory hierarchy for generated files.
See Also:
"Name for Generated Java Package"For example, consider the following JPublisher command:
% 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.
You can also explicitly specify this behavior with empty settings:
%jpub ... -d= -dir=
You can set these options on the command line or in a properties file.
Note:
SQLJ has-dir
and -d
options as well, with the same functionality. However, when you use the JPublisher -sqlj
option to specify SQLJ settings, use the JPublisher -dir
and -d
options, which take precedence over any SQLJ -dir
and -d
settings.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 file.encoding
system property or 8859_1
(ISO Latin-1), if this property is not set. The syntax for this option is:
-encoding=name_of_character_encoding
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. In 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
Note:
Encoding settings, either set through the JPublisher-encoding
option or the Java file.encoding
setting, do not apply to Java properties files, including those specified through the JPublisher -props
option. Properties files always use the 8859_1
encoding. This is a feature of Java in general and not JPublisher in particular. However, you can use Unicode escape sequences in a properties file.This section documents options and related concepts for accessing Java classes from server-side Java or PL/SQL. In particular, these options may be used to access Web services client code from inside the database, referred to as Web services call-outs. This section comprises the following topics:
The following list is a summary of the options relevant to Web services call-outs and how they relate to each other:
-proxyclasses=
class1,class2,...,classN
This option specifies Java classes for which Java and PL/SQL wrappers will be generated. For Web services, this option is used behind the scenes by the -proxywsdl
option and is set automatically to process generated client proxy classes.
Alternatively, you can use this option directly, for general purposes, when you want to create Java and PL/SQL wrappers for Java classes.
The -proxyclasses
option takes the -proxyopts
setting as input.
-proxyopts=
setting1,setting2,...
This option specifies JPublisher behavior in generating wrapper classes and PL/SQL wrappers. This is usually, but not necessarily, for Web services. For typical usage of the -proxywsdl
option, the -proxyopts
default setting is sufficient. If you directly use the -proxyclasses
option, then you may want specific -proxyopts
settings.
-proxywsdl=
WSDL_URL
Use this option to generate Web services client proxy classes and appropriate Java and PL/SQL wrappers, given the WSDL document at the specified URL.
The -proxywsdl
option uses the -proxyclasses
option behind the scenes and takes the -proxyopts
setting as input.
-endpoint=
Web_services_endpoint
Use this option in conjunction with the -proxywsdl
option to specify the Web services endpoint.
-httpproxy=
proxy_URL
Where the WSDL document is accessed through a firewall, use this option to specify a proxy URL to use in resolving the URL of the WSDL document.
-sysuser=
superuser_name/superuser_password
Use this option to specify the name and password for the superuser account used to grant permissions for the client proxy classes to access Web services using HTTP.
Notes:
The features described here require the dbwsclient.jar
library to be installed in Oracle Database 10g.
Several previously existing JPublisher options are used in conjunction with wrapper generation as discussed here: -dir
, -d
, -plsqlmap
, -plsqlfile
, -plsqlpackage
, and -package
. You can also specify a database connection through the -user
and -url
options so that JPublisher can load generated entities into the database.
The syntax for the -proxywsdl
option is:
-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, uses the -proxyopts
setting as input, and executes the following steps:
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 run time to access the Web services specified in the WSDL document.
Creates Java wrapper classes for the Web services client proxy classes as appropriate or necessary. For each proxy class that has instance methods, 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.
Creates PL/SQL wrappers for the generated classes, to make them accessible from PL/SQL. PL/SQL supports only static methods, so this step requires the wrapping of instance methods by static methods, This is performed in the previous step.
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.
Note:
When using-proxywsdl
:
You must use the -package
option to determine the package for generated Java classes.
For -proxyopts
, the default jaxrpc
setting is sufficient for use with 10.0.x releases of Oracle Application Server 10g. This setting uses the singleton mechanism for publishing instance methods of the Web services client proxy classes. For use with the 9.0.4 release of Oracle Application Server 10g or with earlier releases, set -proxyopts=soap
.
The -endpoint
option is typically used in conjunction with the -proxywsdl
option.
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. The syntax for this option is:
-endpoint=Web_services_endpoint
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 following statement: // ((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.
If a WSDL document used for Web services call-outs is accessed through a firewall, use the -httpproxy
option in conjunction with the -proxywsdl
option to specify a proxy URL to use in resolving the URL of the WSDL document. The syntax for this option is:
-httpproxy=proxy_URL
For example:
% jpub ... -httpproxy=http://www-proxy.oracle.com:80
Use the -sysuser
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. The syntax for this option is:
-sysuser=superuser_name/superuser_password
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.
If the -url
setting specifies a thin driver, then you must set up a password file for SYS
, which authorizes logon as SYS
, through the thin driver. To set up a password file, you must:
Add the remote_login_passwordfile
option to the database parameter file. You must use either of the following settings:
remote_login_passwordfile=shared remote_login_passwordfile=exclusive
Create a password file, if you have not already created one. You can do this by running the following command, where ORACLE_HOME
/dbs/
is an existing directory:
orapwd file="ORACLE_HOME/dbs/orapwlsqlj1" password=change_on_install entries=100 force=y
Grant remote logon privileges to a user. This can be done as follows:
% sqlplus /nolog SQL> CONN / AS sysdba Connected. SQL> GRANT sysdba TO scott; Grant succeeded.
See Also:
Oracle Database JDBC Developer's Guide and Reference for details of setting up a remoteSYS
logonThis section documents the -sqlj
option, which you can use to pass SQLJ options to the SQLJ translator through the JPublisher command line.
In Oracle Database 10g, SQLJ translation is automatic by default when you run JPublisher. Translation is transparent, with no visible .sqlj
files resulting from JPublisher code generation.
However, you can still specify SQLJ settings for the JPublisher invocation of the SQLJ translator by using the JPublisher -sqlj
option. The syntax for this option is:
-sqlj=sqlj_options
For example:
% jpub -user=scott/tiger -sqlj -optcols=true -optparams=true -optparamdefaults=datatype1(size1),datatype2(size)
Notes:
There is no equal 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 the preceding 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 the -compatible=sqlj
setting, which skips the automatic SQLJ translation step and results in .sqlj
output files from JPublisher. In this case, use no JPublisher options other than -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 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
Notes:
As an alternative to specifying SQLJ option settings through the -sqlj
option, you can specify them in the sqlj.properties
file that JPublisher supports.
The -compiler-executable
option, if set, is passed to the SQLJ translator to specify the Java compiler that the translator will use to compile Java code.
This section documents the -compatible
option, which you can use to specify any of the following:
The interface for JPublisher to implement in generated classes
Whether JPublisher should skip SQLJ translation, resulting in visible .sqlj
output files
A backward-compatibility mode to use JPublisher output in an Oracle9i or Oracle8i environment
See Also:
"Backward Compatibility and Migration"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.
Through a setting of sqlj
, 8i
, both8i
, or 9i
, you can specify a backward-compatibility mode.
You can select either of the two modes, but not both.
The syntax for this option is:
-compatible={oradata|customdatum|both8i|8i|9i|10.1|sqlj}
Using -compatible to Specify an Interface
If -usertypes=oracle
, then you have the option of setting -compatible=customdatum
, to implement the deprecated CustomDatum
interface in your generated classes for user-defined types, instead of the default ORAData
interface. CustomDatum
was replaced by ORAData
in Oracle9i Database, but is still supported for backward compatibility.
The default setting to use the ORAData
interface is oradata
. If you set -usertypes=jdbc
, then a -compatible
setting of customdatum
or oradata
is ignored.
If you use JPublisher in a pre-Oracle9i Database environment, in which the ORAData
interface is not supported, then the CustomDatum
interface is used automatically if -usertypes=oracle
. You will receive an informational warning if -compatible=oradata
, but the generation will take place.
Using -compatible to Specify a Backward-Compatibility Mode
Use the sqlj
, 10.1
, 9i
, 8i
, or both8i
setting to specify a backward-compatibility mode.
The -compatible=sqlj
setting instructs JPublisher to skip SQLJ translation and instead produce .sqlj
files that you can work with directly. The sqlj
setting has no effect on the generated code itself. To translate the resulting .sqlj
files, you can use the SQLJ translator directly, if available, or use the JPublisher -sqlj
option.
See Also:
"Option to Access SQLJ Functionality"The -compatibility=10.1
setting specifies Oracle Database 10g release 1 (10.1) compatibility mode. In this mode, the JPublisher option -dbjava
behaves the same as -java
in Oracle Database 10g release 1 (10.1).
The -compatibility=9i
setting specifies Oracle9i compatibility mode. In this mode, JPublisher generates .sqlj
files with the same code as would be generated by the Oracle9i version.
The -compatible=8i
setting specifies Oracle8i compatibility mode. This mode uses the CustomDatum
interface, generating .sqlj
files with the same code that would be generated by Oracle8i versions of JPublisher. The 8i
setting is equivalent to setting several individual JPublisher options for backward compatibility to Oracle8i. For example, behavior of method generation is equivalent to that for -methods=always
, and generation of connection context declarations is equivalent to that for -context=generated
.
The -compatible=both8i
setting is for an alternative Oracle8i compatibility mode. With this setting, wrapper classes are generated to implement both the ORAData
and CustomDatum
interfaces. Code is generated as it would have been by the Oracle8i version of JPublisher. This setting is generally preferred over the -compatible=8i
setting, because support for ORAData
is required for programs running in the middle tier, such as in Oracle Application Server. However, using ORAData
requires an Oracle9i release 1 (9.0.1) or later JDBC driver.
Note:
In any compatibility mode that results in the generation of visible.sqlj
files, remember that if you are generating Java wrapper classes for a SQL type hierarchy and any of the types contains stored procedures, then, by default, JPublisher generates .sqlj
files for all the SQL types, and not just the types that have stored procedures.This section discusses JPublisher options that you can use to determine the Java environment:
The -classpath
option specifies the Java classpath that JPublisher and SQLJ use to resolve classes during translation and compilation.
The -compiler-executable
option specifies the Java compiler for compiling the code generated by JPublisher.
The -vm
option specifies the JVM through which JPublisher is invoked.
In a UNIX environment, the jpub
script specifies the location of the Java executable that runs JPublisher. This script is generated at the time you install your database or application server instance. If the jpub
script uses a Java version prior to JDK 1.4, then some JPublisher functionality for Web services, such as call-outs and mapping to the SYS.XMLType
, are unavailable.
Use the -classpath
option to specify the Java classpath for JPublisher to use in resolving Java source and classes during translation and compilation. The syntax for this option is:
-classpath=path1:path2:...:pathN
The following command 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
Note:
SQLJ also has a-classpath
option. If you use the SQLJ -classpath
option, following the JPublisher -sqlj
option, then that setting is used for the classpath for translation and compilation, and any JPublisher -classpath
option setting is ignored. It is more straightforward to use only the JPublisher -classpath
option.Use the -compiler-executable
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. The syntax for this option is:
-compiler-executable=path_to_compiler_executable
Use the -vm
option if you want to use a JVM other than the JVM that JPublisher would use by default on your system. Specify the path to an alternative Java executable file. The syntax for this option is:
-vm=path_to_JVM_executable
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 command 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
In Oracle Database 10g release 2 (10.2), JPublisher provides the following command-line options to support migrating SQLJ to JDBC applications:
-migrate
This option enables you to turn on SQLJ migration. The syntax for setting this option is as follows:
-migrate[=true|false]
The -migrate
and -migrate=true
settings are equivalent. Both these settings indicate that JPublisher should migrate SQLJ programs specified on the command line to JDBC programs. The -migrate=false
turns off the migration mode, and SQLJ programs are translated and compiled into a Java program that possibly depends on the SQLJ run time. By default, if this option is not specified, then JPublisher behaves like -migrate=false
.
-migconn
This option enables you to specify the default JDBC connection used by the migrated code. The default JDBC connection replaces the default DefaultContext
instance in the SQLJ run time. The syntax for setting this option is as follows:
-migconn=getter:getter,setter:setter -migconn=name[[:datasource|modifier][,modifier]*]
In the first syntax, the getter
and setter
settings specify the getter and setter methods for the default connection. For example:
-migconn=getter:Test.getDefConn,setter:Test.setDefConn
In the second syntax, the name
setting specifies the default JDBC connection. The optional datasource
setting provides a JNDI data source location for initializing the default JDBC connection. The modifier
settings add the modifiers for the default connection variable. You can specify more than one modifier by using multiple modifier
settings. Examples of the usage of the second syntax are as follows:
-migconn=_defaultConn:public,static -migconn=Test._defaultConn -migconn=Test._defaultConn:jdbc/MyDataSource -migconn=_defaultConn:public,static,final
-migrsi
This option enables you to specify an interface for all ResultSet
iterator classes. The syntax for setting this option is as follows:
-migrsi=java_interface_name
For example:
-migrsi=ResultSetInterface
-migsync
This option enables you to mark static variables as synchronized
. The syntax for setting this option is as follows:
-migsync[=true|false]
The -migsync
and -migsync=true
settings mark static variables generated for migration purpose as synchronized. If you do not want the variables to be marked as synchronized, then set -migsync=false
. By default, JPublisher behaves like -migsync=true
.
-migdriver
This option enables you to specify the JDBC driver registered by the migrated code. The syntax for setting this option is as follows:
-migdriver=class_name|no
For example:
-migdriver=oracle.jdbc.driver.OracleDriver
By default, JPublisher behaves like -migdriver=oracle.jdbc.driver.OracleDriver
. If you do not want the driver registration code to be generated during migration, then set this option as follows:
-migdriver=no
-migcodegen
This option enables you to specify whether the migrated code depends on an Oracle JDBC driver or a generic JDBC driver. The syntax for setting this option is as follows:
-migcodegen=oracle|jdbc
The default behavior is -migcodegen=oracle
, indicating that Oracle-specific JDBC APIs are used in the migrated code.
-migserver
This option enables you to specify whether to migrate the program to be used on the server. The syntax for setting this option is as follows:
-migserver
The following sections describe the structure and contents of JPublisher input files:
A properties file is an optional text file in which you can specify frequently used options. Specify the name of the properties file on the JPublisher command line with the -props
option.
Note:
-props
is the only option that you cannot specify in a properties file.On each line in a properties file, enter only one option with its associated value. Enter each option setting with the following prefix, including the period:
jpub.
The jpub.
prefix is case-sensitive. White space is permitted only directly in front of jpub.
. Any other white space within the option line is significant.
Alternatively, JPublisher permits you to specify options with a double-dash (--
), which is the syntax for SQL comments, as part of the prefix:
-- jpub.
A line that does not start with either of the prefixes shown is simply ignored by JPublisher.
In addition, you can use line continuation to spread a JPublisher option over several lines in the properties file. A line to be continued must have a backslash character (\
) as the last character, immediately after the text of the line. Any leading space or double dash (--
) on the line that follows the backslash is ignored. Consider the following sample entries:
/* The next three lines represent a JPublisher option jpub.sql=SQL_TYPE:JPubJavaType:MyJavaType,\ OTHER_SQL_TYPE:OtherJPubType:MyOtherJavaType,\ LAST_SQL_TYPE:My:LastType */ -- The next two lines represent another JPublisher option -- jpub.addtypemap=PLSQL_TYPE:JavaType:SQL TYPE\ -- :SQL_TO_PLSQL_FUNCTION:PLSQL_TO_SQL_FUNCTION
Using this functionality, you can embed JPublisher options in SQL scripts, which may be useful when setting up PL/SQL-to-SQL type mappings.
JPublisher reads the options in the properties file in order, as if its contents were inserted on the command line at the point where the -props
option is located. If you specify an option more than once, then the last value encountered by JPublisher overrides previous values, except for the following options, which are cumulative:
jpub.sql
(or the deprecated jpub.types
)
jpub.java
jpub.style
jpub.addtypemap
jpub.adddefaulttypemap
For example, consider the following command:
% jpub -user=scott/tiger -sql=employee -mapping=oracle -case=lower -package=corp -dir=demo
Now consider the following:
% jpub -props=my_properties
This command is equivalent to the first example if you assume that my_properties
has a definition such as the following:
-- jpub.user=scott/tiger // jpub.user=cannot_use/java_line_comments jpub.sql=employee /* jpub.mapping=oracle */ Jpub.notreally=a jpub option jpub.case=lower jpub.package=corp jpub.dir=demo
You must include the jpub.
prefix at the beginning of each option name. If you enter anything other than white space or double dash (--
) before the option name, then JPublisher ignores the entire line.
The preceding example illustrates that white space before jpub.
is okay. It also shows that the jpub.
prefix must be all lowercase, otherwise it is ignored. Therefore the following line from the preceding example will be ignored:
Jpub.notreally=a jpub option
Specify the name of the INPUT
file on the JPublisher command line with the -input
option. This file identifies SQL user-defined types and PL/SQL packages that JPublisher should translate. It also controls the naming of the generated classes and packages. Although you can use the -sql
command-line option to specify user-defined types and packages, an INPUT
file allows you a finer degree of control over how JPublisher translates them.
If you do not specify types or packages to translate in an INPUT
file or on the command line, then JPublisher translates all user-defined types and PL/SQL packages in the schema to which it connects.
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.
SQL name | TYPE type_name 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 TYPE
type_name
if you are specifying only object types. However, the 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
, which is a comma-delimited list of names to be published, enclosed in parentheses. 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.
Note:
If a user-defined type is defined in a case-sensitive way in SQL, then you must specify the name in quotes. For example:SQL "CaseSenstiveType" AS CaseSensitiveType
Alternatively, you can also specify a schema name that is not case-sensitive:
SQL SCOTT."CaseSensitiveType" AS CaseSensitiveType
You can also specify a case-sensitive schema name:
SQL "Scott"."CaseSensitiveType" AS CaseSensitiveType
The AS
clause is optional.
Avoid situations where a period (".") is part of the schema name or the type name itself.
GENERATE java_name_1 AS java_name_2 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, which is referred to as the base class. The AS
clause specifies the name of a Java class that extends the generated base class, which is referred to as the user subclass. 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, and not to the base class. If you later run the same JPublisher command to republish the SQL type, then the generated class is overwritten, but the user subclass is not.
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 overrides the -case
option.
TRANSLATE database_member_name AS simple_java_name 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 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. The case of the Java name 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. If applicable, the Java name is modified according to the setting of the -case
option. 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 get
XXX
()
and set
XXX
()
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.
Note:
The Java keywordnull
has special meaning when used as the target Java name for an attribute or method, such as in the following example:
TRANSLATE FIRSTNAME AS null
When you map a SQL method to null
, JPublisher does not generate a corresponding Java method in the mapped Java class. When you map a SQL object attribute to null
, JPublisher does not generate the getter and setter methods for the attribute in the mapped Java class.
Package Naming Rules in the INPUT File You can specify a package name by using a fully qualified class name in the INPUT
file. If you use a simple, unqualified class name in the INPUT
file, then the fully qualified class name includes the package name from the -package
option. 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.
See Also:
"Name for Generated Java Package"Note:
If there are conflicting package settings between a-package
option setting and a package setting in the INPUT
file, then the precedence depends on the order in which the -input
and -package
options appear on the command line. The -package
setting takes precedence if that option is after the -input
option, else the INPUT
file setting takes precedence.Translating Additional Types It may be necessary for JPublisher to translate additional types that are 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.
Consider the example in "Sample JPublisher Translation". Assume that the object type definition for EMPLOYEE
includes an attribute called ADDRESS
, and ADDRESS
is 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.
To better illustrate the function of the INPUT
file, consider an updated version of the example in "Sample JPublisher Translation".
Consider the following command:
% 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 uppercase 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 uppercase, 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
This section describes possible INPUT
file error conditions that JPublisher will currently not report. There is also a section for reserved terms.
If you request the same Java class name for two different object types, the second class overwrites the first without warning. Consider that the INPUT
file contains:
type PERSON1 as Person type PERSON2 as Person
JPublisher creates the Person.java
file for PERSON1
and then overwrites it for the PERSON2
type.
If you request the same attribute name for two different object attributes, JPublisher generates get
XXX
()
and set
XXX
()
methods for both attributes without issuing a warning message. The question of whether the generated class is valid in Java depends on whether the two get
XXX
()
methods with the same name and the two set
XXX
()
methods with the same name have different argument types so that they may be unambiguously overloaded.
If you specify a nonexistent object attribute in the TRANSLATE
clause, then 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.