5 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 the Oracle Database.

• Generation of Java interfaces

  By 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 application programming interface (API) from which Web Services Description Language (WSDL) content is to be generated. Prior to Oracle Database 10g, JPublisher could generate classes but not interfaces.

  See Also:

  "Generation of Java Interfaces"

• JPublisher styles and style files

  Style files, along with the related -style option, enable Java-to-Java type mappings that 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 Also:

  "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 Also:

  "REF CURSOR Types and Result Sets Mapping"

• 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. By using the extended functionality of the -sql option, you can publish a specific 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 Also:

  "Features to Filter JPublisher Output"

• Support for calling Java classes in the database

  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 that had to be created manually. This PL/SQL wrapper was also known as a call spec. In Oracle Database 10g release 2 (10.2), Web services call-ins of Java classes are supported in two modes, dynamic invocation mode and PL/SQL wrapper mode.

  See Also:

  "Publishing Server-Side Java Classes Through Native Java Interface" and "Server-Side Java Invocation (Call-in)"

• Support for publishing SQL queries or DML statements

  JPublisher provides the -sqlstatement option to take a particular 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 and always use unique method names instead.

  See Also:

  "Generation of Package Classes and Wrapper Methods"

Support for Web Services Call-Outs from the Database

JPublisher supports Web services call-outs from the Oracle Database. The Web services client code is written in SQL, PL/SQL, or Java and it runs on the database and invokes Web services elsewhere. This support is provided through the -proxywsdl and -httpproxy options. In addition, the -proxyopts and -proxyclasses options may possibly be relevant, but typically do not require any special settings for Web services.

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.

Server-Side Java Invocation (Call-in)

The server-side Java call-in functionality allows JPublisher to publish Java classes in the database for client-side invocation. JPublisher generates Java clients to invoke server-side Java.

In Oracle Database 10g release 1 (10.1), the JPublisher option for server-side call-in is -java. JPublisher generates a Java client that uses the dynamic invocation interface, oracle.jpub.runtime.Client, that is provided in the JPublisher run time, to invoke the oracle.jpub.runtime.Server server-side class, which in turn calls the desired Java stored procedure. The Client and Server interfaces are a part of the JPublisher run time. Only static methods with serializable parameters and return types are supported. Beginning with Oracle Database 10g release 1 (10.1), oracle.jpub.runtime.Server is located in the database.

In Oracle Database 10g release 2 (10.2), for server-side call-ins, JPublisher generates a PL/SQL wrapper for the stored procedure and the Java client that calls this PL/SQL wrapper. It supports both static and instance methods. The parameter and return types supported are primitive types, Java Beans, Serializable objects, and Oracle Java Database Connectivity (JDBC) types, typically those with the package name oracle.sql.

In Oracle Database 10g release 2 (10.2), the -java option is deprecated and the JPublisher option for server-side call-in is -dbjava. However, the -java option is still supported for backward compatibility. When the -compatible option is set to 10.1, -dbjava behaves same as -java.

Publishing a Specified Subset of Functions or Procedures

Extended functionality of the -sql option enables you to publish just a subset of the 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, ...)

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, that is no filtering is done. Then list specific modes or types that you want to exclude each followed by a minus sign (-). For example:

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

-filtermodes=1,out-,inout-

Alternatively, you can start with a 0 to filter everything out. Then list specific modes or types that you want to allow each followed by a plus sign (+). For example:

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

-filtermodes=0,in+,return+

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 -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 (_).

JPublisher Backward Compatibility

The JPublisher run time 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 run time.

• It can continue to compile against the current release of the JPublisher run time.

If you use an earlier release of the JPublisher run time and the Oracle JDBC drivers in generating code, then you can compile the code against that version of the JPublisher run time. 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 Oracle Database 10g Release 1 and Release 2

In Oracle Database 10g release 2 (10.2), JPublisher adds the following new APIs for Java classes generated for PL/SQL:

