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

## Using JPublisher to Create Custom Object Classes

A convenient way to create custom object classes, as well as other kinds of custom Java classes, is to use the Oracle JPublisher utility. It generates a full definition for a custom Java class, which you can instantiate to hold the data from an Oracle object. JPublisher-generated classes include methods to convert data from SQL to Java and from Java to SQL, as well as getter and setter methods for the object attributes.

This section offers a brief overview. For more information, see the Oracle8i JPublisher User's Guide.

### JPublisher Functionality

You can direct JPublisher to create custom object classes that implement either the `SQLData` interface or the `CustomDatum` interface, according to how you set the JPublisher type mappings.

If you use the `CustomDatum` interface, JPublisher will also create a custom reference class to map to object references for the Oracle object type. If you use the `SQLData` interface, JPublisher will not produce a custom reference class; you would use standard `java.sql.Ref` instances instead.

If you want additional functionality, you can subclass the custom object class and add features as desired. When you run JPublisher, there is a command-line option for specifying both a generated class name and the name of the subclass you will implement. For the SQL-Java mapping to work properly, JPublisher must know the subclass name, which is incorporated into some of the functionality of the generated class.

Note: Hand-editing the JPublisher-generated class, instead of subclassing it, is not recommended. If you hand-edit this class and later have to re-run JPublisher for some reason, you would have to re-implement your changes.

### JPublisher Type Mappings

JPublisher offers various choices for how to map user-defined types and their attribute types between SQL and Java. The rest of this section lists categories of SQL types and the mapping options available for each category.

For general information about SQL-Java type mappings, see "Datatype Mappings".

For more information about JPublisher features or options, see the Oracle8i JPublisher User's Guide.

#### Categories of SQL Types

JPublisher categorizes SQL types into the following groups, with corresponding JPublisher options as noted:

- user-defined types (UDT)--Oracle objects, references, and collections

  Use the JPublisher `-usertypes` option to specify the type-mapping implementation for UDTs--either a standard `SQLData` implementation or an Oracle-specific `CustomDatum` implementation.

- numeric types--anything stored in the database as SQL type `NUMBER`

  Use the JPublisher `-numbertypes` option to specify type-mapping for numeric types.

- LOB types--SQL types `BLOB` and `CLOB`

  Use the JPublisher `-lobtypes` option to specify type-mapping for LOB types.

- built-in types--anything stored in the database as a SQL type not covered by the preceding categories; for example: `CHAR`, `VARCHAR2`, `LONG`, and `RAW`

  Use the JPublisher `-builtintypes` option to specify type-mapping for built-in types.

#### Type-Mapping Modes

JPublisher defines the following type-mapping modes, two of which apply to numeric types only:

- JDBC mapping (setting `jdbc`)--Uses standard default mappings between SQL types and Java native types. For a custom object class, uses a `SQLData` implementation.

- Oracle mapping (setting `oracle`)--Uses corresponding `oracle.sql` types to map to SQL types. For a custom object, reference, or collection class, uses a `CustomDatum` implementation.

- object-JDBC mapping (for numeric types only) (setting `objectjdbc`)--This is an extension of JDBC mapping. Where relevant, object-JDBC mapping uses numeric object types from the standard `java.lang` package (such as `java.lang.Integer`, `Float`, and `Double`), instead of primitive Java types (such as `int`, `float`, and `double`). The `java.lang` types are nullable, while the primitive types are not.

- `BigDecimal` mapping (for numeric types only) (setting `bigdecimal`)--Uses `java.math.BigDecimal` to map to all numeric attributes; appropriate if you are dealing with large numbers but do not want to map to the `oracle.sql.NUMBER` class.

  Note: Using `BigDecimal` mapping can significantly degrade performance.

#### Mapping the SQL Object Type to Java

Use the JPublisher `-usertypes` option to determine how JPublisher will implement the custom Java class that corresponds to a SQL object type:

- A setting of `-usertypes=oracle` (the default setting) instructs JPublisher to create a `CustomDatum` implementation for the custom object class.

  This will also result in JPublisher producing a `CustomDatum` implementation for the corresponding custom reference class.

- A setting of `-usertypes=jdbc` instructs JPublisher to create a `SQLData` implementation for the custom object class. No custom reference class can be created--you must use `java.sql.Ref` or `oracle.sql.REF` for the reference type.

The next section discusses type mapping options that you can use for object attributes.

Note: You can also use JPublisher with a `-usertypes=oracle` setting in creating `CustomDatum` implementations to map SQL collection types. The `-usertypes=jdbc` setting is not valid for mapping SQL collection types. (The `SQLData` interface is intended only for mapping SQL object types.)

#### Mapping Attribute Types to Java

If you do not specify mappings for the attribute types of the SQL object type, JPublisher uses the following defaults:

- For numeric attribute types, the default mapping is object-JDBC.

- For LOB attribute types, the default mapping is Oracle.

- For built-in type attribute types, the default mapping is JDBC.

If you want alternate mappings, use the `-numbertypes`, `-lobtypes`, and `-builtintypes` options as necessary, depending on the attribute types you have and the mappings you desire.

If an attribute type is itself a SQL object type, it will be mapped according to the `-usertypes` setting.

Important: Be especially aware that if you specify a `SQLData` implementation for the custom object class and want the code to be portable, you must be sure to use portable mappings for the attribute types. The defaults for numeric types and built-in types are portable, but for LOB types you must specify `-lobtypes=jdbc`.

#### Summary of SQL Type Categories and Mapping Settings

Table 8-1 summarizes JPublisher categories for SQL types, the mapping settings relevant for each category, and the default settings.

##### Table 8-1 JPublisher SQL Type Categories, Supported Settings, and Defaults

SQL Type Category | JPublisher Mapping Option | Mapping Settings | Default
--- | --- | --- | ---
UDT types | -usertypes | oracle, jdbc | oracle
numeric types | -numbertypes | oracle, jdbc, objectjdbc, bigdecimal | objectjdbc
LOB types | -lobtypes | oracle, jdbc | oracle
built-in types | -builtintypes | oracle, jdbc | jdbc

Note: The JPublisher `-mapping` option used in previous releases will be deprecated but is currently still supported. For information about how JPublisher converts -mapping option settings to settings for the new mapping options, see the Oracle8i JPublisher User's Guide

.

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