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.

---