001 /*
002 * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.sql;
027
028 /**
029 * The output stream for writing the attributes of a user-defined
030 * type back to the database. This interface, used
031 * only for custom mapping, is used by the driver, and its
032 * methods are never directly invoked by a programmer.
033 * <p>When an object of a class implementing the interface
034 * <code>SQLData</code> is passed as an argument to an SQL statement, the
035 * JDBC driver calls the method <code>SQLData.getSQLType</code> to
036 * determine the kind of SQL
037 * datum being passed to the database.
038 * The driver then creates an instance of <code>SQLOutput</code> and
039 * passes it to the method <code>SQLData.writeSQL</code>.
040 * The method <code>writeSQL</code> in turn calls the
041 * appropriate <code>SQLOutput</code> <i>writer</i> methods
042 * <code>writeBoolean</code>, <code>writeCharacterStream</code>, and so on)
043 * to write data from the <code>SQLData</code> object to
044 * the <code>SQLOutput</code> output stream as the
045 * representation of an SQL user-defined type.
046 * @since 1.2
047 */
048
049 public interface SQLOutput {
050
051 //================================================================
052 // Methods for writing attributes to the stream of SQL data.
053 // These methods correspond to the column-accessor methods of
054 // java.sql.ResultSet.
055 //================================================================
056
057 /**
058 * Writes the next attribute to the stream as a <code>String</code>
059 * in the Java programming language.
060 *
061 * @param x the value to pass to the database
062 * @exception SQLException if a database access error occurs
063 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
064 * this method
065 * @since 1.2
066 */
067 void writeString(String x) throws SQLException;
068
069 /**
070 * Writes the next attribute to the stream as a Java boolean.
071 * Writes the next attribute to the stream as a <code>String</code>
072 * in the Java programming language.
073 *
074 * @param x the value to pass to the database
075 * @exception SQLException if a database access error occurs
076 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
077 * this method
078 * @since 1.2
079 */
080 void writeBoolean(boolean x) throws SQLException;
081
082 /**
083 * Writes the next attribute to the stream as a Java byte.
084 * Writes the next attribute to the stream as a <code>String</code>
085 * in the Java programming language.
086 *
087 * @param x the value to pass to the database
088 * @exception SQLException if a database access error occurs
089 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
090 * this method
091 * @since 1.2
092 */
093 void writeByte(byte x) throws SQLException;
094
095 /**
096 * Writes the next attribute to the stream as a Java short.
097 * Writes the next attribute to the stream as a <code>String</code>
098 * in the Java programming language.
099 *
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 * Writes an SQL <code>ROWID</code> value to the stream.
405 *
406 * @param x a <code>RowId</code> object representing data of an SQL
407 * <code>ROWID</code> value
408 *
409 * @exception SQLException if a database access error occurs
410 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
411 * this method
412 * @since 1.6
413 */
414 void writeRowId(RowId x) throws SQLException;
415
416 /**
417 * Writes an SQL <code>XML</code> value to the stream.
418 *
419 * @param x a <code>SQLXML</code> object representing data of an SQL
420 * <code>XML</code> value
421 *
422 * @throws SQLException if a database access error occurs,
423 * the <code>java.xml.transform.Result</code>,
424 * <code>Writer</code> or <code>OutputStream</code> has not been closed for the <code>SQLXML</code> object or
425 * if there is an error processing the XML value. The <code>getCause</code> method
426 * of the exception may provide a more detailed exception, for example, if the
427 * stream does not contain valid XML.
428 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
429 * this method
430 * @since 1.6
431 */
432 void writeSQLXML(SQLXML x) throws SQLException;
433
434 }
|