0N/A<!
DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
0N/A <
meta http-
equiv="Content-Type" 0N/A <
meta name="GENERATOR" 2362N/ACopyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved. 0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/AThis code is free software; you can redistribute it and/or modify it 0N/Aunder the terms of the GNU General Public License version 2 only, as 2362N/Apublished by the Free Software Foundation. Oracle designates this 0N/Aparticular file as subject to the "Classpath" exception as provided 2362N/Aby Oracle in the LICENSE file that accompanied this code. 0N/AThis code is distributed in the hope that it will be useful, but WITHOUT 0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 0N/AYou should have received a copy of the GNU General Public License version 0N/A2 along with this work; if not, write to the Free Software Foundation, 0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<
body bgcolor="#ffffff">
0N/AProvides utility classes to allow serializable mappings between SQL types
0N/Aand data types in the Java programming language.
0N/A<
p> Standard JDBC <
code>RowSet</
code> implementations may use these utility
0N/Aassist in the serialization of disconnected <
code>RowSet</
code> objects.
0N/Awhen transmitting a disconnected <
tt>RowSet</
tt> object over the wire to
0N/Aa different VM or across layers within an application.<
br>
0N/A<
h3>1.0 SerialArray</
h3>
0N/AA serializable mapping in the Java programming language of an SQL ARRAY
0N/AThe <
tt>SerialArray </
tt>class provides a constructor for creating a <
tt>SerialArray
0N/A</
tt>instance from an Array object, methods for getting the base type and
0N/Athe SQL name for the base type, and methods for copying all or part of a
0N/A<
tt>SerialArray </
tt>object. <
br>
0N/A<
h3>2.0 SerialBlob</
h3>
0N/AA serializable mapping in the Java programming language of an SQL BLOB
0N/AThe <
tt>SerialBlob </
tt>class provides a constructor for creating an instance
0N/Afrom a Blob object. Note that the Blob object should have brought the SQL
0N/ABLOB value's data over to the client before a <
tt>SerialBlob </
tt>object
0N/Ais constructed from it. The data of an SQL BLOB value can be materialized
0N/A<
tt>SerialBlob </
tt>methods make it possible to make a copy of a <
tt>SerialBlob
0N/A</
tt>object as an array of bytes or as a stream. They also make it possible
0N/Ato locate a given pattern of bytes or a <
tt>Blob </
tt>object within a <
tt>SerialBlob
0N/A<
h3>3.0 SerialClob</
h3>
0N/AA serializable mapping in the Java programming language of an SQL CLOB
0N/AThe <
tt>SerialClob </
tt>class provides a constructor for creating an instance
0N/Afrom a <
tt>Clob </
tt>object. Note that the <
tt>Clob </
tt>object should have
0N/Abrought the SQL CLOB value's data over to the client before a <
tt>SerialClob
0N/A</
tt>object is constructed from it. The data of an SQL CLOB value can be
0N/Amaterialized on the client as a stream of Unicode characters. <
br>
0N/A<
tt>SerialClob </
tt>methods make it possible to get a substring from a
0N/A<
tt>SerialClob </
tt>object or to locate the start of a pattern of characters.
0N/A<
h3>5.0 SerialDatalink</
h3>
0N/AA serializable mapping in the Java programming language of an SQL DATALINK
0N/Avalue. A DATALINK value references a file outside of the underlying data source
0N/Athat the the originating data source manages. <
br>
0N/A<
code>RowSet</
code> implementations can use the method <
tt>
RowSet.getURL() </
tt>to retrieve
0N/Aa <
code>
java.
net.
URL</
code> object, which can be used to manipulate the external data.
0N/A<
h3>6.0 SerialJavaObject</
h3>
0N/AA serializable mapping in the Java programming language of an SQL JAVA_OBJECT
0N/Avalue. Assuming the Java object instance implements the Serializable interface,
0N/Athis simply wraps the serialization process. <
br>
0N/AIf however, the serialization is not possible in the case where the Java
0N/Aobject is not immediately serializable, this class will attempt to serialize
0N/Aall non static members to permit the object instance state to be serialized.
0N/AStatic or transient fields cannot be serialized and attempting to do so
0N/Awill result in a <
tt>SerialException </
tt>being thrown. <
br>
0N/A<
h3>7.0 SerialRef</
h3>
0N/AA serializable mapping between the SQL REF type and the Java programming
0N/AThe <
tt>SerialRef </
tt>class provides a constructor for creating a <
tt>SerialRef
0N/A</
tt>instance from a <
tt>Ref</
tt> type and provides methods for getting
0N/Aand setting the <
tt>Ref</
tt> object type. <
br>
0N/A<
h3>8.0 SerialStruct</
h3>
0N/AA serializable mapping in the Java programming language of an SQL structured
0N/Atype. Each attribute that is not already serializable is mapped to a serializable
0N/Aform, and if an attribute is itself a structured type, each of its attributes
0N/Athat is not already serializable is mapped to a serializable form. <
br>
0N/AIn addition, if a <
code>Map</
code> object is passed to one of the constructors or
0N/Ato the method <
code>getAttributes</
code>, the structured type is custom mapped
0N/Aaccording to the mapping specified in the <
code>Map</
code> object.
0N/A The <
tt>SerialStruct </
tt>class provides a constructor for creating an
0N/Ainstance from a <
tt>Struct</
tt> object, a method for retrieving the SQL
0N/Atype name of the SQL structured type in the database, and methods for retrieving
0N/Aits attribute values. <
br>
0N/A<
h3>9.0 SQLInputImpl</
h3>
0N/A An input stream used for custom mapping user-defined types (UDTs). An
0N/A <
tt>SQLInputImpl</
tt> object is an input stream that contains a stream of
0N/Athe attributes of a UDT. This class is used by the driver behind the scenes
0N/Awhen the method <
tt>getObject</
tt> is called on an SQL structured or distinct
0N/Atype that has a custom mapping; a programmer never invokes <
tt>SQLInputImpl
0N/A</
tt> methods directly. <
br>
0N/A The <
tt>SQLInputImpl</
tt> class provides a set of reader methods
0N/A analogous to the <
tt>ResultSet</
tt> getter methods. These methods make it
0N/A possible to read the values in an <
tt>SQLInputImpl</
tt> object. The method
0N/A<
code>wasNull</
code> is used to determine whether the the last value read was SQL NULL.
0N/A When a constructor or getter method that takes a <
code>Map</
code> object is called,
0N/Athe JDBC driver calls the method
0N/Amapped. The driver creates an instance of <
code>SQLInputImpl</
code>, populating it with
0N/Athe attributes of the UDT. The driver then passes the input stream to the
0N/Amethods to read the attributes from the input stream. <
br>
0N/A<
h3>10.0 SQLOutputImpl</
h3>
0N/A The output stream for writing the attributes of a custom mapped user-defined
0N/A type (UDT) back to the database. The driver uses this interface internally,
0N/A and its methods are never directly invoked by an application programmer.
0N/A driver checks to see whether the value to be written is a UDT with a custom
0N/A mapping. If it is, there will be an entry in a type map containing the Class
0N/A object for the class that implements <
tt>SQLData </
tt>for this UDT. If the
0N/A value to be written is an instance of <
tt>SQLData</
tt>, the driver will
0N/Acreate an instance of <
code>SQLOutputImpl</
code> and pass it to the method
0N/A The method <
code>writeSQL</
code> in turn calls the appropriate <
tt>SQLOutputImpl</
tt>
0N/Awriter methods to write data from the <
code>SQLData</
code> object to the
0N/A<
code>SQLOutputImpl</
code>
0N/Aoutput stream as the representation of an SQL user-defined type.
0N/A<
h3>Custom Mapping</
h3>
0N/AThe JDBC API provides mechanisms for mapping an SQL structured type or DISTINCT
0N/Atype to the Java programming language. Typically, a structured type is mapped
0N/Ato a class, and its attributes are mapped to fields in the class.
0N/A(A DISTINCT type can thought of as having one attribute.) However, there are
0N/Amany other possibilities, and there may be any number of different mappings.
0N/AA programmer defines the mapping by implementing the interface <
code>SQLData</
code>.
0N/AFor example, if an SQL structured type named AUTHORS has the attributes NAME,
0N/ATITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The
0N/AAuthors class could have the fields name, title, and publisher, to which the
0N/Aattributes of AUTHORS are mapped. In such a case, the implementation of
0N/A<
code>SQLData</
code> could look like the following:
0N/A public class Authors implements SQLData {
0N/A public String title;
0N/A public String publisher;
0N/A private String sql_type;
0N/A public String getSQLTypeName() {
0N/A public void readSQL(SQLInput stream, String type)
0N/A throws SQLException {
0N/A public void writeSQL(SQLOutput stream) throws SQLException {
0N/AA <
code>
java.
util.
Map</
code> object is used to associate the SQL structured
0N/Atype with its mapping to the class <
code>Authors</
code>. The following code fragment shows
0N/Ahow a <
code>Map</
code> object might be created and given an entry associating
0N/A<
code>AUTHORS</
code> and <
code>Authors</
code>.
0N/AThe <
code>Map</
code> object <
i>map</
i> now contains an entry with the
0N/Afully qualified name of the SQL structured type and the <
code>Class</
code>
0N/A object for the class <
code>Authors</
code>. It can be passed to a method
0N/Ato tell the driver how to map <
code>AUTHORS</
code> to <
code>Authors</
code>.
0N/AFor a disconnected <
code>RowSet</
code> object, custom mapping can be done
0N/Aonly when a <
code>Map</
code> object is passed to the method or constructor
0N/Athat will be doing the custom mapping. The situation is different for
0N/Aconnected <
code>RowSet</
code> objects because they maintain a connection
0N/Awith the data source. A method that does custom mapping and is called by
0N/Aa disconnected <
code>RowSet</
code> object may use the <
code>Map</
code>
0N/Aobject that is associated with the <
code>Connection</
code> object being
0N/Aused. So, in other words, if no map is specified, the connection's type
0N/Amap can be used by default.