to top
Android APIs
Since: API Level 1
public interface

SQLData

java.sql.SQLData

Class Overview

An interface for the custom mapping of an SQL User Defined Type (UDT) to a Java class. The Java class object is added to the connection's type map paired with the SQL name of the corresponding UDT.

Usually within an implementation of SQLData, there is a corresponding field for every attribute of an SQL type, but only one field, if the type is SQL DISTINCT. When the UDT is returned within a ResultSet, it is accessed with the getObject(int) 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 setObject(int, Object) method which performs the reverse mapping into the SQL UDT.

Normally the implementation of a custom mapping is generated by a tool requiring 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 are 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 an application would not call SQLData methods directly. Similarly SQLInput and SQLOutput methods are not usually called directly.

Summary

Public Methods
abstract String getSQLTypeName()
Gets the SQL name of the User Defined Type (UDT) that this object represents.
abstract void readSQL(SQLInput stream, String typeName)
Reads data from the database into this object.
abstract void writeSQL(SQLOutput stream)
Writes the object to a supplied SQLOutput data stream, writing it out as an SQL value to the data source.

Public Methods

public abstract String getSQLTypeName ()

Since: API Level 1

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.
Throws
SQLException if a database error occurs.

public abstract void readSQL (SQLInput stream, String typeName)

Since: API Level 1

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 they are in 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 (e.g. 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.
Throws
SQLException if a database error occurs.
See Also

public abstract void writeSQL (SQLOutput stream)

Since: API Level 1

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 (e.g. 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.
Throws
SQLException if a database error occurs.
See Also