1 /*
2 * Copyright 1998-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.sql;
27
28 /**
29 * The output stream for writing the attributes of a user-defined
30 * type back to the database. This interface, used
31 * only for custom mapping, is used by the driver, and its
32 * methods are never directly invoked by a programmer.
33 * <p>When an object of a class implementing the interface
34 * <code>SQLData</code> is passed as an argument to an SQL statement, the
35 * JDBC driver calls the method <code>SQLData.getSQLType</code> to
36 * determine the kind of SQL
37 * datum being passed to the database.
38 * The driver then creates an instance of <code>SQLOutput</code> and
39 * passes it to the method <code>SQLData.writeSQL</code>.
40 * The method <code>writeSQL</code> in turn calls the
41 * appropriate <code>SQLOutput</code> <i>writer</i> methods
42 * <code>writeBoolean</code>, <code>writeCharacterStream</code>, and so on)
43 * to write data from the <code>SQLData</code> object to
44 * the <code>SQLOutput</code> output stream as the
45 * representation of an SQL user-defined type.
46 * @since 1.2
47 */
48
49 public interface SQLOutput {
50
51 //================================================================
52 // Methods for writing attributes to the stream of SQL data.
53 // These methods correspond to the column-accessor methods of
54 // java.sql.ResultSet.
55 //================================================================
56
57 /**
58 * Writes the next attribute to the stream as a <code>String</code>
59 * in the Java programming language.
60 *
61 * @param x the value to pass to the database
62 * @exception SQLException if a database access error occurs
63 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
64 * this method
65 * @since 1.2
66 */
67 void writeString(String x) throws SQLException;
68
69 /**
70 * Writes the next attribute to the stream as a Java boolean.
71 * Writes the next attribute to the stream as a <code>String</code>
72 * in the Java programming language.
73 *
74 * @param x the value to pass to the database
75 * @exception SQLException if a database access error occurs
76 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
77 * this method
78 * @since 1.2
79 */
80 void writeBoolean(boolean x) throws SQLException;
81
82 /**
83 * Writes the next attribute to the stream as a Java byte.
84 * Writes the next attribute to the stream as a <code>String</code>
85 * in the Java programming language.
86 *
87 * @param x the value to pass to the database
88 * @exception SQLException if a database access error occurs
89 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90 * this method
91 * @since 1.2
92 */
93 void writeByte(byte x) throws SQLException;
94
95 /**
96 * Writes the next attribute to the stream as a Java short.
97 * Writes the next attribute to the stream as a <code>String</code>
98 * in the Java programming language.
99 *
100 * @param x the value to pass to the database
101 * @exception SQLException if a database access error occurs
102 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
103 * this method
104 * @since 1.2
105 */
106 void writeShort(short x) throws SQLException;
107
108 /**
109 * Writes the next attribute to the stream as a Java int.
110 * Writes the next attribute to the stream as a <code>String</code>
111 * in the Java programming language.
112 *
113 * @param x the value to pass to the database
114 * @exception SQLException if a database access error occurs
115 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
116 * this method
117 * @since 1.2
118 */
119 void writeInt(int x) throws SQLException;
120
121 /**
122 * Writes the next attribute to the stream as a Java long.
123 * Writes the next attribute to the stream as a <code>String</code>
124 * in the Java programming language.
125 *
126 * @param x the value to pass to the database
127 * @exception SQLException if a database access error occurs
128 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
129 * this method
130 * @since 1.2
131 */
132 void writeLong(long x) throws SQLException;
133
134 /**
135 * Writes the next attribute to the stream as a Java float.
136 * Writes the next attribute to the stream as a <code>String</code>
137 * in the Java programming language.
138 *
139 * @param x the value to pass to the database
140 * @exception SQLException if a database access error occurs
141 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
142 * this method
143 * @since 1.2
144 */
145 void writeFloat(float x) throws SQLException;
146
147 /**
148 * Writes the next attribute to the stream as a Java double.
149 * Writes the next attribute to the stream as a <code>String</code>
150 * in the Java programming language.
151 *
152 * @param x the value to pass to the database
153 * @exception SQLException if a database access error occurs
154 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
155 * this method
156 * @since 1.2
157 */
158 void writeDouble(double x) throws SQLException;
159
160 /**
161 * Writes the next attribute to the stream as a java.math.BigDecimal object.
162 * Writes the next attribute to the stream as a <code>String</code>
163 * in the Java programming language.
164 *
165 * @param x the value to pass to the database
166 * @exception SQLException if a database access error occurs
167 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
168 * this method
169 * @since 1.2
170 */
171 void writeBigDecimal(java.math.BigDecimal x) throws SQLException;
172
173 /**
174 * Writes the next attribute to the stream as an array of bytes.
175 * Writes the next attribute to the stream as a <code>String</code>
176 * in the Java programming language.
177 *
178 * @param x the value to pass to the database
179 * @exception SQLException if a database access error occurs
180 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
181 * this method
182 * @since 1.2
183 */
184 void writeBytes(byte[] x) throws SQLException;
185
186 /**
187 * Writes the next attribute to the stream as a java.sql.Date object.
188 * Writes the next attribute to the stream as a <code>java.sql.Date</code> object
189 * in the Java programming language.
190 *
191 * @param x the value to pass to the database
192 * @exception SQLException if a database access error occurs
193 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
194 * this method
195 * @since 1.2
196 */
197 void writeDate(java.sql.Date x) throws SQLException;
198
199 /**
200 * Writes the next attribute to the stream as a java.sql.Time object.
201 * Writes the next attribute to the stream as a <code>java.sql.Date</code> object
202 * in the Java programming language.
203 *
204 * @param x the value to pass to the database
205 * @exception SQLException if a database access error occurs
206 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
207 * this method
208 * @since 1.2
209 */
210 void writeTime(java.sql.Time x) throws SQLException;
211
212 /**
213 * Writes the next attribute to the stream as a java.sql.Timestamp object.
214 * Writes the next attribute to the stream as a <code>java.sql.Date</code> object
215 * in the Java programming language.
216 *
217 * @param x the value to pass to the database
218 * @exception SQLException if a database access error occurs
219 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
220 * this method
221 * @since 1.2
222 */
223 void writeTimestamp(java.sql.Timestamp x) throws SQLException;
224
225 /**
226 * Writes the next attribute to the stream as a stream of Unicode characters.
227 *
228 * @param x the value to pass to the database
229 * @exception SQLException if a database access error occurs
230 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
231 * this method
232 * @since 1.2
233 */
234 void writeCharacterStream(java.io.Reader x) throws SQLException;
235
236 /**
237 * Writes the next attribute to the stream as a stream of ASCII characters.
238 *
239 * @param x the value to pass to the database
240 * @exception SQLException if a database access error occurs
241 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
242 * this method
243 * @since 1.2
244 */
245 void writeAsciiStream(java.io.InputStream x) throws SQLException;
246
247 /**
248 * Writes the next attribute to the stream as a stream of uninterpreted
249 * bytes.
250 *
251 * @param x the value to pass to the database
252 * @exception SQLException if a database access error occurs
253 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
254 * this method
255 * @since 1.2
256 */
257 void writeBinaryStream(java.io.InputStream x) throws SQLException;
258
259 //================================================================
260 // Methods for writing items of SQL user-defined types to the stream.
261 // These methods pass objects to the database as values of SQL
262 // Structured Types, Distinct Types, Constructed Types, and Locator
263 // Types. They decompose the Java object(s) and write leaf data
264 // items using the methods above.
265 //================================================================
266
267 /**
268 * Writes to the stream the data contained in the given
269 * <code>SQLData</code> object.
270 * When the <code>SQLData</code> object is <code>null</code>, this
271 * method writes an SQL <code>NULL</code> to the stream.
272 * Otherwise, it calls the <code>SQLData.writeSQL</code>
273 * method of the given object, which
274 * writes the object's attributes to the stream.
275 * The implementation of the method <code>SQLData.writeSQ</code>
276 * calls the appropriate <code>SQLOutput</code> writer method(s)
277 * for writing each of the object's attributes in order.
278 * The attributes must be read from an <code>SQLInput</code>
279 * input stream and written to an <code>SQLOutput</code>
280 * output stream in the same order in which they were
281 * listed in the SQL definition of the user-defined type.
282 *
283 * @param x the object representing data of an SQL structured or
284 * distinct type
285 * @exception SQLException if a database access error occurs
286 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
287 * this method
288 * @since 1.2
289 */
290 void writeObject(SQLData x) throws SQLException;
291
292 /**
293 * Writes an SQL <code>REF</code> value to the stream.
294 *
295 * @param x a <code>Ref</code> object representing data of an SQL
296 * <code>REF</code> value
297 * @exception SQLException if a database access error occurs
298 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
299 * this method
300 * @since 1.2
301 */
302 void writeRef(Ref x) throws SQLException;
303
304 /**
305 * Writes an SQL <code>BLOB</code> value to the stream.
306 *
307 * @param x a <code>Blob</code> object representing data of an SQL
308 * <code>BLOB</code> value
309 *
310 * @exception SQLException if a database access error occurs
311 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
312 * this method
313 * @since 1.2
314 */
315 void writeBlob(Blob x) throws SQLException;
316
317 /**
318 * Writes an SQL <code>CLOB</code> value to the stream.
319 *
320 * @param x a <code>Clob</code> object representing data of an SQL
321 * <code>CLOB</code> value
322 *
323 * @exception SQLException if a database access error occurs
324 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
325 * this method
326 * @since 1.2
327 */
328 void writeClob(Clob x) throws SQLException;
329
330 /**
331 * Writes an SQL structured type value to the stream.
332 *
333 * @param x a <code>Struct</code> object representing data of an SQL
334 * structured type
335 *
336 * @exception SQLException if a database access error occurs
337 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
338 * this method
339 * @since 1.2
340 */
341 void writeStruct(Struct x) throws SQLException;
342
343 /**
344 * Writes an SQL <code>ARRAY</code> value to the stream.
345 *
346 * @param x an <code>Array</code> object representing data of an SQL
347 * <code>ARRAY</code> type
348 *
349 * @exception SQLException if a database access error occurs
350 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
351 * this method
352 * @since 1.2
353 */
354 void writeArray(Array x) throws SQLException;
355
356 //--------------------------- JDBC 3.0 ------------------------
357
358 /**
359 * Writes a SQL <code>DATALINK</code> value to the stream.
360 *
361 * @param x a <code>java.net.URL</code> object representing the data
362 * of SQL DATALINK type
363 *
364 * @exception SQLException if a database access error occurs
365 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
366 * this method
367 * @since 1.4
368 */
369 void writeURL(java.net.URL x) throws SQLException;
370
371 //--------------------------- JDBC 4.0 ------------------------
372
373 /**
374 * Writes the next attribute to the stream as a <code>String</code>
375 * in the Java programming language. The driver converts this to a
376 * SQL <code>NCHAR</code> or
377 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
378 * (depending on the argument's
379 * size relative to the driver's limits on <code>NVARCHAR</code> values)
380 * when it sends it to the stream.
381 *
382 * @param x the value to pass to the database
383 * @exception SQLException if a database access error occurs
384 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
385 * this method
386 * @since 1.6
387 */
388 void writeNString(String x) throws SQLException;
389
390 /**
391 * Writes an SQL <code>NCLOB</code> value to the stream.
392 *
393 * @param x a <code>NClob</code> object representing data of an SQL
394 * <code>NCLOB</code> value
395 *
396 * @exception SQLException if a database access error occurs
397 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
398 * this method
399 * @since 1.6
400 */
401 void writeNClob(NClob x) throws SQLException;
402
403
404 /**
405 * Writes an SQL <code>ROWID</code> value to the stream.
406 *
407 * @param x a <code>RowId</code> object representing data of an SQL
408 * <code>ROWID</code> value
409 *
410 * @exception SQLException if a database access error occurs
411 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
412 * this method
413 * @since 1.6
414 */
415 void writeRowId(RowId x) throws SQLException;
416
417
418 /**
419 * Writes an SQL <code>XML</code> value to the stream.
420 *
421 * @param x a <code>SQLXML</code> object representing data of an SQL
422 * <code>XML</code> value
423 *
424 * @throws SQLException if a database access error occurs,
425 * the <code>java.xml.transform.Result</code>,
426 * <code>Writer</code> or <code>OutputStream</code> has not been closed for the <code>SQLXML</code> object or
427 * if there is an error processing the XML value. The <code>getCause</code> method
428 * of the exception may provide a more detailed exception, for example, if the
429 * stream does not contain valid XML.
430 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
431 * this method
432 * @since 1.6
433 */
434 void writeSQLXML(SQLXML x) throws SQLException;
435
436
437 }
Save This Page