3 Generated Classes and Interfaces

Passing Output Parameters in Arrays

The simplest way to solve the problem of returning output values in Java is to pass an OUT or IN OUT parameter to the wrapper method in a single-element array. Think of the array as a "container" that holds the parameter. This mechanism works as follows:

• You assign the "before" value of the parameter to element [0] of an array.

• You pass the array to your wrapper method.

• The wrapper method assigns the "after" value of the parameter to element [0] of the array.

• After executing the method, you extract the "after" value from the array.

A setting of -outarguments=array (the default) instructs JPublisher to use this single-element array mechanism to publish any OUT or IN OUT argument.

Here is an example:

Person [] pa = {p}; 
x.f(pa); 
p = pa[0]; 

Assume that x is an instance of a JPublisher-generated class that has the method f(), which is a wrapper method for a stored procedure that uses a SQL PERSON object as an IN OUT parameter. The type PERSON maps to the Java class Person; p is a Person instance; and pa[] is a single-element Person array.

The array technique for passing OUT or IN OUT parameters requires you to add a few extra lines of code to your program for each parameter.

As another example, consider the PL/SQL function created by the following SQL*Plus command:

SQL> create or replace function g (a0 number, a1 out number, a2 in out number,
     a3 clob, a4 out clob, a5 in out clob) return clob is begin return null; end;

With -outarguments=array, this is published as follows:

public oracle.sql.CLOB g (
     java.math.BigDecimal a0,
     java.math.BigDecimal a1[],
     java.math.BigDecimal a2[],
     oracle.sql.CLOB a3,
     oracle.sql.CLOB a4[],
     oracle.sql.CLOB a5[])

Problems similar to those described earlier arise when the this object of an instance method is modified.

The this object is an additional parameter, passed in a different way. Its mode, as declared in the CREATE TYPE statement, may be IN or IN OUT. If you do not explicitly declare the mode of this, its mode is IN OUT if the stored procedure does not return a result, or IN if it does.

If the mode of the this object is IN OUT, then the wrapper method must return the new value of this. The code generated by JPublisher implements this functionality in different ways, depending on the situation:

• For a stored procedure that does not return a result, the new value of this is returned as the result of the wrapper method.

  As an example, assume that the SQL object type MYTYPE has the following member procedure:

  MEMBER PROCEDURE f1(y IN OUT INTEGER);
  
  

  Also assume that JPublisher generates a corresponding Java class, MyJavaType. This class defines the following method:

  MyJavaType f1(int[] y)
  
  

  The f1() method returns the modified this object value as a MyJavaType instance.

• For a stored function (a stored procedure that returns a result), the wrapper method returns the result of the stored function as its result. The new value of this is returned in a single-element array, passed as an extra argument (the last argument) to the wrapper method.

  Assume that the SQL object type MYTYPE has the following member function:

  MEMBER FUNCTION f2(x IN INTEGER) RETURNS VARCHAR2;
  
  

  Then the corresponding Java class, MyJavaType, defines the following method:

  String f2(int x, MyJavaType[] newValue)
  
  

  The f2() method returns the VARCHAR2 function-return as a Java string, and returns the modified this object value as an array element in the MyJavaType array.

Passing Output Parameters in JAX-RPC Holders

The JAX-RPC specification explicitly specifies holder classes in the javax.xml.rpc.holders package for the Java mapping of simple XML data types and other types. Typically, "Holder" is appended to the type name for the holder class name. For example, BigDecimalHolder is the holder class for BigDecimal.

Given a setting of -outarguments=holder, JPublisher uses holder instances to publish OUT and IN OUT arguments from stored procedures. Holder settings are specified in a JPublisher style file, in the HOLDER subtag inside the TARGETTYPE section for the appropriate mapping. If no holder class is specified, then JPublisher chooses one according to defaults. See "JPublisher Styles and Style Files" for details about style files.

For general information about JAX-RPC and holders, see the Java API for XML-based RPC, JAX-RPC 1.0 specification, available at the following location:

http://jcp.org/aboutJava/communityprocess/final/jsr101/index.html

As an example, again consider the PL/SQL function created by the following SQL*Plus command:

