--- old/src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package.html 2018-12-12 14:01:39.380369275 -0500 +++ /dev/null 2018-12-11 14:42:27.088072338 -0500 @@ -1,239 +0,0 @@ - - -
- - - - - - Standard JDBC RowSet
implementations may use these utility
-classes to
-assist in the serialization of disconnected RowSet
objects.
-This is useful
-when transmitting a disconnected RowSet
object over the wire to
-a different VM or across layers within an application.
-
SerialArray
class provides a constructor for creating a SerialArray
-instance from an Array object, methods for getting the base type and
-the SQL name for the base type, and methods for copying all or part of a
-SerialArray
object. SerialBlob
class provides a constructor for creating an instance
-from a Blob object. Note that the Blob object should have brought the SQL
-BLOB value's data over to the client before a SerialBlob
object
-is constructed from it. The data of an SQL BLOB value can be materialized
-on the client as an array of bytes (using the method Blob.getBytes
)
-or as a stream of uninterpreted bytes (using the method Blob.getBinaryStream
).
-SerialBlob
methods make it possible to make a copy of a SerialBlob
-object as an array of bytes or as a stream. They also make it possible
-to locate a given pattern of bytes or a Blob
object within a SerialBlob
-object. SerialClob
class provides a constructor for creating an instance
-from a Clob
object. Note that the Clob
object should have
-brought the SQL CLOB value's data over to the client before a SerialClob
-object is constructed from it. The data of an SQL CLOB value can be
-materialized on the client as a stream of Unicode characters. SerialClob
methods make it possible to get a substring from a
-SerialClob
object or to locate the start of a pattern of characters.
-RowSet
implementations can use the method RowSet.getURL()
to retrieve
-a java.net.URL
object, which can be used to manipulate the external data.
- java.net.URL url = rowset.getURL(1);
SerialException
being thrown. SerialRef
class provides a constructor for creating a SerialRef
-instance from a Ref
type and provides methods for getting
-and setting the Ref
object type. Map
object is passed to one of the constructors or
-to the method getAttributes
, the structured type is custom mapped
-according to the mapping specified in the Map
object.
-SerialStruct
class provides a constructor for creating an
-instance from a Struct
object, a method for retrieving the SQL
-type name of the SQL structured type in the database, and methods for retrieving
-its attribute values. SQLInputImpl
object is an input stream that contains a stream of
- values that are
-the attributes of a UDT. This class is used by the driver behind the scenes
-when the method getObject
is called on an SQL structured or distinct
-type that has a custom mapping; a programmer never invokes SQLInputImpl
-methods directly. SQLInputImpl
class provides a set of reader methods
-analogous to the ResultSet
getter methods. These methods make it
-possible to read the values in an SQLInputImpl
object. The method
-wasNull
is used to determine whether the last value read was SQL NULL.
-Map
object is called,
-the JDBC driver calls the method
-SQLData.getSQLType
to determine the SQL type of the UDT being custom
-mapped. The driver creates an instance of SQLInputImpl
, populating it with
-the attributes of the UDT. The driver then passes the input stream to the
-method SQLData.readSQL
, which in turn calls the SQLInputImpl
-methods to read the attributes from the input stream. PreparedStatement.setObject
, the
-driver checks to see whether the value to be written is a UDT with a custom
-mapping. If it is, there will be an entry in a type map containing the Class
-object for the class that implements SQLData
for this UDT. If the
-value to be written is an instance of SQLData
, the driver will
-create an instance of SQLOutputImpl
and pass it to the method
-SQLData.writeSQL
.
-The method writeSQL
in turn calls the appropriate SQLOutputImpl
-writer methods to write data from the SQLData
object to the
-SQLOutputImpl
-output stream as the representation of an SQL user-defined type.
-
-
-A programmer defines the mapping by implementing the interface SQLData
.
-For example, if an SQL structured type named AUTHORS has the attributes NAME,
-TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The
-Authors class could have the fields name, title, and publisher, to which the
-attributes of AUTHORS are mapped. In such a case, the implementation of
-SQLData
could look like the following:
-
- public class Authors implements SQLData { - public String name; - public String title; - public String publisher; - - private String sql_type; - public String getSQLTypeName() { - return sql_type; - } - - public void readSQL(SQLInput stream, String type) - throws SQLException { - sql_type = type; - name = stream.readString(); - title = stream.readString(); - publisher = stream.readString(); - } - - public void writeSQL(SQLOutput stream) throws SQLException { - stream.writeString(name); - stream.writeString(title); - stream.writeString(publisher); - } - } -- -A
java.util.Map
object is used to associate the SQL structured
-type with its mapping to the class Authors
. The following code fragment shows
-how a Map
object might be created and given an entry associating
-AUTHORS
and Authors
.
-- java.util.Map map = new java.util.HashMap(); - map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors"); -- -The
Map
object map now contains an entry with the
-fully qualified name of the SQL structured type and the Class
- object for the class Authors
. It can be passed to a method
-to tell the driver how to map AUTHORS
to Authors
.
-
-For a disconnected RowSet
object, custom mapping can be done
-only when a Map
object is passed to the method or constructor
-that will be doing the custom mapping. The situation is different for
-connected RowSet
objects because they maintain a connection
-with the data source. A method that does custom mapping and is called by
-a disconnected RowSet
object may use the Map
-object that is associated with the Connection
object being
-used. So, in other words, if no map is specified, the connection's type
-map can be used by default.
-
-
-
-
--- /dev/null 2018-12-11 14:42:27.088072338 -0500
+++ new/src/java.sql.rowset/share/classes/javax/sql/rowset/serial/package-info.java 2018-12-12 14:01:39.104367906 -0500
@@ -0,0 +1,227 @@
+/*
+ * Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * Provides utility classes to allow serializable mappings between SQL types
+ * and data types in the Java programming language.
+ *
Standard JDBC RowSet
implementations may use these utility
+ * classes to
+ * assist in the serialization of disconnected RowSet
objects.
+ * This is useful
+ * when transmitting a disconnected RowSet
object over the wire to
+ * a different VM or across layers within an application.
+ *
SerialArray
class provides a constructor for creating a SerialArray
+ * instance from an Array object, methods for getting the base type and
+ * the SQL name for the base type, and methods for copying all or part of a
+ * SerialArray
object. SerialBlob
class provides a constructor for creating an instance
+ * from a Blob object. Note that the Blob object should have brought the SQL
+ * BLOB value's data over to the client before a SerialBlob
object
+ * is constructed from it. The data of an SQL BLOB value can be materialized
+ * on the client as an array of bytes (using the method Blob.getBytes
)
+ * or as a stream of uninterpreted bytes (using the method Blob.getBinaryStream
).
+ * SerialBlob
methods make it possible to make a copy of a SerialBlob
+ * object as an array of bytes or as a stream. They also make it possible
+ * to locate a given pattern of bytes or a Blob
object within a SerialBlob
+ * object. SerialClob
class provides a constructor for creating an instance
+ * from a Clob
object. Note that the Clob
object should have
+ * brought the SQL CLOB value's data over to the client before a SerialClob
+ * object is constructed from it. The data of an SQL CLOB value can be
+ * materialized on the client as a stream of Unicode characters. SerialClob
methods make it possible to get a substring from a
+ * SerialClob
object or to locate the start of a pattern of characters.
+ * RowSet
implementations can use the method RowSet.getURL()
to retrieve
+ * a java.net.URL
object, which can be used to manipulate the external data.
+ * java.net.URL url = rowset.getURL(1);
SerialException
being thrown. SerialRef
class provides a constructor for creating a SerialRef
+ * instance from a Ref
type and provides methods for getting
+ * and setting the Ref
object type. Map
object is passed to one of the constructors or
+ * to the method getAttributes
, the structured type is custom mapped
+ * according to the mapping specified in the Map
object.
+ * SerialStruct
class provides a constructor for creating an
+ * instance from a Struct
object, a method for retrieving the SQL
+ * type name of the SQL structured type in the database, and methods for retrieving
+ * its attribute values. SQLInputImpl
object is an input stream that contains a stream of
+ * values that are
+ * the attributes of a UDT. This class is used by the driver behind the scenes
+ * when the method getObject
is called on an SQL structured or distinct
+ * type that has a custom mapping; a programmer never invokes SQLInputImpl
+ * methods directly. SQLInputImpl
class provides a set of reader methods
+ * analogous to the ResultSet
getter methods. These methods make it
+ * possible to read the values in an SQLInputImpl
object. The method
+ * wasNull
is used to determine whether the last value read was SQL NULL.
+ * Map
object is called,
+ * the JDBC driver calls the method
+ * SQLData.getSQLType
to determine the SQL type of the UDT being custom
+ * mapped. The driver creates an instance of SQLInputImpl
, populating it with
+ * the attributes of the UDT. The driver then passes the input stream to the
+ * method SQLData.readSQL
, which in turn calls the SQLInputImpl
+ * methods to read the attributes from the input stream. PreparedStatement.setObject
, the
+ * driver checks to see whether the value to be written is a UDT with a custom
+ * mapping. If it is, there will be an entry in a type map containing the Class
+ * object for the class that implements SQLData
for this UDT. If the
+ * value to be written is an instance of SQLData
, the driver will
+ * create an instance of SQLOutputImpl
and pass it to the method
+ * SQLData.writeSQL
.
+ * The method writeSQL
in turn calls the appropriate SQLOutputImpl
+ * writer methods to write data from the SQLData
object to the
+ * SQLOutputImpl
+ * output stream as the representation of an SQL user-defined type.
+ *
+ *
+ * A programmer defines the mapping by implementing the interface SQLData
.
+ * For example, if an SQL structured type named AUTHORS has the attributes NAME,
+ * TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The
+ * Authors class could have the fields name, title, and publisher, to which the
+ * attributes of AUTHORS are mapped. In such a case, the implementation of
+ * SQLData
could look like the following:
+ *
+ * public class Authors implements SQLData { + * public String name; + * public String title; + * public String publisher; + * + * private String sql_type; + * public String getSQLTypeName() { + * return sql_type; + * } + * + * public void readSQL(SQLInput stream, String type) + * throws SQLException { + * sql_type = type; + * name = stream.readString(); + * title = stream.readString(); + * publisher = stream.readString(); + * } + * + * public void writeSQL(SQLOutput stream) throws SQLException { + * stream.writeString(name); + * stream.writeString(title); + * stream.writeString(publisher); + * } + * } + *+ * + * A
java.util.Map
object is used to associate the SQL structured
+ * type with its mapping to the class Authors
. The following code fragment shows
+ * how a Map
object might be created and given an entry associating
+ * AUTHORS
and Authors
.
+ * + * java.util.Map map = new java.util.HashMap(); + * map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors"); + *+ * + * The
Map
object map now contains an entry with the
+ * fully qualified name of the SQL structured type and the Class
+ * object for the class Authors
. It can be passed to a method
+ * to tell the driver how to map AUTHORS
to Authors
.
+ *
+ * For a disconnected RowSet
object, custom mapping can be done
+ * only when a Map
object is passed to the method or constructor
+ * that will be doing the custom mapping. The situation is different for
+ * connected RowSet
objects because they maintain a connection
+ * with the data source. A method that does custom mapping and is called by
+ * a disconnected RowSet
object may use the Map
+ * object that is associated with the Connection
object being
+ * used. So, in other words, if no map is specified, the connection's type
+ * map can be used by default.
+ */
+package javax.sql.rowset.serial;