| J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 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 2003-2006 Sun Microsystems, Inc. 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. Sun designates this |
| 17 | particular file as subject to the "Classpath" exception as provided |
| 18 | by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 31 | CA 95054 USA or visit www.sun.com if you need additional information or |
| 32 | have any 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> |