SQL> create or replace function g (a0 number, a1 out number, a2 in out number,
a3 clob, a4 out clob, a5 in out clob) return clob is begin return null; end;

With -outarguments=holder, the following is an example of how the function is published. In this case, there is an extra level of abstraction—because oracle.sql.CLOB is not supported by Web services, it is mapped to String, the JAX-RPC holder class for which is StringHolder.Assume the following JPublisher command to publish the function g. (The webservices10 style file contains an entry for -outarguments=holder.)

% jpub -u scott/tiger  -s toplevel"(g)":ToplevelG -style=webservices10

Here is the published interface:

public java.lang.String g
              (java.math.BigDecimal a0,
               javax.xml.rpc.holders.BigDecimalHolder _xa1_out_x,
               javax.xml.rpc.holders.BigDecimalHolder _xa2_inout_x,
               java.lang.String a3,
               javax.xml.rpc.holders.StringHolder _xa4_out_x,
               javax.xml.rpc.holders.StringHolder _xa5_inout_x)
throws java.rmi.RemoteException;

Passing Output Parameters in Function Returns

You can use the setting -outarguments=return as a workaround for supporting method signatures in Web services that do not use JAX-RPC holder types or arrays. In a situation in which there is no support for JAX-RPC holders, the -outarguments=return setting allows OUT or IN OUT data to be returned in function results.

Once again, consider the PL/SQL function created by the following SQL*Plus command:

SQL> create or replace function g (a0 number, a1 out number, a2 in out number,
a3 clob, a4 out clob, a5 in out clob) return clob is begin return null; end;

Assume the following JPublisher command (a wraparound command, with output also shown) to publish the function g. Although the webservices10 style file specifies -outarguments=holder, the -outarguments=return setting comes after the -style setting so takes precedence.

% jpub -u scott/tiger  -s toplevel"(g)":ToplevelG -style=webservices10
       -outarguments=return
SCOTT.top_level_scope
ToplevelGUser_g_Out

The JPublisher output acknowledges that it is processing the SCOTT top level, and also indicates the creation of the Java class ToplevelGUser_g_Out to support output values of the function g through return data.

JPublisher generates the following interface to take input parameters and return output parameters:

public ToplevelGUser_g_Out g
            (java.math.BigDecimal a0,
             java.math.BigDecimal xxa2_inoutxx,
             java.lang.String a3,
             java.lang.String xxa5_inoutxx)
throws java.rmi.RemoteException;

JPublisher generates the TopLevelGUser_g_Out class as follows:

public class ToplevelGUser_g_Out{
  public ToplevelGUser_g_Out() { }
  public java.math.BigDecimal getA1Out()  { return a1_out; }
  public void setA1Out(java.math.BigDecimal a1_out) { this.a1_out = a1_out; }
  public java.math.BigDecimal getA2Inout()   { return a2_inout; }
  public void setA2Inout(java.math.BigDecimal a2_inout) 
                          { this.a2_inout = a2_inout; }
  public java.lang.String getA4Out()   { return a4_out; }}

The return type ToplevelGUser_g_Out encapsulates the values of the OUT and IN OUT parameters to be passed back to the caller of the function. As in the preceding section, oracle.sql.CLOB is mapped to String by the webservices10 style file.

Important Notes About Generation of SQLJ Classes

Note the following for JPublisher-generated SQLJ classes:

• If you are generating Java wrapper classes for a SQL type hierarchy, and any one (or more) of the types contains stored procedures, then by default JPublisher generates SQLJ classes for all the SQL types, not just the types that have stored procedures. (But you have the option of explicitly suppressing the generation of SQLJ classes through the JPublisher -methods=false setting. This results in all non-SQLJ classes.)

• Classes produced by JPublisher include a release() method. If an instance of a JPublisher-generated wrapper class implicitly constructs a DefaultContext instance, then you should use the release() method to release this connection context instance when it is no longer needed. You can avoid this scenario, however, by adhering to at least one of the following suggestions in creating and using the wrapper class instance:

  • Construct the wrapper class instance with an explicitly provided SQLJ connection context.

  • Explicitly associate the wrapper class instance with a SQLJ connection context instance through the setConnectionContext() method.

  • Implicitly use the static SQLJ default connection context instance for the wrapper class instance. This occurs if you do not supply any connection information.

  See "More About Connection Contexts and Instances in SQLJ Classes" for additional information.

