1 <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en"> 2 <html> 3 <head> 4 5 <meta http-equiv="Content-Type" 6 content="text/html; charset=iso-8859-1"> 7 8 <meta name="GENERATOR" 9 content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> 10 <!-- 11 Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved. 12 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 13 14 This code is free software; you can redistribute it and/or modify it 15 under the terms of the GNU General Public License version 2 only, as 16 published by the Free Software Foundation. Oracle designates this 17 particular file as subject to the "Classpath" exception as provided 18 by Oracle in the LICENSE file that accompanied this code. 19 20 This code is distributed in the hope that it will be useful, but WITHOUT 21 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 22 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 23 version 2 for more details (a copy is included in the LICENSE file that 24 accompanied this code). 25 26 You should have received a copy of the GNU General Public License version 27 2 along with this work; if not, write to the Free Software Foundation, 28 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 29 30 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 31 or visit www.oracle.com if you need additional information or have any 32 questions. 33 --> 34 <title>javax.sql.rowset.serial</title> 35 </head> 36 <body bgcolor="#ffffff"> 37 Provides utility classes to allow serializable mappings between SQL types 38 and data types in the Java programming language. 39 <p> Standard JDBC <code>RowSet</code> implementations may use these utility 40 classes to 41 assist in the serialization of disconnected <code>RowSet</code> objects. 42 This is useful 43 when transmitting a disconnected <tt>RowSet</tt> object over the wire to 44 a different VM or across layers within an application.<br> 45 </p> 46 47 <h3>1.0 SerialArray</h3> 48 A serializable mapping in the Java programming language of an SQL ARRAY 49 value. <br> 50 <br> 51 The <tt>SerialArray </tt>class provides a constructor for creating a <tt>SerialArray 52 </tt>instance from an Array object, methods for getting the base type and 53 the SQL name for the base type, and methods for copying all or part of a 54 <tt>SerialArray </tt>object. <br> 55 56 <h3>2.0 SerialBlob</h3> 57 A serializable mapping in the Java programming language of an SQL BLOB 58 value. <br> 59 <br> 60 The <tt>SerialBlob </tt>class provides a constructor for creating an instance 61 from a Blob object. Note that the Blob object should have brought the SQL 62 BLOB value's data over to the client before a <tt>SerialBlob </tt>object 63 is constructed from it. The data of an SQL BLOB value can be materialized 64 on the client as an array of bytes (using the method <tt>Blob.getBytes</tt>) 65 or as a stream of uninterpreted bytes (using the method <tt>Blob.getBinaryStream</tt>). 66 <br> 67 <br> 68 <tt>SerialBlob </tt>methods make it possible to make a copy of a <tt>SerialBlob 69 </tt>object as an array of bytes or as a stream. They also make it possible 70 to locate a given pattern of bytes or a <tt>Blob </tt>object within a <tt>SerialBlob 71 </tt>object. <br> 72 73 <h3>3.0 SerialClob</h3> 74 A serializable mapping in the Java programming language of an SQL CLOB 75 value. <br> 76 <br> 77 The <tt>SerialClob </tt>class provides a constructor for creating an instance 78 from a <tt>Clob </tt>object. Note that the <tt>Clob </tt>object should have 79 brought the SQL CLOB value's data over to the client before a <tt>SerialClob 80 </tt>object is constructed from it. The data of an SQL CLOB value can be 81 materialized on the client as a stream of Unicode characters. <br> 82 <br> 83 <tt>SerialClob </tt>methods make it possible to get a substring from a 84 <tt>SerialClob </tt>object or to locate the start of a pattern of characters. 85 <br> 86 87 <h3>5.0 SerialDatalink</h3> 88 A serializable mapping in the Java programming language of an SQL DATALINK 89 value. A DATALINK value references a file outside of the underlying data source 90 that the the originating data source manages. <br> 91 <br> 92 <code>RowSet</code> implementations can use the method <tt>RowSet.getURL() </tt>to retrieve 93 a <code>java.net.URL</code> object, which can be used to manipulate the external data. 94 <br> 95 <br> 96 <tt> java.net.URL url = rowset.getURL(1);</tt><br> 97 98 <h3>6.0 SerialJavaObject</h3> 99 A serializable mapping in the Java programming language of an SQL JAVA_OBJECT 100 value. Assuming the Java object instance implements the Serializable interface, 101 this simply wraps the serialization process. <br> 102 <br> 103 If however, the serialization is not possible in the case where the Java 104 object is not immediately serializable, this class will attempt to serialize 105 all non static members to permit the object instance state to be serialized. 106 Static or transient fields cannot be serialized and attempting to do so 107 will result in a <tt>SerialException </tt>being thrown. <br> 108 109 <h3>7.0 SerialRef</h3> 110 A serializable mapping between the SQL REF type and the Java programming 111 language. <br> 112 <br> 113 The <tt>SerialRef </tt>class provides a constructor for creating a <tt>SerialRef 114 </tt>instance from a <tt>Ref</tt> type and provides methods for getting 115 and setting the <tt>Ref</tt> object type. <br> 116 117 <h3>8.0 SerialStruct</h3> 118 A serializable mapping in the Java programming language of an SQL structured 119 type. Each attribute that is not already serializable is mapped to a serializable 120 form, and if an attribute is itself a structured type, each of its attributes 121 that is not already serializable is mapped to a serializable form. <br> 122 <br> 123 In addition, if a <code>Map</code> object is passed to one of the constructors or 124 to the method <code>getAttributes</code>, the structured type is custom mapped 125 according to the mapping specified in the <code>Map</code> object. 126 <br> 127 The <tt>SerialStruct </tt>class provides a constructor for creating an 128 instance from a <tt>Struct</tt> object, a method for retrieving the SQL 129 type name of the SQL structured type in the database, and methods for retrieving 130 its attribute values. <br> 131 132 <h3>9.0 SQLInputImpl</h3> 133 An input stream used for custom mapping user-defined types (UDTs). An 134 <tt>SQLInputImpl</tt> object is an input stream that contains a stream of 135 values that are 136 the attributes of a UDT. This class is used by the driver behind the scenes 137 when the method <tt>getObject</tt> is called on an SQL structured or distinct 138 type that has a custom mapping; a programmer never invokes <tt>SQLInputImpl 139 </tt> methods directly. <br> 140 <br> 141 The <tt>SQLInputImpl</tt> class provides a set of reader methods 142 analogous to the <tt>ResultSet</tt> getter methods. These methods make it 143 possible to read the values in an <tt>SQLInputImpl</tt> object. The method 144 <code>wasNull</code> is used to determine whether the the last value read was SQL NULL. 145 <br> 146 <br> 147 When a constructor or getter method that takes a <code>Map</code> object is called, 148 the JDBC driver calls the method 149 <tt>SQLData.getSQLType</tt> to determine the SQL type of the UDT being custom 150 mapped. The driver creates an instance of <code>SQLInputImpl</code>, populating it with 151 the attributes of the UDT. The driver then passes the input stream to the 152 method <tt>SQLData.readSQL</tt>, which in turn calls the <tt>SQLInputImpl</tt> 153 methods to read the attributes from the input stream. <br> 154 155 <h3>10.0 SQLOutputImpl</h3> 156 The output stream for writing the attributes of a custom mapped user-defined 157 type (UDT) back to the database. The driver uses this interface internally, 158 and its methods are never directly invoked by an application programmer. 159 <br> 160 <br> 161 When an application calls the method <tt>PreparedStatement.setObject, </tt>the 162 driver checks to see whether the value to be written is a UDT with a custom 163 mapping. If it is, there will be an entry in a type map containing the Class 164 object for the class that implements <tt>SQLData </tt>for this UDT. If the 165 value to be written is an instance of <tt>SQLData</tt>, the driver will 166 create an instance of <code>SQLOutputImpl</code> and pass it to the method 167 <tt>SQLData.writeSQL</tt>. 168 The method <code>writeSQL</code> in turn calls the appropriate <tt>SQLOutputImpl</tt> 169 writer methods to write data from the <code>SQLData</code> object to the 170 <code>SQLOutputImpl</code> 171 output stream as the representation of an SQL user-defined type. 172 173 <h3>Custom Mapping</h3> 174 The JDBC API provides mechanisms for mapping an SQL structured type or DISTINCT 175 type to the Java programming language. Typically, a structured type is mapped 176 to a class, and its attributes are mapped to fields in the class. 177 (A DISTINCT type can thought of as having one attribute.) However, there are 178 many other possibilities, and there may be any number of different mappings. 179 <P> 180 A programmer defines the mapping by implementing the interface <code>SQLData</code>. 181 For example, if an SQL structured type named AUTHORS has the attributes NAME, 182 TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The 183 Authors class could have the fields name, title, and publisher, to which the 184 attributes of AUTHORS are mapped. In such a case, the implementation of 185 <code>SQLData</code> could look like the following: 186 <PRE> 187 public class Authors implements SQLData { 188 public String name; 189 public String title; 190 public String publisher; 191 192 private String sql_type; 193 public String getSQLTypeName() { 194 return sql_type; 195 } 196 197 public void readSQL(SQLInput stream, String type) 198 throws SQLException { 199 sql_type = type; 200 name = stream.readString(); 201 title = stream.readString(); 202 publisher = stream.readString(); 203 } 204 205 public void writeSQL(SQLOutput stream) throws SQLException { 206 stream.writeString(name); 207 stream.writeString(title); 208 stream.writeString(publisher); 209 } 210 } 211 </PRE> 212 213 A <code>java.util.Map</code> object is used to associate the SQL structured 214 type with its mapping to the class <code>Authors</code>. The following code fragment shows 215 how a <code>Map</code> object might be created and given an entry associating 216 <code>AUTHORS</code> and <code>Authors</code>. 217 <PRE> 218 java.util.Map map = new java.util.HashMap(); 219 map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors"); 220 </PRE> 221 222 The <code>Map</code> object <i>map</i> now contains an entry with the 223 fully qualified name of the SQL structured type and the <code>Class</code> 224 object for the class <code>Authors</code>. It can be passed to a method 225 to tell the driver how to map <code>AUTHORS</code> to <code>Authors</code>. 226 <P> 227 For a disconnected <code>RowSet</code> object, custom mapping can be done 228 only when a <code>Map</code> object is passed to the method or constructor 229 that will be doing the custom mapping. The situation is different for 230 connected <code>RowSet</code> objects because they maintain a connection 231 with the data source. A method that does custom mapping and is called by 232 a disconnected <code>RowSet</code> object may use the <code>Map</code> 233 object that is associated with the <code>Connection</code> object being 234 used. So, in other words, if no map is specified, the connection's type 235 map can be used by default. 236 237 <br> 238 </body> 239 </html>