Whole document tree

7 Persistence for Java Objects

The new JDBC API features described in this chapter are intended to support a new generation of Java-aware database management systems, termed Java-relational DBMSs. A Java-relational DBMS extends the type system of a database with Java object types and allows users to write queries that reference these types. Several database vendors are creating products with Java-relational capabilities. The mechanisms described in this chapter are optional. JDBC drivers that do not support the capabilities described in this chapter are not required to implement them.

Lets take a look at how a typical application written in the Java programming language (Java application) can make use of the JDBC API to store and retrieve Java objects.

7.1     Retrieving Java objects

ResultSet rs = stmt.executeQuery( 
	"SELECT Employee FROM PERSONNEL");
rs.next();
Employee emp = (Employee)rs.getObject(1);

The example selects all of the Employee instances from the PERSONNEL table. The ResultSet.next() method is called to position the result set to the first row containing an Employee. The example application then obtains an Employee instance by calling ResultSet.getObject(). This causes the JDBC driver to construct an instance of the Employee class, possibly by deserializing a serialized object instance, and return the instance as a java.lang.Object which the application then narrows to an Employee.

Note that the example above does not contain any additions to the JDBC 1.0 API aside from possibly requiring some form of extended SQL query syntax which is not specified by the JDBC API. As an aside, we note that the JDBC technology based code shown above can also be used to retrieve data of an SQL user-defined type that is being mapped to a Java class. The details on how this is done are specified in a later chapter.

7.2     Storing Java objects

emp.setSalary(emp.getSalary() * 1.5);
PreparedStatement pstmt = con.preparedStatement(
"UPDATE PERSONNEL SET Employee = ? WHERE Employee.no = 1001");
pstmt.setObject(1, emp);
pstmt.executeUpdate();

Next, a PreparedStatement object is created using an extended SQL UPDATE command -the query syntax used in the example is again not mandated by the JDBC API. The UPDATE command specifies that the Employee column in the PERSONNEL table is to be changed for a specified row. PreparedStatement.setObject() is used to pass the Employee object to the prepared statement, and the executeUpdate() method updates the Employee value stored in the database.

Note once again that the example above does not involve any syntactic additions to the JDBC 1.0 API. In addition, the same code could be used if the Employee class was being mapped to an SQL user-defined type.

7.3     Additional metadata

7.3.1 Identifying Java objects

1. TYPE_NAME String => data source specific name (may be null)
2. DATA_TYPE short => java.sql.Types.JAVA_OBJECT
3. etc.

The TYPE_NAME column contains the data source specific term for a Java object, such as "JavaObject", "Serialized" etc. TYPE_NAME may be null.

7.3.2 Retrieving schema-specific Java type descriptions

int[] types = {Types.JAVA_OBJECT};
ResultSet rs = dmd.getUDTs("catalog-name", "schema-name", 
	"%", types);

returns descriptions of all the Java object types defined in the catalog-name.schema- name schema. If the driver does not support UDTs or no matching UDTs are found then an empty result set is returned.

Each type description has the following columns:

TYPE_CAT	String => the type's catalog (may be null)
TYPE_SCHEM	String => the type's schema (may be null)
TYPE_NAME	String => the database type name
JAVA_CLASS	String => a Java classname
DATA_TYPE	short => value defined in java.sql.Types, e.g. JAVA_OBJECT
REMARKS	String => explanatory comment on the type

The TYPE_CAT, TYPE_SCHEM, DATA_TYPE, and REMARKS columns should be self-explanatory. The TYPE_NAME is, in effect, the SQL type name. This is the name used in a CREATE TABLE statement to specify a column of this type.

When DATA_TYPE is JAVA_OBJECT, the JAVA_CLASS is the fully qualified Java class name of the Java class associated with TYPE_NAME. All values actually stored in a TYPE_NAME column must be instances of this class or one of its subclasses. Instances of this class or a subclass are materialized by the JDBC driver when values are fetched from a TYPE_NAME column by an application that uses JDBC technology.

The DatabaseMetaData.getUDTs() method also accepts a fully qualified SQL name as its third parameter. In this case the catalog and schema pattern parameters are ignored. The fully qualified SQL name may contain wildcards. For example, the code sample below is equivalent to the previous example,

int[] types = {Types.JAVA_OBJECT};
ResultSet rs = dmd.getUDTs(null, null, 
	"catalog-name.schema-name.%", types);

7.3.3 Retrieving the Java class object