• In Oracle8i compatibility mode, instead of the constructor taking a DefaultContext instance or user-specified-class instance, there is a constructor that simply takes a ConnectionContext instance. This could be an instance of any class that implements the standard sqlj.runtime.ConnectionContext interface, including the DefaultContext class.

Use of SQLJ Classes That JPublisher Generates for PL/SQL Packages

Take the following steps to use a class that JPublisher generates for a PL/SQL package:

1. Construct an instance of the class.

2. Call the wrapper methods of the class.

The constructors for the class associate a database connection with an instance of the class. One constructor takes a SQLJ DefaultContext instance (or an instance of a class specified through the -context option when you ran JPublisher); one constructor takes a JDBC Connection instance; one constructor has no arguments. Calling the no-argument constructor is equivalent to passing the SQLJ default context to the constructor that takes a DefaultContext instance. JPublisher provides the constructor that takes a Connection instance for the convenience of JDBC programmers unfamiliar with SQLJ concepts such as connection contexts and the default context.

The wrapper methods are all instance methods, because the connection context in the this object is used in the wrapper methods.

Because a class generated for a PL/SQL package has no instance data other than the connection context, you will typically construct one class instance for each connection context that you use. If the default context is the only one you use, then you can call the no-argument constructor once.

An instance of a class generated for a PL/SQL package does not contain copies of PL/SQL package variables. It is not an ORAData class or a SQLData class, and you cannot use it as a host variable.

Use of SQLJ Classes That JPublisher Generates for Object Types

To use an instance of a Java class that JPublisher generates for a SQL object type or a SQL OPAQUE type, you must first initialize the Java object. You can accomplish this in one of the following ways:

• Assign an already initialized Java object to your Java object.

