Oracle8i JDBC Developer's Guide and Reference Release 3 (8.1.7) Part Number A83724-01 |
Library | Service | Contents | Index

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

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index