4 Additional Features and Considerations

Summary of Support for Web Services Call-Ins to the Database

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.

  See "JPublisher Generation of Java 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
  
  

  See "JPublisher Styles and Style Files".

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

  See "Mapping of REF CURSOR Types and Result Sets".

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

  See "Features to Filter JPublisher Output".

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

  See "Publishing Server-Side Java Classes".

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

  See "Publishing SQL Queries or DML Statements".

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

Support for Web Services Call-Outs from the Database

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.

Publishing a Specified Subset of Functions or Procedures

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.

Publishing Functions or Procedures According to Parameter Modes or Types

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.

Ensuring that Generated Methods Adhere to the JavaBeans Specification

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.

JPublisher Backward Compatibility

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.

Changes in JPublisher Behavior Between Oracle9i and Oracle Database 10g

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.

Changes in JPublisher Behavior Between Oracle8i and Oracle9i

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.

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 Backward Compatibility Modes and Settings

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:

• Explicit Generation of .sqlj Files

• Oracle9i Compatibility Mode

• Oracle8i Compatibility Mode

• Individual Settings to Force Oracle8i JPublisher Behavior