Custom Reference Classes with JPublisher

This chapter primarily describes the functionality of the oracle.sql.REF class, but it is also possible to access Oracle object references through custom Java classes or, more specifically, custom reference classes.

Custom reference classes offer all the functionality described earlier in this chapter, as well as the advantage of being strongly typed. A custom reference class must satisfy three requirements:

• It must implement the oracle.sql.CustomDatum interface described under "Creating and Using Custom Object Classes for Oracle Objects". Note that the standard JDBC SQLData interface, which is an alternative for custom object classes, is not intended for custom reference classes.

• It, or a companion class, must implement the oracle.sql.CustomDatumFactory interface, for creating instances of the custom reference class.

• It must provide a way to refer to the object data. JPublisher accomplishes this by using an oracle.sql.REF attribute.

You can create custom reference classes yourself, but the most convenient way to produce them is through the Oracle JPublisher utility. If you use JPublisher to generate a custom object class to map to an Oracle object, and you specify that JPublisher use a CustomDatum implementation, then JPublisher will also generate a custom reference class that implements CustomDatum and CustomDatumFactory and includes an oracle.sql.REF attribute. (The CustomDatum implementation will be used if JPublisher's -usertypes mapping option is set to oracle, which is the default.)

Custom reference classes are strongly typed. For example, if you define an Oracle object EMPLOYEE, then JPublisher can generate an Employee custom object class and an EmployeeRef custom reference class. Using EmployeeRef instances instead of generic oracle.sql.REF instances makes it easier to catch errors during compilation instead of at runtime--for example, if you accidentally assign some other kind of object reference into an EmployeeRef variable.

Be aware that the standard SQLData interface supports only SQL object mappings. For this reason, if you instruct JPublisher to implement the standard SQLData interface in creating a custom object class, then JPublisher will not generate a custom reference class. In this case your only option is to use standard java.sql.Ref instances (or oracle.sql.REF instances) to map to your object references. (Specifying the SQLData implementation is accomplished by setting JPublisher's UDT attributes mapping option to jdbc.)

For more information about JPublisher, see "Using JPublisher to Create Custom Object Classes", or refer to the Oracle8i JPublisher User's Guide.

---