< 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,239 +1,227 @@
-<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
-<html>
-<head>
-
- <meta http-equiv="Content-Type"
- content="text/html; charset=iso-8859-1">
-
- <meta name="GENERATOR"
- content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]">
-<!--
-Copyright (c) 2003, 2006, 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.
--->
-<title>javax.sql.rowset.serial</title>
-</head>
-<body bgcolor="#ffffff">
-Provides utility classes to allow serializable mappings between SQL types
-and data types in the Java programming language.
-<p> Standard JDBC <code>RowSet</code> implementations may use these utility
-classes to
-assist in the serialization of disconnected <code>RowSet</code> objects.
-This is useful
-when transmitting a disconnected <code>RowSet</code> object over the wire to
-a different VM or across layers within an application.<br>
-</p>
-
-<h3>1.0 SerialArray</h3>
-A serializable mapping in the Java programming language of an SQL ARRAY
-value. <br>
-<br>
-The <code>SerialArray</code> class provides a constructor for creating a <code>SerialArray</code>
-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
-<code>SerialArray</code> object. <br>
-
-<h3>2.0 SerialBlob</h3>
-A serializable mapping in the Java programming language of an SQL BLOB
-value. <br>
-<br>
-The <code>SerialBlob</code>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 <code>SerialBlob</code>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 <code>Blob.getBytes</code>)
-or as a stream of uninterpreted bytes (using the method <code>Blob.getBinaryStream</code>).
-<br>
-<br>
-<code>SerialBlob</code> methods make it possible to make a copy of a <code>SerialBlob</code>
-object as an array of bytes or as a stream. They also make it possible
-to locate a given pattern of bytes or a <code>Blob</code> object within a <code>SerialBlob</code>
-object. <br>
-
-<h3>3.0 SerialClob</h3>
-A serializable mapping in the Java programming language of an SQL CLOB
-value. <br>
-<br>
-The <code>SerialClob</code> class provides a constructor for creating an instance
-from a <code>Clob</code> object. Note that the <code>Clob</code> object should have
-brought the SQL CLOB value's data over to the client before a <code>SerialClob</code>
-object is constructed from it. The data of an SQL CLOB value can be
-materialized on the client as a stream of Unicode characters. <br>
-<br>
-<code>SerialClob</code> methods make it possible to get a substring from a
-<code>SerialClob</code> object or to locate the start of a pattern of characters.
-<br>
-
-<h3>5.0 SerialDatalink</h3>
-A serializable mapping in the Java programming language of an SQL DATALINK
-value. A DATALINK value references a file outside of the underlying data source
-that the originating data source manages. <br>
-<br>
-<code>RowSet</code> implementations can use the method <code>RowSet.getURL()</code> to retrieve
-a <code>java.net.URL</code> object, which can be used to manipulate the external data.
-<br>
-<br>
- <code> java.net.URL url = rowset.getURL(1);</code><br>
-
-<h3>6.0 SerialJavaObject</h3>
-A serializable mapping in the Java programming language of an SQL JAVA_OBJECT
-value. Assuming the Java object instance implements the Serializable interface,
-this simply wraps the serialization process. <br>
-<br>
-If however, the serialization is not possible in the case where the Java
-object is not immediately serializable, this class will attempt to serialize
-all non static members to permit the object instance state to be serialized.
-Static or transient fields cannot be serialized and attempting to do so
-will result in a <code>SerialException</code> being thrown. <br>
-
-<h3>7.0 SerialRef</h3>
-A serializable mapping between the SQL REF type and the Java programming
-language. <br>
-<br>
-The <code>SerialRef</code> class provides a constructor for creating a <code>SerialRef</code>
-instance from a <code>Ref</code> type and provides methods for getting
-and setting the <code>Ref</code> object type. <br>
-
-<h3>8.0 SerialStruct</h3>
-A serializable mapping in the Java programming language of an SQL structured
-type. Each attribute that is not already serializable is mapped to a serializable
-form, and if an attribute is itself a structured type, each of its attributes
-that is not already serializable is mapped to a serializable form. <br>
-<br>
-In addition, if a <code>Map</code> object is passed to one of the constructors or
-to the method <code>getAttributes</code>, the structured type is custom mapped
-according to the mapping specified in the <code>Map</code> object.
-<br>
-The <code>SerialStruct</code> class provides a constructor for creating an
-instance from a <code>Struct</code> object, a method for retrieving the SQL
-type name of the SQL structured type in the database, and methods for retrieving
-its attribute values. <br>
-
-<h3>9.0 SQLInputImpl</h3>
- An input stream used for custom mapping user-defined types (UDTs). An
- <code>SQLInputImpl</code> 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 <code>getObject</code> is called on an SQL structured or distinct
-type that has a custom mapping; a programmer never invokes <code>SQLInputImpl</code>
-methods directly. <br>
- <br>
-The <code>SQLInputImpl</code> class provides a set of reader methods
-analogous to the <code>ResultSet</code> getter methods. These methods make it
-possible to read the values in an <code>SQLInputImpl</code> object. The method
-<code>wasNull</code> is used to determine whether the last value read was SQL NULL.
-<br>
- <br>
-When a constructor or getter method that takes a <code>Map</code> object is called,
-the JDBC driver calls the method
-<code>SQLData.getSQLType</code> to determine the SQL type of the UDT being custom
-mapped. The driver creates an instance of <code>SQLInputImpl</code>, populating it with
-the attributes of the UDT. The driver then passes the input stream to the
-method <code>SQLData.readSQL</code>, which in turn calls the <code>SQLInputImpl</code>
-methods to read the attributes from the input stream. <br>
-
-<h3>10.0 SQLOutputImpl</h3>
- The output stream for writing the attributes of a custom mapped user-defined
- type (UDT) back to the database. The driver uses this interface internally,
- and its methods are never directly invoked by an application programmer.
-<br>
- <br>
-When an application calls the method <code>PreparedStatement.setObject</code>, 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 <code>SQLData</code> for this UDT. If the
-value to be written is an instance of <code>SQLData</code>, the driver will
-create an instance of <code>SQLOutputImpl</code> and pass it to the method
-<code>SQLData.writeSQL</code>.
-The method <code>writeSQL</code> in turn calls the appropriate <code>SQLOutputImpl</code>
-writer methods to write data from the <code>SQLData</code> object to the
-<code>SQLOutputImpl</code>
-output stream as the representation of an SQL user-defined type.
-
-<h3>Custom Mapping</h3>
-The JDBC API provides mechanisms for mapping an SQL structured type or DISTINCT
-type to the Java programming language. Typically, a structured type is mapped
-to a class, and its attributes are mapped to fields in the class.
-(A DISTINCT type can thought of as having one attribute.) However, there are
-many other possibilities, and there may be any number of different mappings.
-<P>
-A programmer defines the mapping by implementing the interface <code>SQLData</code>.
-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
-<code>SQLData</code> could look like the following:
-<PRE>
- 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);
- }
- }
-</PRE>
-
-A <code>java.util.Map</code> object is used to associate the SQL structured
-type with its mapping to the class <code>Authors</code>. The following code fragment shows
-how a <code>Map</code> object might be created and given an entry associating
-<code>AUTHORS</code> and <code>Authors</code>.
-<PRE>
- java.util.Map map = new java.util.HashMap();
- map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");
-</PRE>
-
-The <code>Map</code> object <i>map</i> now contains an entry with the
-fully qualified name of the SQL structured type and the <code>Class</code>
- object for the class <code>Authors</code>. It can be passed to a method
-to tell the driver how to map <code>AUTHORS</code> to <code>Authors</code>.
-<P>
-For a disconnected <code>RowSet</code> object, custom mapping can be done
-only when a <code>Map</code> object is passed to the method or constructor
-that will be doing the custom mapping. The situation is different for
-connected <code>RowSet</code> objects because they maintain a connection
-with the data source. A method that does custom mapping and is called by
-a disconnected <code>RowSet</code> object may use the <code>Map</code>
-object that is associated with the <code>Connection</code> object being
-used. So, in other words, if no map is specified, the connection's type
-map can be used by default.
-
-<br>
-</body>
-</html>
+/*
+ * 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.
+ * <p> Standard JDBC <code>RowSet</code> implementations may use these utility
+ * classes to
+ * assist in the serialization of disconnected <code>RowSet</code> objects.
+ * This is useful
+ * when transmitting a disconnected <code>RowSet</code> object over the wire to
+ * a different VM or across layers within an application.<br>
+ * </p>
+ *
+ * <h3>1.0 SerialArray</h3>
+ * A serializable mapping in the Java programming language of an SQL ARRAY
+ * value. <br>
+ * <br>
+ * The <code>SerialArray</code> class provides a constructor for creating a <code>SerialArray</code>
+ * 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
+ * <code>SerialArray</code> object. <br>
+ *
+ * <h3>2.0 SerialBlob</h3>
+ * A serializable mapping in the Java programming language of an SQL BLOB
+ * value. <br>
+ * <br>
+ * The <code>SerialBlob</code>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 <code>SerialBlob</code>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 <code>Blob.getBytes</code>)
+ * or as a stream of uninterpreted bytes (using the method <code>Blob.getBinaryStream</code>).
+ * <br>
+ * <br>
+ * <code>SerialBlob</code> methods make it possible to make a copy of a <code>SerialBlob</code>
+ * object as an array of bytes or as a stream. They also make it possible
+ * to locate a given pattern of bytes or a <code>Blob</code> object within a <code>SerialBlob</code>
+ * object. <br>
+ *
+ * <h3>3.0 SerialClob</h3>
+ * A serializable mapping in the Java programming language of an SQL CLOB
+ * value. <br>
+ * <br>
+ * The <code>SerialClob</code> class provides a constructor for creating an instance
+ * from a <code>Clob</code> object. Note that the <code>Clob</code> object should have
+ * brought the SQL CLOB value's data over to the client before a <code>SerialClob</code>
+ * object is constructed from it. The data of an SQL CLOB value can be
+ * materialized on the client as a stream of Unicode characters. <br>
+ * <br>
+ * <code>SerialClob</code> methods make it possible to get a substring from a
+ * <code>SerialClob</code> object or to locate the start of a pattern of characters.
+ * <br>
+ *
+ * <h3>5.0 SerialDatalink</h3>
+ * A serializable mapping in the Java programming language of an SQL DATALINK
+ * value. A DATALINK value references a file outside of the underlying data source
+ * that the originating data source manages. <br>
+ * <br>
+ * <code>RowSet</code> implementations can use the method <code>RowSet.getURL()</code> to retrieve
+ * a <code>java.net.URL</code> object, which can be used to manipulate the external data.
+ * <br>
+ * <br>
+ * <code> java.net.URL url = rowset.getURL(1);</code><br>
+ *
+ * <h3>6.0 SerialJavaObject</h3>
+ * A serializable mapping in the Java programming language of an SQL JAVA_OBJECT
+ * value. Assuming the Java object instance implements the Serializable interface,
+ * this simply wraps the serialization process. <br>
+ * <br>
+ * If however, the serialization is not possible in the case where the Java
+ * object is not immediately serializable, this class will attempt to serialize
+ * all non static members to permit the object instance state to be serialized.
+ * Static or transient fields cannot be serialized and attempting to do so
+ * will result in a <code>SerialException</code> being thrown. <br>
+ *
+ * <h3>7.0 SerialRef</h3>
+ * A serializable mapping between the SQL REF type and the Java programming
+ * language. <br>
+ * <br>
+ * The <code>SerialRef</code> class provides a constructor for creating a <code>SerialRef</code>
+ * instance from a <code>Ref</code> type and provides methods for getting
+ * and setting the <code>Ref</code> object type. <br>
+ *
+ * <h3>8.0 SerialStruct</h3>
+ * A serializable mapping in the Java programming language of an SQL structured
+ * type. Each attribute that is not already serializable is mapped to a serializable
+ * form, and if an attribute is itself a structured type, each of its attributes
+ * that is not already serializable is mapped to a serializable form. <br>
+ * <br>
+ * In addition, if a <code>Map</code> object is passed to one of the constructors or
+ * to the method <code>getAttributes</code>, the structured type is custom mapped
+ * according to the mapping specified in the <code>Map</code> object.
+ * <br>
+ * The <code>SerialStruct</code> class provides a constructor for creating an
+ * instance from a <code>Struct</code> object, a method for retrieving the SQL
+ * type name of the SQL structured type in the database, and methods for retrieving
+ * its attribute values. <br>
+ *
+ * <h3>9.0 SQLInputImpl</h3>
+ * An input stream used for custom mapping user-defined types (UDTs). An
+ * <code>SQLInputImpl</code> 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 <code>getObject</code> is called on an SQL structured or distinct
+ * type that has a custom mapping; a programmer never invokes <code>SQLInputImpl</code>
+ * methods directly. <br>
+ * <br>
+ * The <code>SQLInputImpl</code> class provides a set of reader methods
+ * analogous to the <code>ResultSet</code> getter methods. These methods make it
+ * possible to read the values in an <code>SQLInputImpl</code> object. The method
+ * <code>wasNull</code> is used to determine whether the last value read was SQL NULL.
+ * <br>
+ * <br>
+ * When a constructor or getter method that takes a <code>Map</code> object is called,
+ * the JDBC driver calls the method
+ * <code>SQLData.getSQLType</code> to determine the SQL type of the UDT being custom
+ * mapped. The driver creates an instance of <code>SQLInputImpl</code>, populating it with
+ * the attributes of the UDT. The driver then passes the input stream to the
+ * method <code>SQLData.readSQL</code>, which in turn calls the <code>SQLInputImpl</code>
+ * methods to read the attributes from the input stream. <br>
+ *
+ * <h3>10.0 SQLOutputImpl</h3>
+ * The output stream for writing the attributes of a custom mapped user-defined
+ * type (UDT) back to the database. The driver uses this interface internally,
+ * and its methods are never directly invoked by an application programmer.
+ * <br>
+ * <br>
+ * When an application calls the method <code>PreparedStatement.setObject</code>, 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 <code>SQLData</code> for this UDT. If the
+ * value to be written is an instance of <code>SQLData</code>, the driver will
+ * create an instance of <code>SQLOutputImpl</code> and pass it to the method
+ * <code>SQLData.writeSQL</code>.
+ * The method <code>writeSQL</code> in turn calls the appropriate <code>SQLOutputImpl</code>
+ * writer methods to write data from the <code>SQLData</code> object to the
+ * <code>SQLOutputImpl</code>
+ * output stream as the representation of an SQL user-defined type.
+ *
+ * <h3>Custom Mapping</h3>
+ * The JDBC API provides mechanisms for mapping an SQL structured type or DISTINCT
+ * type to the Java programming language. Typically, a structured type is mapped
+ * to a class, and its attributes are mapped to fields in the class.
+ * (A DISTINCT type can thought of as having one attribute.) However, there are
+ * many other possibilities, and there may be any number of different mappings.
+ * <P>
+ * A programmer defines the mapping by implementing the interface <code>SQLData</code>.
+ * 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
+ * <code>SQLData</code> could look like the following:
+ * <PRE>
+ * 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);
+ * }
+ * }
+ * </PRE>
+ *
+ * A <code>java.util.Map</code> object is used to associate the SQL structured
+ * type with its mapping to the class <code>Authors</code>. The following code fragment shows
+ * how a <code>Map</code> object might be created and given an entry associating
+ * <code>AUTHORS</code> and <code>Authors</code>.
+ * <PRE>
+ * java.util.Map map = new java.util.HashMap();
+ * map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");
+ * </PRE>
+ *
+ * The <code>Map</code> object <i>map</i> now contains an entry with the
+ * fully qualified name of the SQL structured type and the <code>Class</code>
+ * object for the class <code>Authors</code>. It can be passed to a method
+ * to tell the driver how to map <code>AUTHORS</code> to <code>Authors</code>.
+ * <P>
+ * For a disconnected <code>RowSet</code> object, custom mapping can be done
+ * only when a <code>Map</code> object is passed to the method or constructor
+ * that will be doing the custom mapping. The situation is different for
+ * connected <code>RowSet</code> objects because they maintain a connection
+ * with the data source. A method that does custom mapping and is called by
+ * a disconnected <code>RowSet</code> object may use the <code>Map</code>
+ * object that is associated with the <code>Connection</code> 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;
< prev index next >