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