| Oracle® Database JPublisher User's Guide 10g Release 1 (10.1) Part Number B10983-01 |
|
|
View PDF |
| Oracle® Database JPublisher User's Guide 10g Release 1 (10.1) Part Number B10983-01 |
|
|
View PDF |
This chapter covers additional features and considerations for your use of JPublisher:
The following sections summarize key JPublisher features for Web services. Most features relate to Web services call-ins to the database, covering JPublisher features that make SQL, PL/SQL, and server-side Java classes accessible to Web services clients. There are also features and options to support Web services call-outs from the database.
For additional information about Oracle Database Web services, see Oracle Database Java Developer's Guide. For general information about Oracle features for Web services, see the Oracle Application Server Web Services Developer's Guide.
The following JPublisher features support Web services call-ins to code running in Oracle Database. They are described in detail elsewhere in this manual, as noted.
Generation of Java interfaces
Using extended functionality of the -sql option, JPublisher can generate Java interfaces. This functionality eliminates the necessity to manually generate Java interfaces that represent the API from which WSDL content is to be generated. Prior to Oracle Database 10g, JPublisher could generate classes but not interfaces.
JPublisher styles and style files
Style files, along with the related -style option, allow Java-to-Java type mappings to ensure that generated classes can be used in Web services. In particular, Oracle provides the following style files to support Web services:
/oracle/jpub/mesg/webservices-common.properties /oracle/jpub/mesg/webservices10.properties /oracle/jpub/mesg/webservices9.properties
REF CURSOR returning and result set mapping
The java.sql.ResultSet type is not supported by Web services, which affects stored procedures and functions that return REF CURSOR types. JPublisher supports alternative mappings that allow the use of query results with Web services.
Options to filter what JPublisher publishes
There are several features for specifying or filtering JPublisher output, particularly to ensure that JPublisher-generated code can be exposed as Web services. Using extended functionality of the -sql option, you can publish a specified subset of stored procedures. Using the -filtertypes and -filtermodes options, you can publish stored procedures based on the modes or types of parameters or return values. Using the -generatebean option, you can specify that generated methods satisfy the JavaBeans specification.
Support for calling Java classes in the database without PL/SQL call specs
JPublisher uses the native Java interface for calls directly from a client-side Java stub, generated by JPublisher through the -java option, to the server-side Java code. Prior to Oracle Database 10g, server-side Java code could be called only through a PL/SQL wrapper, known as a call spec, that had to be created manually.
Support for publishing SQL queries or DML statements
JPublisher provides the -sqlstatement option to take a specified SELECT, UPDATE, INSERT, or DELETE statement and publish it as a method on a Java class that can be published as a Web service.
Support for unique method names
To meet Web services requirements, you can instruct JPublisher to disallow overloaded methods, instead always using unique method names.
See "Generation of Package Classes and Wrapper Methods (-methods)".
JPublisher supports Web services call-outs from Oracle Database. This is where Web services client code is written in SQL, PL/SQL, or Java to run inside the database, invoking Web services elsewhere. This support is through the -proxywsdl and -httpproxy options. In addition, the options -proxyopts and -proxyclasses are possibly relevant, but typically do not require any special settings for Web services so are not discussed here.
Here is a summary of the key options:
-proxywsdl=URL
Use this option to generate Web services client proxy classes, given the WSDL document at the specified URL. This option also generates additional wrapper classes to expose instance methods as static methods, and generates PL/SQL wrappers.
-httpproxy=proxy_URL
Where a 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.
|
Note: See "Options to Facilitate Web Services Call-Outs" for details about the options introduced here. |
JPublisher supplies some options that allow you to filter what JPublisher produces, such as by publishing just a subset of stored procedures from a package, filtering generated code according to parameter modes or parameter types, and ensuring that generated classes follow the JavaBeans specification.
The following sections offer details:
Publishing Functions or Procedures According to Parameter Modes or Types
Ensuring that Generated Methods Adhere to the JavaBeans Specification
Extended functionality of the -sql option enables you to publish just a subset of stored functions or procedures from a package or from the SQL top level.
Recall that the following syntax results in publication of all the stored procedures of a package:
-sql=plsql_package
To publish only a subset of the stored procedures of the package, use the following syntax:
-sql=plsql_package(proc1+proc2+proc3+...)
You can also specify the subset according to stored procedure names and argument types. Instead of just specifying proc1, you can specify the following:
proc1(sqltype1, sqltype2, ...)
See "Declaration of Object Types and Packages to Translate (-sql)" for additional information.
In some cases, particularly for code generation for Web services, not all parameter modes or types are supported in method signatures or attributes for the target usage of your code. The -filtermodes and -filtertypes options are introduced to allow you to filter generated code as needed, according to parameter modes, parameter types, or both.
For each option setting, start with a "1" to include all possibilities by default (no filtering), then list specific modes or types followed by minus signs ("-") for what to exclude. Alternatively, start with a "0" to include no possibilities by default (total filtering), then list specific modes or types followed by plus signs ("+") for what to allow. For example:
-filtertypes=1,.ORADATA-,.ORACLESQL- -filtertypes=0,.CURSOR+,.INDEXBY+ -filtermodes=0,in+,return+ -filtermodes=1,out-,inout-
See "Method Filtering According to Parameter Modes (-filtermodes)" and "Method Filtering According to Parameter Types (-filtertypes)" for more information.
The -generatebean option is a flag that you can use to ensure that generated classes follow the JavaBeans specification. The default setting is -generatebean=false.
With the setting -generatebean=true, some generated methods are renamed so that they are not assumed to be JavaBean property getter or setter methods. This is accomplished by prefixing the method names with an underscore ("_").
See "Code Generation Adherence to the JavaBeans Specification (-generatebean)" for additional information.
This section discusses issues of backward compatibility, compatibility between JDK versions, and migration between Oracle8i, Oracle9i, and Oracle Database 10g releases of the JPublisher utility.
Default option settings and some features of the generated code changed in Oracle9i. If you created an application using an Oracle8i implementation of JPublisher, you probably will not be able to re-run JPublisher in Oracle Database 10g (or Oracle9i) and have the generated classes still work within your application.
In addition, to a lesser degree, there were changes in JPublisher functionality between Oracle9i and Oracle Database 10g. The main difference is that .sqlj files are no longer visibly generated by default, but you can change this behavior through a JPublisher setting.
The following subsections cover the details:
Changes in JPublisher Behavior Between Oracle9i and Oracle Database 10g
Changes in JPublisher Behavior Between Oracle8i and Oracle9i
The JPublisher runtime is packaged with JDBC in the classes12.jar or ojdbc14.jar library. Code generated by an earlier version of JPublisher is compatible as follows:
It can continue to run with the current release of the JPublisher runtime.
It can continue to compile against the current release of the JPublisher runtime.
If you use an earlier release of the JPublisher runtime and the Oracle JDBC drivers in generating code, then you can compile the code against that version of the JPublisher runtime. Specifically, for use with an Oracle8i JDBC driver, JPublisher can generate code that implements the deprecated CustomDatum interface instead of the ORAData interface that replaced it.
Regarding backward compatibility, a key difference in JPublisher behavior between Oracle9i and Oracle Database 10g is that now, by default, SQLJ source code is translated automatically, with .sqlj source files being invisible to the user. (See "JPublisher Usage of the Oracle SQLJ Implementation".)
In addition, note the following changes in JPublisher behavior beginning in Oracle Database 10g:
In Oracle9i, JPublisher generated SQLJ classes with a protected constructor with a boolean argument to specify whether the object must be initialized:
protected BaseClass(boolean init) { ... }
This constructor is removed in Oracle Database 10g, because it conflicts with constructor generation for a SQL object type with BOOLEAN attributes.
Beginning in Oracle Database 10g, SMALLINT is mapped to int instead of to short in Java.
Note the following JPublisher behaviors, beginning in Oracle9i:
By default, JPublisher no longer declares the inner SQLJ connection context class _Ctx for every object type. Instead, it uses the connection context class sqlj.runtime.ref.DefaultContext throughout.
In addition, user-written code must call the getConnectionContext() method to have a connection context instance, instead of using the _ctx connection context field declared in code generated by Oracle8i versions of JPublisher. See "More About Connection Contexts and Instances in SQLJ Classes" for more information about the getConnectionContext() method.
See "Changes in User-Written Subclasses of JPublisher-Generated Classes", immediately following, for additional information.
Even with the setting -methods=true, non-SQLJ classes are generated if the underlying SQL object type or PL/SQL package does not define any methods. (But a setting of -methods=always always results in SQLJ classes being produced.)
By default, JPublisher generates code that implements the oracle.sql.ORAData interface instead of the deprecated oracle.sql.CustomDatum interface.
By default, JPublisher places generated code into the current directory, rather than into a package/directory hierarchy under the current directory.
If you provided user-written subclasses for classes generated by an Oracle8i version of JPublisher, be aware that several relevant changes were introduced, effective in Oracle9i, regarding how JPublisher generates code. You must make changes in any applications that have Oracle8i functionality if you want to use them in Oracle9i or Oracle Database 10g.
|
Note: If you use the-compatible=8i or -compatible=both8i option setting, you will not see the changes discussed here, and your application will continue to build and work as before. See "Backward Compatibility Option" for information.
In general, however, it is advisable to make the transformation to the Oracle Database 10g JPublisher functionality, which insulates your user code from implementation details of JPublisher-generated classes. |
Following are the changes to make in order to use your code in Oracle9i or Oracle Database 10g:
Replace any use of the declared _ctx connection context field with use of the provided getConnectionContext() method. The _ctx field is no longer supported.
Replace the explicit implementation of the create() method with a call to a superclass create() method, and use ORAData instead of CustomDatum as the return type.
Assume that in the example that follows, UserClass extends BaseClass. Instead of writing the following method in UserClass:
public CustomDatum create(Datum d, int sqlType) throws SQLException
{
if (d == null) return null;
UserClass o = new UserClass();
o._struct = new MutableStruct((STRUCT) d, _sqlType, _factory);
o._ctx = new _Ctx(((STRUCT) d).getConnection());
return o;
}
Supply the following:
public ORAData create(Datum d, int sqlType) throws SQLException
{
return create(new UserClass(),d,sqlType);
}
Alternatively, if the class is part of an inheritance hierarchy, instead write the following:
protected ORAData createExact(Datum d, int sqlType) throws SQLException
{
return create(new UserClass(),d,sqlType);
}
In addition to the getConnectionContext() method, JPublisher provides a getConnection() method that can be used to obtain the JDBC connection instance associated with the object.
JPublisher supports settings for backward compatibility modes, through the -compatible option. (See "Backward Compatibility Option".) At the most elementary, this includes a setting to explicitly generate .sqlj files, which by default are transparent to users in Oracle Database 10g. There are also Oracle9i and Oracle8i compatibility modes, involving differences in the generated code itself as well as the creation of visible .sqlj files. The following topics are discussed:
In Oracle Database 10g, if you want to avoid automatic SQLJ translation so that JPublisher generates .sqlj files that you can work with directly (as in Oracle8i and Oracle9i releases), you can use the JPublisher setting -compatible=sqlj.
|
Note: In Oracle Database 10g, you do not have to invoke the SQLJ translator directly to explicitly translate.sqlj files. You can use the JPublisher -sqlj option instead. See "Option to Access SQLJ Functionality". |
The JPublisher option setting -compatible=9i results in what is called Oracle9i compatibility mode. In this mode, JPublisher generates code that is compatible with Oracle9i SQLJ and JDBC releases. Additionally, in this mode, JPublisher typically produces .sqlj files that are visible to the user, as was the case with Oracle9i JPublisher.
JPublisher has the following functionality in Oracle9i compatibility mode:
In SQLJ classes, JPublisher generates a protected constructor with a boolean argument that specifies whether the object must be initialized, as it did in Oracle9i:
protected BaseClass(boolean init) { ... }
This constructor was removed in Oracle Database 10g, as described in "Changes in JPublisher Behavior Between Oracle9i and Oracle Database 10g".
The mapping in Java from SMALLINT reverts from int (the mapping in Oracle Database 10g) to short.
Either the JPublisher setting -compatible=both8i or the setting -compatible=8i results in what is called Oracle8i compatibility mode. In this mode, JPublisher generates code that is compatible with Oracle8i SQLJ and JDBC releases. In addition, in this mode, JPublisher typically produces .sqlj files visible to the user, as was the case with Oracle8i JPublisher.
For use of this mode to be permissible, however, at least one of the following circumstances must hold.
You translate JPublisher-generated .sqlj files with the default SQLJ -codegen=oracle setting.
The JPublisher-generated code executes under JDK 1.2 or higher and uses the SQLJ runtime12.jar library, or executes in the Oracle Database 10g release of the server-side Oracle JVM.
You run JPublisher with the -methods=false or -methods=none setting.
Note the following functionality in Oracle8i compatibility mode:
JPublisher generates code that implements the deprecated CustomDatum and CustomDatumFactory interfaces instead of the ORAData and ORADataFactory interfaces (as with the -compatible=customdatum setting). In addition, if you choose the setting -compatible=both8i, then the generated code also implements the ORAData interface, though not ORADataFactory.
With the -methods=true setting, JPublisher always generates a SQLJ class for a SQL object type, even if the object type does not define any methods (as with -methods=always).
JPublisher generates connection context declarations and connection context instances on every object wrapper class, as follows (as with -context=generated):
#sql static context _Ctx; protected _Ctx _ctx;
JPublisher provides a constructor in the wrapper class that takes a generic ConnectionContext instance (an instance of any class implementing the standard sqlj.runtime.ConnectionContext interface) as input. In Oracle Database 10g, the constructor accepts only a DefaultContext instance or an instance of the class specified through the -context option when JPublisher was run.
JPublisher does not provide an API for releasing a connection context instance that has been created implicitly on a JPublisher object.
By contrast, the JPublisher utility in Oracle Database 10g provides both a setConnectionContext() method for explicitly setting the connection context instance for an object, and a release() method for releasing an implicitly created connection context instance of an object.
If you must choose Oracle8i compatibility mode, it is advisable use the setting -compatible=both8i. This permits your application to work in a middle-tier environment such as Oracle Application Server, in which JDBC connections are obtained through data sources and likely will be wrapped using oracle.jdbc.OracleXxxx interfaces. CustomDatum implementations do not support such wrapped connections.
|
Note: The setting-compatible=both8i requires a JDBC implementation from Oracle9i Release 1 (9.0.1) or higher. |
Oracle8i compatibility mode is now the only way for a connection context instance _ctx to be declared in JPublisher-generated code. No other option setting accomplishes this particular Oracle8i behavior. The _ctx instance may be useful if you have legacy code that depends on it, but otherwise you should obtain connection context instances through the getConnectionContext() method.
The individual option settings detailed in Table 4-1 will produce many of the same results as using Oracle8i compatibility mode, which is described in the preceding section, "Oracle8i Compatibility Mode".
Table 4-1 JPublisher Backward Compatibility Options
| Option Setting | Behavior |
|---|---|
| -context=generated | This setting results in the declaration of an inner class, _Ctx, for SQLJ connection contexts. This is used instead of the default DefaultContext class or user-specified connection context classes. |
| -methods=always | This setting forces generation of SQLJ classes (in contrast to non-SQLJ classes) for all JPublisher-generated classes, whether or not the underlying SQL objects or packages define any methods (stored procedures). |
| -compatible=customdatum | For Oracle-specific wrapper classes, this setting results in JPublisher implementing the deprecated (but still supported) oracle.sql.CustomDatum and CustomDatumFactory interfaces instead of the oracle.sql.ORAData and ORADataFactory interfaces. |
| -dir=. | Setting this option to "." (a period, or "dot") results in generation of output files into a hierarchy under the current directory, as was the default behavior in Oracle8i. |
Refer to the following for detailed descriptions of these options:
|
 Copyright © 1999, 2003 Oracle Corporation All Rights Reserved. |
|