Stay organized with collections
Save and categorize content based on your preferences.
SQLData
public
interface
SQLData
The interface used for the custom mapping of an SQL user-defined type (UDT) to
a class in the Java programming language. The class object for a class
implementing the SQLData interface will be entered in the
appropriate Connection object's type map along with the SQL
name of the UDT for which it is a custom mapping.
Typically, a SQLData implementation
will define a field for each attribute of an SQL structured type or a
single field for an SQL DISTINCT type. When the UDT is
retrieved from a data source with the ResultSet.getObject
method, it will be mapped as an instance of this class. A programmer
can operate on this class instance just as on any other object in the
Java programming language and then store any changes made to it by
calling the PreparedStatement.setObject method,
which will map it back to the SQL type.
It is expected that the implementation of the class for a custom
mapping will be done by a tool. In a typical implementation, the
programmer would simply supply the name of the SQL UDT, the name of
the class to which it is being mapped, and the names of the fields to
which each of the attributes of the UDT is to be mapped. The tool will use
this information to implement the SQLData.readSQL and
SQLData.writeSQL methods. The readSQL method
calls the appropriate SQLInput methods to read
each attribute from an SQLInput object, and the
writeSQL method calls SQLOutput methods
to write each attribute back to the data source via an
SQLOutput object.
An application programmer will not normally call SQLData methods
directly, and the SQLInput and SQLOutput methods
are called internally by SQLData methods, not by application code.
Summary
Public methods |
|---|
abstract
String
|
getSQLTypeName()
Returns the fully-qualified
name of the SQL user-defined type that this object represents.
|
abstract
void
|
readSQL(SQLInput stream, String typeName)
Populates this object with data read from the database.
|
abstract
void
|
writeSQL(SQLOutput stream)
Writes this object to the given SQL data stream, converting it back to
its SQL value in the data source.
|
Public methods
getSQLTypeName
public abstract String getSQLTypeName ()
Returns the fully-qualified
name of the SQL user-defined type that this object represents.
This method is called by the JDBC driver to get the name of the
UDT instance that is being mapped to this instance of
SQLData.
| Returns |
|---|
String |
the type name that was passed to the method readSQL
when this object was constructed and populated |
public abstract void readSQL (SQLInput stream,
String typeName)
Populates this object with data read from the database.
The implementation of the method must follow this protocol:
- It must read each of the attributes or elements of the SQL
type from the given input stream. This is done
by calling a method of the input stream to read each
item, in the order that they appear in the SQL definition
of the type.
- The method
readSQL then
assigns the data to appropriate fields or
elements (of this or other objects).
Specifically, it must call the appropriate reader method
(SQLInput.readString, SQLInput.readBigDecimal,
and so on) method(s) to do the following:
for a distinct type, read its single data element;
for a structured type, read a value for each attribute of the SQL type.
The JDBC driver initializes the input stream with a type map
before calling this method, which is used by the appropriate
SQLInput reader method on the stream.
| Parameters |
|---|
stream |
SQLInput: the SQLInput object from which to read the data for
the value that is being custom mapped |
typeName |
String: the SQL type name of the value on the data stream |
writeSQL
public abstract void writeSQL (SQLOutput stream)
Writes this object to the given SQL data stream, converting it back to
its SQL value in the data source.
The implementation of the method must follow this protocol:
It must write each of the attributes of the SQL type
to the given output stream. This is done by calling a
method of the output stream to write each item, in the order that
they appear in the SQL definition of the type.
Specifically, it must call the appropriate SQLOutput writer
method(s) (writeInt, writeString, and so on)
to do the following: for a Distinct Type, write its single data element;
for a Structured Type, write a value for each attribute of the SQL type.
| Parameters |
|---|
stream |
SQLOutput: the SQLOutput object to which to write the data for
the value that was custom mapped |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-02-10 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-02-10 UTC."],[],[],null,["# SQLData\n\nAdded in [API level 1](/guide/topics/manifest/uses-sdk-element#ApiLevels) \n\nSQLData\n=======\n\n\n`\npublic\n\n\ninterface\nSQLData\n`\n\n\n`\n\n\n`\n\n|------------------|\n| java.sql.SQLData |\n\n\u003cbr /\u003e\n\n*** ** * ** ***\n\nThe interface used for the custom mapping of an SQL user-defined type (UDT) to\na class in the Java programming language. The class object for a class\nimplementing the `SQLData` interface will be entered in the\nappropriate `Connection` object's type map along with the SQL\nname of the UDT for which it is a custom mapping.\n\n\nTypically, a `SQLData` implementation\nwill define a field for each attribute of an SQL structured type or a\nsingle field for an SQL `DISTINCT` type. When the UDT is\nretrieved from a data source with the `ResultSet.getObject`\nmethod, it will be mapped as an instance of this class. A programmer\ncan operate on this class instance just as on any other object in the\nJava programming language and then store any changes made to it by\ncalling the `PreparedStatement.setObject` method,\nwhich will map it back to the SQL type.\n\n\nIt is expected that the implementation of the class for a custom\nmapping will be done by a tool. In a typical implementation, the\nprogrammer would simply supply the name of the SQL UDT, the name of\nthe class to which it is being mapped, and the names of the fields to\nwhich each of the attributes of the UDT is to be mapped. The tool will use\nthis information to implement the `SQLData.readSQL` and\n`SQLData.writeSQL` methods. The `readSQL` method\ncalls the appropriate `SQLInput` methods to read\neach attribute from an `SQLInput` object, and the\n`writeSQL` method calls `SQLOutput` methods\nto write each attribute back to the data source via an\n`SQLOutput` object.\n\n\nAn application programmer will not normally call `SQLData` methods\ndirectly, and the `SQLInput` and `SQLOutput` methods\nare called internally by `SQLData` methods, not by application code.\n\nSummary\n-------\n\n| ### Public methods ||\n|---------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ` abstract `[String](/reference/java/lang/String) | ` `[getSQLTypeName](/reference/java/sql/SQLData#getSQLTypeName())`() ` Returns the fully-qualified name of the SQL user-defined type that this object represents. |\n| ` abstract void` | ` `[readSQL](/reference/java/sql/SQLData#readSQL(java.sql.SQLInput,%20java.lang.String))`(`[SQLInput](/reference/java/sql/SQLInput)` stream, `[String](/reference/java/lang/String)` typeName) ` Populates this object with data read from the database. |\n| ` abstract void` | ` `[writeSQL](/reference/java/sql/SQLData#writeSQL(java.sql.SQLOutput))`(`[SQLOutput](/reference/java/sql/SQLOutput)` stream) ` Writes this object to the given SQL data stream, converting it back to its SQL value in the data source. |\n\nPublic methods\n--------------\n\n### getSQLTypeName\n\nAdded in [API level 1](/guide/topics/manifest/uses-sdk-element#ApiLevels) \n\n```\npublic abstract String getSQLTypeName ()\n```\n\nReturns the fully-qualified\nname of the SQL user-defined type that this object represents.\nThis method is called by the JDBC driver to get the name of the\nUDT instance that is being mapped to this instance of\n`SQLData`.\n\n\u003cbr /\u003e\n\n| Returns ||\n|---------------------------------------|-------------------------------------------------------------------------------------------------------------|\n| [String](/reference/java/lang/String) | the type name that was passed to the method `readSQL` when this object was constructed and populated \u003cbr /\u003e |\n\n| Throws ||\n|----------------------------------------------------------------------------------------|-------------------------------------------------|\n| [SQLException](/reference/java/sql/SQLException) | if there is a database access error |\n| [SQLFeatureNotSupportedException](/reference/java/sql/SQLFeatureNotSupportedException) | if the JDBC driver does not support this method |\n\n### readSQL\n\nAdded in [API level 1](/guide/topics/manifest/uses-sdk-element#ApiLevels) \n\n```\npublic abstract void readSQL (SQLInput stream, \n String typeName)\n```\n\nPopulates this object with data read from the database.\nThe implementation of the method must follow this protocol:\n\n- It must read each of the attributes or elements of the SQL type from the given input stream. This is done by calling a method of the input stream to read each item, in the order that they appear in the SQL definition of the type.\n- The method `readSQL` then assigns the data to appropriate fields or elements (of this or other objects). Specifically, it must call the appropriate *reader* method (`SQLInput.readString`, `SQLInput.readBigDecimal`, and so on) method(s) to do the following: for a distinct type, read its single data element; for a structured type, read a value for each attribute of the SQL type.\n\nThe JDBC driver initializes the input stream with a type map before calling this method, which is used by the appropriate `SQLInput` reader method on the stream.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Parameters ||\n|------------|----------------------------------------------------------------------------------------------------------------|\n| `stream` | `SQLInput`: the `SQLInput` object from which to read the data for the value that is being custom mapped \u003cbr /\u003e |\n| `typeName` | `String`: the SQL type name of the value on the data stream \u003cbr /\u003e |\n\n| Throws ||\n|----------------------------------------------------------------------------------------|-------------------------------------------------|\n| [SQLException](/reference/java/sql/SQLException) | if there is a database access error |\n| [SQLFeatureNotSupportedException](/reference/java/sql/SQLFeatureNotSupportedException) | if the JDBC driver does not support this method |\n\n**See also:**\n\n- [SQLInput](/reference/java/sql/SQLInput) \n\n### writeSQL\n\nAdded in [API level 1](/guide/topics/manifest/uses-sdk-element#ApiLevels) \n\n```\npublic abstract void writeSQL (SQLOutput stream)\n```\n\nWrites this object to the given SQL data stream, converting it back to\nits SQL value in the data source.\nThe implementation of the method must follow this protocol: \n\nIt must write each of the attributes of the SQL type\nto the given output stream. This is done by calling a\nmethod of the output stream to write each item, in the order that\nthey appear in the SQL definition of the type.\nSpecifically, it must call the appropriate `SQLOutput` writer\nmethod(s) (`writeInt`, `writeString`, and so on)\nto do the following: for a Distinct Type, write its single data element;\nfor a Structured Type, write a value for each attribute of the SQL type.\n\n\u003cbr /\u003e\n\n| Parameters ||\n|----------|------------------------------------------------------------------------------------------------------------|\n| `stream` | `SQLOutput`: the `SQLOutput` object to which to write the data for the value that was custom mapped \u003cbr /\u003e |\n\n| Throws ||\n|----------------------------------------------------------------------------------------|-------------------------------------------------|\n| [SQLException](/reference/java/sql/SQLException) | if there is a database access error |\n| [SQLFeatureNotSupportedException](/reference/java/sql/SQLFeatureNotSupportedException) | if the JDBC driver does not support this method |\n\n**See also:**\n\n- [SQLOutput](/reference/java/sql/SQLOutput)"]]
