1 /*
2  * Copyright (c) 1998, 2006, Oracle and/or its affiliates. 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.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * 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    */
writeString(String x)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    */
writeBoolean(boolean x)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    */
writeByte(byte x)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    */
writeShort(short x)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    */
writeInt(int x)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    */
writeLong(long x)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    */
writeFloat(float x)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    */
writeDouble(double x)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    */
writeBigDecimal(java.math.BigDecimal x)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    */
writeBytes(byte[] x)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    */
writeDate(java.sql.Date x)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    */
writeTime(java.sql.Time x)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    */
writeTimestamp(java.sql.Timestamp x)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    */
writeCharacterStream(java.io.Reader x)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    */
writeAsciiStream(java.io.InputStream x)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    */
writeBinaryStream(java.io.InputStream x)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    */
writeObject(SQLData x)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    */
writeRef(Ref x)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    */
writeBlob(Blob x)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    */
writeClob(Clob x)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    */
writeStruct(Struct x)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    */
writeArray(Array x)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       */
writeURL(java.net.URL x)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    */
writeNString(String x)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    */
writeNClob(NClob x)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    */
writeRowId(RowId x)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    */
writeSQLXML(SQLXML x)434   void writeSQLXML(SQLXML x) throws SQLException;
435 
436 
437 }
438