Custom Collection Classes with JPublisher

This chapter primarily describes the functionality of the oracle.sql.ARRAY class, but it is also possible to access Oracle collections through custom Java classes or, more specifically, custom collection classes.

You can create custom collection classes yourself, but the most convenient way is to use the Oracle JPublisher utility. Custom collection classes generated by JPublisher offer all the functionality described earlier in this chapter, as well as the following advantages (it is also possible to implement such functionality yourself):

• They are strongly typed. This can help you find coding errors during compilation that might not otherwise be discovered until runtime.

• They can be changeable, or mutable. Custom collection classes produced by JPublisher, unlike the ARRAY class, allow you to get and set individual elements using the getElement() and setElement() methods. (This is also something you could implement in a custom collection class yourself.)

A custom collection 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 collection classes.

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

• It must have a means of storing the collection data. Typically it will directly or indirectly include an oracle.sql.ARRAY attribute for this purpose (this is the case with a JPublisher-produced custom collection class).

A JPublisher-generated custom collection class implements CustomDatum and CustomDatumFactory and indirectly includes an oracle.sql.ARRAY attribute. The custom collection class will have an oracle.jpub.runtime.MutableArray attribute. The MutableArray class has an oracle.sql.ARRAY attribute.

Note: When you use JPublisher to create a custom collection class, you must use the CustomDatum implementation. This will be true if JPublisher's -usertypes mapping option is set to oracle, which is the default. You cannot use a SQLData implementation for a custom collection class (that implementation is for custom object classes only). Setting the -usertypes mapping option to jdbc is invalid.

As an example of custom collection classes being strongly typed, if you define an Oracle collection MYVARRAY, then JPublisher can generate a MyVarray custom collection class. Using MyVarray instances, instead of generic oracle.sql.ARRAY instances, makes it easier to catch errors during compilation instead of at runtime--for example, if you accidentally assign some other kind of array into a MyVarray variable.

If you do not use custom collection classes, then you would use standard java.sql.Array instances (or oracle.sql.ARRAY instances) to map to your collections.

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

---