• Retrieve a copy of a SQL object into your Java object. You can do this by using the SQL object as an OUT argument or as the function return of a JPublisher-generated wrapper method, or by retrieving the SQL object through JDBC calls that you write (or through SQLJ #sql statements, if you are in a backward compatibility mode and using SQLJ source files directly).

• Construct the Java object with the no-argument constructor and set its attributes using the setXXX() methods, or construct the Java object with the constructor that accepts values for all the object attributes. Typically, you will subsequently use the setConnection() or setConnectionContext() method to associate the object with a database connection before invoking any of its wrapper methods. If you do not explicitly associate the object with a JDBC or SQLJ connection before invoking a method on it, then it becomes implicitly associated with the SQLJ default context.

  Other constructors for the class associate a connection with the class instance. One constructor takes a DefaultContext instance (or an instance of a class specified through the -context option when you ran JPublisher), and one constructor takes a Connection instance. The constructor that takes a Connection instance is provided for the convenience of JDBC programmers unfamiliar with SQLJ concepts such as connection contexts and the default context.

Once you have initialized your Java object, you can do the following:

• Call the accessor methods of the object.

• Call the wrapper methods of the object.

• Pass the object to other wrapper methods.

• Use the object as a host variable in JDBC calls (or in SQLJ #sql statements if you are in a backward compatibility mode and using SQLJ source files directly).

There is a Java attribute for each attribute of the corresponding SQL object type, with getXXX() and setXXX() accessor methods for each attribute. The accessor method names are of the form getFoo() and setFoo() for attribute foo. JPublisher does not generate fields for the attributes.

By default, the class includes wrapper methods that invoke the associated Oracle object methods (stored procedures) executing in the server. The wrapper methods are all instance methods, whether or not the server methods are. The DefaultContext in the this object is used in the wrapper methods.

With Oracle mapping, JPublisher generates the following methods for the Oracle JDBC driver to use. These methods are specified in the ORAData and ORADataFactory interfaces:

• create()

• toDatum()

These methods are not generally intended for your direct use. In addition, JPublisher generates the methods setFrom(otherObject), setValueFrom(otherObject), and setContextFrom(otherObject) that you can use to copy the value or connection information from one object instance to another.

More About Connection Contexts and Instances in SQLJ Classes

The class that JPublisher uses in creating SQLJ connection context instances depends on how you set the -context option when you run JPublisher, as follows:

• A setting of -context=DefaultContext (the default) results in JPublisher using instances of the standard sqlj.runtime.ref.DefaultContext class.

• A setting of a user-defined class that is in the classpath and that implements the standard sqlj.runtime.ConnectionContext interface results in JPublisher using instances of that class.

• A setting of -context=generated results in declaration of the static connection context class _Ctx in the JPublisher-generated class. JPublisher uses instances of this class for connection context instances. This is appropriate for Oracle8i compatibility mode, but generally not recommended otherwise.

See "SQLJ Connection Context Classes (-context)" for more information about the -context option.

Consider the following points in using SQLJ connection context instances or JDBC connection instances in instances of JPublisher-generated wrapper classes:

• Wrapper classes generated by JPublisher provide a setConnectionContext() method that you can use to explicitly specify a SQLJ connection context instance. (This is not necessary if you have already specified a connection context instance through the constructor.)

  This method is defined as follows:

  void setConnectionContext(conn_ctxt_instance);
  
  

  This installs the passed connection context instance as the SQLJ connection context in the wrapper class instance. The connection context instance must be an instance of the class specified through the -context setting for JPublisher connection contexts (typically DefaultContext).

  Note that the underlying JDBC connection must be compatible with the connection used to materialize the database object in the first place. Specifically, some objects may have attributes, such as object reference types or BLOBs, that are valid only for a particular connection.

• Use either of the following methods of a wrapper class instance, as appropriate, to retrieve a connection or connection context instance.

  • Connection getConnection()

  • ConnCtxtType getConnectionContext()

  The getConnectionContext() method returns an instance of the connection context class specified through the JPublisher -context setting (typically DefaultContext).

  The returned connection context instance may be either an explicitly set instance or one that was created implicitly by JPublisher.

• If no connection context instance is explicitly set for a JPublisher-generated SQLJ class, then one will be created implicitly from the JDBC connection instance when the getConnectionContext() method is called.

  In this circumstance, at the conclusion of processing, use the release() method to free resources in the SQLJ runtime. This prevents a possible memory leak.

The setFrom(), setValueFrom(), and setContextFrom() Methods

JPublisher provides the following utility methods in generated SQLJ classes:

• setFrom(anotherObject)

  This method initializes the calling object from another object of the same base type, including connection and connection context information. An existing, implicitly created connection context object on the calling object is freed.

• setValueFrom(anotherObject)

  This method initializes the underlying field values of the calling object from another object of the same base type. This method does not transfer connection or connection context information.

• setContextFrom(anotherObject)

  This method initializes the connection and connection context information on the calling object from the connection setting of another object of the same base type. An existing, implicitly created, connection context object on the calling object is freed. This method does not transfer any information related to the object value.

Note that there is semantic equivalence between the following:

x.setFrom(y);

and:

x.setValueFrom(y); 
x.setContextFrom(y);

Extending JPublisher-Generated Classes

Suppose you want JPublisher to generate the class JAddress from the SQL object type ADDRESS. You also want to write a class, MyAddress, to represent ADDRESS objects, where MyAddress extends the functionality that JAddress provides.

Under this scenario, you can use JPublisher to generate both a base Java class, JAddress, and an initial version of a subclass, MyAddress, to which you can add the desired functionality. You then use JPublisher to map ADDRESS objects to the MyAddress class instead of the JAddress class.

To do this, JPublisher must alter the code it generates in the following ways:

• It generates the reference class MyAddressRef rather than JAddressRef.

• It uses the MyAddress class instead of the JAddress class to represent attributes whose SQL type is ADDRESS, or to represent VARRAY and nested table elements whose SQL type is ADDRESS.

• It uses the MyAddress factory instead of the JAddress factory when the ORADataFactory interface is used to construct Java objects whose SQL type is ADDRESS.

• It generates or regenerates the code for the JAddress class. In addition, it generates an initial version of the code for the MyAddress class, which you can then modify to insert your own additional functionality. If the source file for the MyAddress class already exists, however, it is left untouched by JPublisher.

-sql=object_type:generated_base_class:map_class

-sql=ADDRESS:JAddress:MyAddress

SQL ADDRESS GENERATE JAddress AS MyAddress

JPublisher-Generated Subclasses for Java-to-Java Type Transformations

JPublisher style files, described in "JPublisher Styles and Style Files", enable you to specify Java-to-Java type mappings. A typical use for such mappings is to ensure that generated classes can be used in Web services. As a particular example, CLOB types such as java.sql.Clob and oracle.sql.CLOB cannot be used in Web services. However, the data can be used if converted to a type, such as java.lang.String, that is supported by Web services.

If you use the JPublisher -style option to specify a style file, JPublisher generates subclasses that implement the Java-to-Java type mappings specified in the style file. This includes the use of "holder" classes, introduced in "Passing Output Parameters in JAX-RPC Holders", for handling output arguments—data corresponding to PL/SQL OUT or IN OUT types.

For example, consider the following PL/SQL package, foo_pack, consisting of the stored function foo:

create or replace package foo_pack as 
   function foo(a IN OUT sys.xmltype, b integer) return CLOB; 
end; 
/

Assume that you translate the foo_pack package as follows:

% jpub -u scott/tiger -s foo_pack:FooPack -style=webservices10

This command uses the style file webservices10.properties for Java-to-Java type mappings. (This style file is supplied by Oracle and is typically appropriate for using Web services in an Oracle Database 10g environment.) The webservices10.properties file specifies the following (among other things):

• The mapping of the Java type oracle.sql.SimpleXMLType (which is not supported by Web services) to the Java type javax.xml.transform.Source (which is):

  SOURCETYPE oracle.sql.SimpleXMLType
  TARGETTYPE javax.xml.transform.Source
  ...
  
  

• The use of holder classes for PL/SQL OUT and IN OUT arguments:

  jpub.outarguments=holder
  
  

  This setting directs JPublisher to use instances of the appropriate holder class, in this case javax.xml.rpc.holders.SourceHolder, for the PL/SQL output argument of type XMLTYPE.

• The inclusion of webservices-common.properties:

  INCLUDE webservices-common
  
  

The webservices-common.properties file (also supplied by Oracle) specifies the following:

• The mapping of SYS.XMLTYPE to oracle.sql.SimpleXMLType in the JPublisher default type map:

  jpub.adddefaulttypemap=SYS.XMLTYPE:oracle.sql.SimpleXMLType
  
  

• A code generation naming pattern:

  jpub.genpattern=%2Base:%2User#%2
  
  

  Based on the "-s foo_pack:FooPack" specification to JPublisher, the genpattern setting results in generation of the interface FooPack, the base class FooPackBase, and the user subclass FooPackUser, which extends FooPackBase and implements FooPack. See "Class and Interface Naming Pattern (-genpattern)" for general information about the -genpattern option.

• The mapping of the Java type oracle.sql.CLOB (which is not supported by Web services) to the Java type java.lang.String (which is):

  SOURCETYPE oracle.sql.CLOB
  TARGETTYPE java.lang.String
  ...
  
  

Recall the calling sequence for the foo stored function:

function foo(a IN OUT sys.xmltype, b integer) return CLOB;

The base class generated by JPublisher, FooPackBase, has the following corresponding method declaration:

public oracle.sql.CLOB _foo (oracle.sql.SimpleXMLType a[], Integer b);

The base class uses an array to support the output argument. (See "Passing Output Parameters in Arrays".)

The user subclass has the following corresponding method declaration:

public java.lang.String foo (SourceHolder _xa_inout_x, Integer b);

This is because of the specified mapping of oracle.sql.SimpleXMLType to javax.xml.transform.Source, the specified use of holder classes for output arguments, and the specified mapping of oracle.sql.CLOB to java.lang.String (all as described earlier).

Following is the class SourceHolder, the holder class for Source:

// Holder class for javax.xml.transform.Source 
public class SourceHolder implements javax.xml.rpc.holders.Holder 
{ 
   public javax.xml.transform.Source value; 
   public SourceHolder() { } 
   public SourceHolder(javax.xml.transform.Source value) 
   { this.value = value; } 
}

Generated user subclasses employ the following general functionality for Java-to-Java type transformations in the wrapper method:

User subclass method 
{
     Enter Holder layer (extract IN data from the holder) 
          Enter Java-to-Java mapping layer (from target to source) 
               Call base class method (uses JDBC to invoke wrapped procedure) 
          Exit Java-to-Java mapping layer (from source to target) 
     Exit Holder layer (update the holder)
}

For the example, this is as follows in the foo() method of the class FooPackUser:

foo (SourceHolder, Integer)
{
     SourceHolder -> Source 
          Source -> SimpleXMLType 
               _foo (SimpleXMLType[], Integer); 
          SimpleXMLType -> Source 
     Source -> SourceHolder
}

The holder layer retrieves and assigns the holder instance.

In the example, the holder layer in foo() performs the following:

1. It retrieves a Source object from the SourceHolder object that is passed in to the foo() method (data input).

2. After processing (which occurs inside the type conversion layer), it assigns the SourceHolder object from the Source object that was retrieved and processed (data output).

The type conversion layer first takes the target type (TARGETTYPE from the style file), next converts it to the source type (SOURCETYPE from the style file), then calls the corresponding method in the base class (which uses JDBC to invoke the wrapped stored function), and finally converts the source type returned by the base class method back into the target type to return to the holder layer.

In this example, the type conversion layer in foo() performs the following:

1. It takes the Source object from the holder layer (data input).

2. It converts the Source object to a SimpleXMLType object.

3. It passes the SimpleXMLType object to the _foo() method of the base class, which uses JDBC to invoke the foo stored function.

4. It takes the SimpleXMLType object returned by the _foo() method (output from the foo stored function).

5. It converts the SimpleXMLType object back to a Source object for the holder layer (data output).

ORAData Object Types and Inheritance

Consider the following SQL object types:

CREATE TYPE PERSON AS OBJECT (
...
) NOT FINAL;

CREATE TYPE STUDENT UNDER PERSON (
...
);

CREATE TYPE INSTRUCTOR UNDER PERSON (
...
);

And consider the following JPublisher command line to create corresponding Java classes (a single wraparound command):

% jpub -user=scott/tiger
       -sql=PERSON:Person,STUDENT:Student,INSTRUCTOR:Instructor -usertypes=oracle

In this example, JPublisher generates a Person class, a Student class, and an Instructor class. The Student and Instructor classes extend the Person class, because STUDENT and INSTRUCTOR are subtypes of PERSON.

The class at the root of the inheritance hierarchy, Person in this example, contains the full information for the entire inheritance hierarchy and automatically initializes its type map with the required information. As long as you use JPublisher to generate all the required classes of a class hierarchy together, no additional action is required. The type map of the class hierarchy is appropriately populated.

% jpub -user=scott/tiger -sql=PERSON:Person,STUDENT:Student -usertypes=oracle
% jpub -user=scott/tiger -sql=PERSON:Person,INSTRUCTOR:Instructor
       -usertypes=oracle

new Instructor(); // required
new Student();    // required
new Person();     // optional

Person create(oracle.sql.Datum d, int sqlType)

ORAData Reference Types and Inheritance

This section shows how to convert from one custom reference class to another, and also explains why a custom reference class generated for a subtype by JPublisher does not extend the reference classes of the base type.

StudentRef s_ref = ...;  
PersonRef p_ref = PersonRef.cast(s_ref);

PersonRef pr = ...; 
InstructorRef ir = InstructorRef.cast(pr);

CREATE TYPE PERSON AS OBJECT (
...
) NOT FINAL;

CREATE TYPE STUDENT UNDER PERSON (
...
);

% jpub -user=scott/tiger -sql=PERSON:Person,STUDENT:Student -usertypes=oracle

java.sql.Connection conn = ...;  // get underlying JDBC connection
XxxxRef xref = ...;
YyyyRef yref = (YyyyRef) YyyyRef.getORADataFactory().
                create(xref.toDatum(conn), Oracle.jdbc.OracleTypes.REF);

create type person_t as object (ssn number, name varchar2 (30), dob date) not
final;
/
show errors

create type instructor_t under person_t (title varchar2(20)) not final;
/
show errors

create type instructorPartTime_t under instructor_t (num_hours number);
/
show errors

create type student_t under person_t (deptid number, major varchar2(30)) not
final;
/
show errors

create type graduate_t under student_t (advisor instructor_t);
/
show errors

create type studentPartTime_t under student_t (num_hours number);
/
show errors

create table person_tab  of person_t;

insert into person_tab values (1001, 'Larry', TO_DATE('11-SEP-60'));
insert into person_tab values (instructor_t(1101, 'Smith', TO_DATE
('09-OCT-1940'), 'Professor'));
insert into person_tab values (instructorPartTime_t(1111, 'Myers',
TO_DATE('10-OCT-65'), 'Adjunct Professor', 20));
insert into person_tab values (student_t(1201, 'John', To_DATE('01-OCT-78'), 11,
'EE'));
insert into person_tab values (graduate_t(1211, 'Lisa', TO_DATE('10-OCT-75'),
12, 'ICS', instructor_t(1101, 'Smith', TO_DATE ('09-OCT-40'), 'Professor')));
insert into person_tab values (studentPartTime_t(1221, 'Dave',
TO_DATE('11-OCT-70'), 13, 'MATH', 20));

Person_t:Person,instructor_t:Instructor,instructorPartTime_t:InstructorPartTime,
graduate_t:Graduate,studentPartTime_t:StudentPartTime

import java.sql.*; 
import oracle.jdbc.*; 
import oracle.sql.*; 

public class Inheritance 
{ 
  public static void main(String[] args) throws SQLException 
  { 
    System.out.println("Connecting."); 
    java.sql.DriverManager.registerDriver(new oracle.jdbc.OracleDriver()); 
    oracle.jdbc.OracleConnection conn = 
              (oracle.jdbc.OracleConnection) java.sql.DriverManager.getConnection
              ("jdbc:oracle:oci8:@", "scott", "tiger");
    // The following is only required in 9.0.1 
    // or if the Java class hierarchy was created piecemeal 
    System.out.println("Initializing type system."); 
    new Person(); 
    new Instructor(); 
    new InstructorPartTime(); 
    new StudentT(); 
    new StudentPartTime(); 
    new Graduate(); 
    PersonRef p_ref; 
    InstructorRef i_ref; 
    InstructorPartTimeRef ipt_ref; 
    StudentTRef s_ref; 
    StudentPartTimeRef spt_ref; 
    GraduateRef g_ref; 
    OraclePreparedStatement stmt =
                (OraclePreparedStatement)conn.prepareStatement
                ("select ref(p) FROM PERSON_TAB p WHERE p.NAME=:1"); 
    OracleResultSet rs; 

    System.out.println("Selecting a person."); 
    stmt.setString(1, "Larry"); 
    rs = (OracleResultSet) stmt.executeQuery(); 
    rs.next(); 
    p_ref = (PersonRef) rs.getORAData(1, PersonRef.getORADataFactory()); 
    rs.close(); 

    System.out.println("Selecting an instructor."); 
    stmt.setString(1, "Smith"); 
    rs = (OracleResultSet) stmt.executeQuery(); 
    rs.next(); 
    i_ref = (InstructorRef) rs.getORAData(1, InstructorRef.getORADataFactory()); 
    rs.close(); 

    System.out.println("Selecting a part time instructor."); 
    stmt.setString(1, "Myers"); 
    rs = (OracleResultSet) stmt.executeQuery(); 
    rs.next(); 
    ipt_ref = (InstructorPartTimeRef) rs.getORAData
              (1, InstructorPartTimeRef.getORADataFactory()); 
    rs.close(); 

    System.out.println("Selecting a student."); 
    stmt.setString(1, "John"); 
    rs = (OracleResultSet) stmt.executeQuery(); 
    rs.next(); 
    s_ref = (StudentTRef) rs.getORAData(1, StudentTRef.getORADataFactory()); 
    rs.close(); 

    System.out.println("Selecting a part time student."); 
    stmt.setString(1, "Dave"); 
    rs = (OracleResultSet) stmt.executeQuery(); 
    rs.next(); 
    spt_ref = (StudentPartTimeRef) rs.getORAData
              (1, StudentPartTimeRef.getORADataFactory()); 
    rs.close(); 

    System.out.println("Selecting a graduate student."); 
    stmt.setString(1, "Lisa"); 
    rs = (OracleResultSet) stmt.executeQuery(); 
    rs.next(); 
    g_ref = (GraduateRef) rs.getORAData(1, GraduateRef.getORADataFactory()); 
    rs.close(); 
    stmt.close(); 

    // Assigning a part-time instructor ref to a person ref 
    System.out.println("Assigning a part-time instructor ref to a person ref"); 
    oracle.sql.Datum ref = ipt_ref.toDatum(conn); 
    PersonRef pref = (PersonRef) PersonRef.getORADataFactory(). 
                                           create(ref,OracleTypes.REF); 
    // or just use: PersonRef pref = PersonRef.cast(ipt_ref); 
    // Assigning a person ref to an instructor ref 
    System.out.println("Assigning a person ref to an instructor ref"); 
    InstructorRef iref = (InstructorRef) InstructorRef.getORADataFactory(). 
                                     create(pref.toDatum(conn), OracleTypes.REF); 
    // or just use: InstructorRef iref = InstructorRef.cast(pref); 
    // Assigning a graduate ref to an part time instructor ref. 
    // This should produce an error, demonstrating that refs 
    // are type safe. 
    System.out.println ("Assigning a graduate ref to a part time instructor ref"); 
    InstructorPartTimeRef iptref = 
                (InstructorPartTimeRef) InstructorPartTimeRef.getORADataFactory(). 
                create(g_ref.toDatum(conn), OracleTypes.REF); 
    // or just use: InstructorPartTimeRef iptref = 
    // InstructorPartTimeRef.cast(g_ref); 
    conn.close(); 
  } 
} 

SQLData Object Types and Inheritance

If you use the JPublisher -usertypes=jdbc setting instead of -usertypes=oracle, then the custom Java class generated by JPublisher implements the standard SQLData interface instead of the Oracle ORAData interface. The SQLData standard readSQL() and writeSQL() methods provide equivalent functionality to the ORAData/ORADataFactory create() and toDatum() methods for reading and writing data.

As is the case when JPublisher generates ORAData classes corresponding to a hierarchy of SQL object types, when JPublisher generates SQLData classes corresponding to a SQL hierarchy, the Java types follow the same hierarchy as the SQL types.

SQLData implementations do not, however, offer the implicit mapping intelligence that JPublisher automatically generates in ORAData classes (as described in "ORAData Object Types and Inheritance").

In a SQLData scenario, you must manually provide a type map to ensure the proper mapping between SQL object types and Java types. In a JDBC application, you can properly initialize the default type map for your connection, or you can explicitly provide a type map as a getObject() input parameter. See the Oracle Database JDBC Developer's Guide and Reference for information.

In addition, note that there is no support for strongly typed object references in a SQLData implementation. All object references are weakly typed java.sql.Ref instances.

Effects of Using SQL FINAL, NOT FINAL, NOT INSTANTIABLE

This section discusses the effect on JPublisher-generated wrapper classes of using the SQL modifiers FINAL, NOT FINAL, or NOT INSTANTIABLE.

Using the SQL modifier FINAL or NOT FINAL on a SQL type or on a method of a SQL type has no effect on the generated Java wrapper code. This is so JPublisher users are able in all cases to customize generated Java wrapper classes by extending the classes and overriding the generated behavior.

Using the SQL modifier NOT INSTANTIABLE on a method of a SQL type results in no code being generated for that method in the Java wrapper class. Therefore, to call such a method, you must cast to some wrapper class that corresponds to an instantiable SQL subtype.

Using NOT INSTANTIABLE on a SQL type results in the corresponding wrapper class being generated with protected constructors. This will remind you that instances of that class can be created only through subclasses that correspond to instantiable SQL types.