Standard JDBC RowSet
implementations may use these utility classes to assist in the serialization of disconnected RowSet
objects. This is useful when transmitting a disconnected RowSet
object over the wire to a different VM or across layers within an application.
SerialArray
class provides a constructor for creating a SerialArray
instance from an Array object, methods for getting the base type and the SQL name for the base type, and methods for copying all or part of a SerialArray
object. SerialBlob
class provides a constructor for creating an instance from a Blob object. Note that the Blob object should have brought the SQL BLOB value's data over to the client before a SerialBlob
object is constructed from it. The data of an SQL BLOB value can be materialized on the client as an array of bytes (using the method Blob.getBytes
) or as a stream of uninterpreted bytes (using the method Blob.getBinaryStream
). SerialBlob
methods make it possible to make a copy of a SerialBlob
object as an array of bytes or as a stream. They also make it possible to locate a given pattern of bytes or a Blob
object within a SerialBlob
object. SerialClob
class provides a constructor for creating an instance from a Clob
object. Note that the Clob
object should have brought the SQL CLOB value's data over to the client before a SerialClob
object is constructed from it. The data of an SQL CLOB value can be materialized on the client as a stream of Unicode characters. SerialClob
methods make it possible to get a substring from a SerialClob
object or to locate the start of a pattern of characters. RowSet
implementations can use the method RowSet.getURL()
to retrieve a java.net.URL
object, which can be used to manipulate the external data. java.net.URL url = rowset.getURL(1);
SerialException
being thrown. SerialRef
class provides a constructor for creating a SerialRef
instance from a Ref
type and provides methods for getting and setting the Ref
object type. Map
object is passed to one of the constructors or to the method getAttributes
, the structured type is custom mapped according to the mapping specified in the Map
object. SerialStruct
class provides a constructor for creating an instance from a Struct
object, a method for retrieving the SQL type name of the SQL structured type in the database, and methods for retrieving its attribute values. SQLInputImpl
object is an input stream that contains a stream of values that are the attributes of a UDT. This class is used by the driver behind the scenes when the method getObject
is called on an SQL structured or distinct type that has a custom mapping; a programmer never invokes SQLInputImpl
methods directly. SQLInputImpl
class provides a set of reader methods analogous to the ResultSet
getter methods. These methods make it possible to read the values in an SQLInputImpl
object. The method wasNull
is used to determine whether the last value read was SQL NULL. Map
object is called, the JDBC driver calls the method SQLData.getSQLType
to determine the SQL type of the UDT being custom mapped. The driver creates an instance of SQLInputImpl
, populating it with the attributes of the UDT. The driver then passes the input stream to the method SQLData.readSQL
, which in turn calls the SQLInputImpl
methods to read the attributes from the input stream. PreparedStatement.setObject
, the driver checks to see whether the value to be written is a UDT with a custom mapping. If it is, there will be an entry in a type map containing the Class object for the class that implements SQLData
for this UDT. If the value to be written is an instance of SQLData
, the driver will create an instance of SQLOutputImpl
and pass it to the method SQLData.writeSQL
. The method writeSQL
in turn calls the appropriate SQLOutputImpl
writer methods to write data from the SQLData
object to the SQLOutputImpl
output stream as the representation of an SQL user-defined type. A programmer defines the mapping by implementing the interface SQLData
. For example, if an SQL structured type named AUTHORS has the attributes NAME, TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The Authors class could have the fields name, title, and publisher, to which the attributes of AUTHORS are mapped. In such a case, the implementation of SQLData
could look like the following:
public class Authors implements SQLData { public String name; public String title; public String publisher; private String sql_type; public String getSQLTypeName() { return sql_type; } public void readSQL(SQLInput stream, String type) throws SQLException { sql_type = type; name = stream.readString(); title = stream.readString(); publisher = stream.readString(); } public void writeSQL(SQLOutput stream) throws SQLException { stream.writeString(name); stream.writeString(title); stream.writeString(publisher); } }A
java.util.Map
object is used to associate the SQL structured type with its mapping to the class Authors
. The following code fragment shows how a Map
object might be created and given an entry associating AUTHORS
and Authors
. java.util.Map map = new java.util.HashMap(); map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");The
Map
object map now contains an entry with the fully qualified name of the SQL structured type and the Class
object for the class Authors
. It can be passed to a method to tell the driver how to map AUTHORS
to Authors
. For a disconnected RowSet
object, custom mapping can be done only when a Map
object is passed to the method or constructor that will be doing the custom mapping. The situation is different for connected RowSet
objects because they maintain a connection with the data source. A method that does custom mapping and is called by a disconnected RowSet
object may use the Map
object that is associated with the Connection
object being used. So, in other words, if no map is specified, the connection's type map can be used by default.
Class | Description |
---|---|
SerialArray | A serialized version of an Array object, which is the mapping in the Java programming language of an SQL ARRAY value. |
SerialBlob | A serialized mapping in the Java programming language of an SQL BLOB value. |
SerialClob | A serialized mapping in the Java programming language of an SQL CLOB value. |
SerialDatalink | A serialized mapping in the Java programming language of an SQL DATALINK value. |
SerialException | Indicates and an error with the serialization or de-serialization of SQL types such as BLOB, CLOB, STRUCT or ARRAY in addition to SQL types such as DATALINK and JAVAOBJECT
|
SerialJavaObject | A serializable mapping in the Java programming language of an SQL JAVA_OBJECT value. |
SerialRef | A serialized mapping of a Ref object, which is the mapping in the Java programming language of an SQL REF value. |
SerialStruct | A serialized mapping in the Java programming language of an SQL structured type. |
SQLInputImpl | An input stream used for custom mapping user-defined types (UDTs). |
SQLOutputImpl | The output stream for writing the attributes of a custom-mapped user-defined type (UDT) back to the database. |
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.sql.rowset/javax/sql/rowset/serial/package-summary.html