< prev index next >

src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package-info.java

Print this page
rev 52981 : 8215309: Convert package.html files to package-info.java files
Reviewed-by:
   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 <code>RowSet</code> 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 <code>SerialArray</code> class provides a constructor for creating a <code>SerialArray</code>
  52 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 <code>SerialArray</code> 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 <code>SerialBlob</code>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 <code>SerialBlob</code>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 <code>Blob.getBytes</code>)
  65 or as a stream of uninterpreted bytes (using the method <code>Blob.getBinaryStream</code>).
  66 <br>
  67 <br>
  68 <code>SerialBlob</code> methods make it possible to make a copy of a <code>SerialBlob</code>
  69 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 <code>Blob</code> object within a <code>SerialBlob</code>
  71 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 <code>SerialClob</code> class provides a constructor for creating an instance
  78 from a <code>Clob</code> object. Note that the <code>Clob</code> object should have
  79 brought the SQL CLOB value's data over to the client before a <code>SerialClob</code>
  80 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 <code>SerialClob</code> methods make it possible to get a substring from a
  84 <code>SerialClob</code> 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 originating data source manages. <br>
  91 <br>
  92 <code>RowSet</code> implementations can use the method <code>RowSet.getURL()</code> to retrieve
  93 a <code>java.net.URL</code> object, which can be used to manipulate the external data.
  94 <br>
  95 <br>
  96 &nbsp;&nbsp;<code>&nbsp;&nbsp;&nbsp; java.net.URL url = rowset.getURL(1);</code><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 <code>SerialException</code> 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 <code>SerialRef</code> class provides a constructor for creating a <code>SerialRef</code>
 114 instance from a <code>Ref</code> type and provides methods for getting
 115 and setting the <code>Ref</code> 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 <code>SerialStruct</code> class provides a constructor for creating an
 128 instance  from a <code>Struct</code> 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   <code>SQLInputImpl</code> 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 <code>getObject</code> is called on an SQL structured or distinct
 138 type that has a custom mapping; a programmer never invokes <code>SQLInputImpl</code>
 139 methods directly. <br>
 140   <br>
 141 The <code>SQLInputImpl</code> class provides a set of reader methods
 142 analogous to the <code>ResultSet</code> getter methods. These methods make it
 143 possible to read the values in an <code>SQLInputImpl</code> object. The method
 144 <code>wasNull</code> is used to determine whether 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 <code>SQLData.getSQLType</code> 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 <code>SQLData.readSQL</code>,  which in turn calls the <code>SQLInputImpl</code>
 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 <code>PreparedStatement.setObject</code>, 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 <code>SQLData</code> for this UDT. If the
 165 value to be written is an instance of <code>SQLData</code>, the driver will
 166 create  an instance of <code>SQLOutputImpl</code> and pass it to the method
 167 <code>SQLData.writeSQL</code>.
 168 The method <code>writeSQL</code> in turn calls the appropriate <code>SQLOutputImpl</code>
 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>
   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  * &nbsp;&nbsp;<code>&nbsp;&nbsp;&nbsp; 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;












< prev index next >