| <!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> |