/* * Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ /** * Provides utility classes to allow serializable mappings between SQL types * and data types in the Java programming language. *
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.
*/
package javax.sql.rowset.serial;