java.sql
public
interface
java.sql.SQLData
An interface for the custom mapping of an SQL User Defined Type (UDT) to a
Java Class. The Java Class object will be added to the Connection's type map
with the SQL Name of the UDT which it maps.
Usually within an implementation of SQLData, there is a corresponding field
for every attribute of an SQL type, or only one field if the type is SQL
DISTINCT. When the UDT is returned within a ResultSet, it is accessed with
the ResultSet.getObject method and is returned as an Object which is an
instance of the class defined by the SQLData mapping. The application can use
this object just like any other Java object and can store changes back into
the database using the PreparedStatement.setObject method which performs the
reverse mapping into the SQL UDT.
It is standard for an implementation for a custom mapping to be generated by
a tool. The tool usually requires the name of the SQL UDT, the name of the
class which it is going to be mapped to, and the field names to which the UDT
attributes will be mapped. The tool can then implement the SQLData readSQL
and writeSQL methods. readSQL reads attributes from an SQLInput object, and
writeSQL writes them. This is done via SQLInput and SQLOutput method calls
respectively
Ordinarily a programmer would not call SQLData methods directly. Similarly
SQLInput and SQLOutput methods are not usually called directly.
Summary
Details
Public Methods
public
String
getSQLTypeName()
Gets the SQL name of the User Defined Type (UDT) that this object
represents. This method, usually invoked by the JDBC driver, retrieves
the name of the UDT instance associated with this SQLData object.
Returns
- a string with UDT type name for this object mapping, passed to
readSQL when the object was created
public
void
readSQL(SQLInput stream, String typeName)
Reads data from the database into this object. This method follows these
steps:
- Utilize the passed input stream to read the attributes or entries of
the SQL type
- This is carried out by reading each entry from the input stream,
ordered as the are the SQL definition.
- Assign the data to the appropriate fields or elements. This is done
by calling the relevant reader method for the type involved (eg.
SQLInput.readString, SQLInputreadBigDecimal). If the type is distinct,
then read its only data entry. For structured types, read every entry.
The supplied input stream is typically initialized by the calling JDBC
driver with the type map before readSQL is called.
Parameters
stream
| the SQLInput stream from which the type map data is read for
the custom mapping |
typeName
| the SQL Type name for the type which is being mapped |
public
void
writeSQL(SQLOutput stream)
Writes the object to a supplied SQLOutput data stream, writing it out as
an SQL value to the data source.
This method follows the following steps:
- Write each attribute of the SQL type to the output stream.
- Write each item by calling a method on the output stream, in the
order they appear in the SQL definition of the type. Use the appropriate
SQLOutput methods (eg. writeInt, writeString). Write a single data
element for a Distinct type. For a Structured type, write a value for
each attribute of the the SQL type.
Parameters
stream
| the SQLOutput stream to use to write out the data for the
custom mapping |