• <init>(javax.sql.DataSource)

  A constructor that takes a java.sql.DataSource object as argument

• setDataSource(javax.sql.DataSource)

  A method to set the data source that takes a java.sql.DataSource object as argument

These methods allow the Java wrapper to acquire a JDBC connection from the data source provided as argument.

JPublisher supports the use of SQL URI types that store URLs, referred to as data links. In Oracle Database 10g release 1 (10.1), JPublisher maps the SQL URI type, SYS.URITYPE, and the subtypes, SYS.DBURITYPE, SYS.XDBURITYPE, and SYS.HTTPURITYPE, to java.net.URL. When SQL URI types are used as PL/SQL stored procedures or SQL statement parameter and return types, this mapping works. However, when a SQL URI type is used as an attribute of a SQL type or element of a SQL array type, the mapping raises ClassCastException at run time.

To overcome this issue, in Oracle Database 10g release 2 (10.2), the SQL URI types are mapped to the ORAData subclasses that are generated by JPublisher. This is similar to the mapping used for user-defined SQL object types. You can also force JPublisher to map a SQL URI type to java.net.URL by specifying the following:

-adddefaulttypemap=
SYS.URITYPE:java.net.URL:VARCHAR2:SYS.URIFACTORY.GETURI:SYS.SQLJUTL.URI2VCHAR
-adddefaulttypemap=
SYS.DBURITYPE:java.net.URL:VARCHAR2:SYS.DBURITYPE.CREATEURI:SYS.SQLJUTL.URI2VCHAR
-adddefaulttypemap=
SYS.XDBURITYPE:java.net.URL:VARCHAR2:SYS.XDBURITYPE.CREATEURI:SYS.SQLJUTL.URI2VCHAR
-adddefaulttypemap=
SYS.HTTPURITYPE:java.net.URL:VARCHAR2:SYS.HTTPURITYPE.CREATEURI:SYS.SQLJUTL.URI2VCHAR

This includes the specification of data conversion functions.

Changes in JPublisher Behavior Between Oracle9i Database and Oracle Database 10g

Regarding backward compatibility, a key difference in JPublisher behavior between Oracle9i Database and Oracle Database 10g is that now, by default, SQLJ source code is translated automatically and the .sqlj source files are invisible to the user.

In addition, note the following changes in JPublisher behavior in Oracle Database 10g:

• In Oracle9i Database, JPublisher generates SQLJ classes with a protected constructor with a boolean argument to specify whether the object must be initialized. For example:

  protected BaseClass(boolean init) { ... }
  
  

  This constructor is removed in Oracle Database 10g, because it conflicts with the constructor generation for a SQL object type with BOOLEAN attributes.

• In Oracle Database 10g, SMALLINT is mapped to int instead of short in Java.

Changes in JPublisher Behavior Between Oracle8i Database and Oracle9i Database

Note the following changes in JPublisher behavior, beginning with Oracle9i Database:

• By default, JPublisher does not declare the inner SQLJ connection context class _Ctx for every object type. Instead, it uses the sqlj.runtime.ref.DefaultContext connection context class 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 Also:

  "Connection Contexts and Instances in SQLJ Classes"

• Even with the -methods=true setting, non-SQLJ classes are generated if the underlying SQL object type or PL/SQL package does not define any methods. However, 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.

Changes in User-Written Subclasses of JPublisher-Generated Classes

If you provided user-written subclasses for classes generated by an Oracle8i version of JPublisher, then you need to be aware that several relevant changes were introduced in Oracle9i Database related to JPublisher code generation. You must make changes in any applications that have Oracle8i functionality if you want to use them in Oracle9i Database or Oracle Database 10g.

You need to make the following changes to use your code in Oracle9i Database 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.

  In the example that follows, assume that 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, then 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. At the most elementary level, this includes a setting to explicitly generate .sqlj files, which are transparent to users in Oracle Database 10g by default. 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