| author | chegar |
| Mon, 18 Aug 2014 10:59:36 +0100 | |
| changeset 25991 | e48157b42439 |
| parent 25976 | jdk/src/share/classes/javax/sql/rowset/serial/package.html@4de01a56e3ee |
| parent 25859 | jdk/src/share/classes/javax/sql/rowset/serial/package.html@3317bb8137f4 |
| child 32210 | 958d823579c3 |
| permissions | -rw-r--r-- |
| 2 | 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 |
<!-- |
|
| 5506 | 11 |
Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved. |
| 2 | 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 |
|
| 5506 | 16 |
published by the Free Software Foundation. Oracle designates this |
| 2 | 17 |
particular file as subject to the "Classpath" exception as provided |
| 5506 | 18 |
by Oracle in the LICENSE file that accompanied this code. |
| 2 | 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 |
||
|
5551
327690766109
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5506
diff
changeset
|
30 |
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
327690766109
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5506
diff
changeset
|
31 |
or visit www.oracle.com if you need additional information or have any |
|
327690766109
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5506
diff
changeset
|
32 |
questions. |
| 2 | 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 <tt>RowSet</tt> 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 <tt>SerialArray </tt>class provides a constructor for creating a <tt>SerialArray |
|
52 |
</tt>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 |
<tt>SerialArray </tt>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 <tt>SerialBlob </tt>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 <tt>SerialBlob </tt>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 <tt>Blob.getBytes</tt>) |
|
65 |
or as a stream of uninterpreted bytes (using the method <tt>Blob.getBinaryStream</tt>). |
|
66 |
<br> |
|
67 |
<br> |
|
68 |
<tt>SerialBlob </tt>methods make it possible to make a copy of a <tt>SerialBlob |
|
69 |
</tt>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 <tt>Blob </tt>object within a <tt>SerialBlob |
|
71 |
</tt>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 <tt>SerialClob </tt>class provides a constructor for creating an instance |
|
78 |
from a <tt>Clob </tt>object. Note that the <tt>Clob </tt>object should have |
|
79 |
brought the SQL CLOB value's data over to the client before a <tt>SerialClob |
|
80 |
</tt>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 |
<tt>SerialClob </tt>methods make it possible to get a substring from a |
|
84 |
<tt>SerialClob </tt>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 |
|
|
25976
4de01a56e3ee
8054555: javadoc cleanup for java.sql and javax.sql
lancea
parents:
5551
diff
changeset
|
90 |
that the originating data source manages. <br> |
| 2 | 91 |
<br> |
92 |
<code>RowSet</code> implementations can use the method <tt>RowSet.getURL() </tt>to retrieve |
|
93 |
a <code>java.net.URL</code> object, which can be used to manipulate the external data. |
|
94 |
<br> |
|
95 |
<br> |
|
96 |
<tt> java.net.URL url = rowset.getURL(1);</tt><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 <tt>SerialException </tt>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 <tt>SerialRef </tt>class provides a constructor for creating a <tt>SerialRef |
|
114 |
</tt>instance from a <tt>Ref</tt> type and provides methods for getting |
|
115 |
and setting the <tt>Ref</tt> 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 <tt>SerialStruct </tt>class provides a constructor for creating an |
|
128 |
instance from a <tt>Struct</tt> 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 |
<tt>SQLInputImpl</tt> 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 <tt>getObject</tt> is called on an SQL structured or distinct |
|
138 |
type that has a custom mapping; a programmer never invokes <tt>SQLInputImpl |
|
139 |
</tt> methods directly. <br> |
|
140 |
<br> |
|
141 |
The <tt>SQLInputImpl</tt> class provides a set of reader methods |
|
142 |
analogous to the <tt>ResultSet</tt> getter methods. These methods make it |
|
143 |
possible to read the values in an <tt>SQLInputImpl</tt> object. The method |
|
|
25976
4de01a56e3ee
8054555: javadoc cleanup for java.sql and javax.sql
lancea
parents:
5551
diff
changeset
|
144 |
<code>wasNull</code> is used to determine whether the last value read was SQL NULL. |
| 2 | 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 |
<tt>SQLData.getSQLType</tt> 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 <tt>SQLData.readSQL</tt>, which in turn calls the <tt>SQLInputImpl</tt> |
|
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 <tt>PreparedStatement.setObject, </tt>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 <tt>SQLData </tt>for this UDT. If the |
|
165 |
value to be written is an instance of <tt>SQLData</tt>, the driver will |
|
166 |
create an instance of <code>SQLOutputImpl</code> and pass it to the method |
|
167 |
<tt>SQLData.writeSQL</tt>. |
|
168 |
The method <code>writeSQL</code> in turn calls the appropriate <tt>SQLOutputImpl</tt> |
|
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> |