Customized Type Mapping:JAVA

This chapter describes the support that the JDBC API provides for mapping SQL
structured and distinct types to classes in the Java programming language. Because
the mechanism for this custom mapping is an extension of the existing getObject
and setObject mechanism, it involves minimal extensions to the JDBC API from
the user’s point of view.

The Type Mapping

The SQL user-defined types (UDTs), structured types and DISTINCT types, can be
given a custom mapping to a class in the Java programming language. The default is
for a driver to use the default mappings between SQL data types and types in the
Java programming language. The default mapping for an SQL structured type is to
the interface Struct; the default mapping for an SQL DISTINCT type is to the type
to which the underlying type is mapped. If a custom mapping has been set up for a
UDT, the driver will use the custom mapping instead of the default mapping when
an application calls the getObject or setObject methods on that UDT.
Setting up a custom mapping requires two things:

1. Writing an implementation of the SQLData interface for the UDT. This class
typically maps the attribute(s) of an SQL structured type (or the single attribute of
a DISTINCT type) to fields. There is, however, great latitude allowed in how a
UDT is custom mapped. It is expected that most SQLData implementations will
be created using a tool.
2. Putting an entry in a java.util.Map object. The entry must contain the
following two items:
a. The fully qualified name of the SQL UDT that is to be mapped.


b. The Class object for the SQLData implementation. It is an error if the class
listed in a type map entry does not implement the SQLData interface.
For example, if the UDT is named mySchemaName.AUTHORS and the SQLData
implementation is the class Authors, the entry for the type map associated with the
Connection object conn would look like
CODE EXAMPLE 17-1.

java.util.Map map = conn.getTypeMap();
map.put("mySchemaName.AUTHORS", Class.forName("Authors"));
conn.setTypeMap(map);

CODE EXAMPLE 17-1 Putting an entry in a connection’s type map

The method Connection.getTypeMap returns the type map associated with the
Connection object conn; the method Connection.setTypeMap sets the given
java.util.Map object as the type map for conn.

When an SQL value with a custom mapping is being retrieved (by the method
ResultSet.getObject, CallableStatement.getObject, or any of the other
methods that materialize an SQL value’s data on the client), the driver will check to
see if there is an entry in the connection’s type map for the SQL value that is to be
retrieved. If there is, the driver will map the SQL UDT to the class specified in the
type map. If there is no entry for the UDT in the connection’s type map, the UDT is
mapped to the default mapping.

Certain methods may take a type map as a parameter. A type map supplied as a
parameter supersedes the type map associated with the connection. A UDT that
does not have an entry in the type map supplied as a parameter will be mapped to
the default mapping. When a type map is explicitly supplied to a method, the
connection’s type map is never used.

Class Conventions

A class that appears in a type map entry must do the following:
1. Implement the interface java.sql.SQLData
2. Provide a niladic constructor, that is, a constructor that takes no parameters
The SQLData interface contains methods that convert instances of SQL UDTs to Java
class instances and that convert Java class instances back to SQL UDTs. For example,
the method SQLData.readSQL reads a stream of data values and builds a Java
object, while the method SQLData.writeSQL writes a sequence of values from a
Java object to a stream. These methods will typically be generated by a tool that
understands the database schema.

This stream-based approach for exchanging data between SQL and the Java
programming language is conceptually similar to Java object serialization. The data
are read from and written to an SQL data stream provided by the JDBC driver. The
SQL data stream may be implemented on various network protocols and data
formats. It may be implemented on any logical data representation in which the leaf
SQL data items (of which SQL structured types are composed) can be read from
(written to) the data stream in a "depth-first" traversal of the structured types. That
is, each attribute value, which may itself be a structured type, appears fully (its
structure recursively elaborated) in the stream before the next attribute. In addition,
the attributes of an SQL structured type must appear in the stream in the order in
which they are declared in the type definition. For data of SQL structured types that
use inheritance, the attributes must appear in the stream in the order that they are
inherited. That is, the attributes of a supertype must appear before attributes of a
subtype.

If multiple inheritance is used, then the attributes of supertypes should appear in the
stream in the order in which the supertypes are listed in the type declaration. This
protocol does not require the database server to have any knowledge of the Java
programming language. However, as there is no support for multiple inheritance in
the SQL99, this issue should not arise.