1 /* 2 * Copyright (c) 1998, 2013, 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.writeSQL</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 //--------------------------JDBC 4.2 ----------------------------- 437 438 /** 439 * Writes to the stream the data contained in the given object. The 440 * object will be converted to the specified targetSqlType 441 * before being sent to the stream. 442 *<p> 443 * When the {@code object} is {@code null}, this 444 * method writes an SQL {@code NULL} to the stream. 445 * <p> 446 * If the object has a custom mapping (is of a class implementing the 447 * interface {@code SQLData}), 448 * the JDBC driver should call the method {@code SQLData.writeSQL} to 449 * write it to the SQL data stream. 450 * If, on the other hand, the object is of a class implementing 451 * {@code Ref}, {@code Blob}, {@code Clob}, {@code NClob}, 452 * {@code Struct}, {@code java.net.URL}, 453 * or {@code Array}, the driver should pass it to the database as a 454 * value of the corresponding SQL type. 455 *<P> 456 * The default implementation will throw {@code SQLFeatureNotSupportedException} 457 * 458 * @param x the object containing the input parameter value 459 * @param targetSqlType the SQL type to be sent to the database. 460 * @exception SQLException if a database access error occurs or 461 * if the Java Object specified by x is an InputStream 462 * or Reader object and the value of the scale parameter is less 463 * than zero 464 * @exception SQLFeatureNotSupportedException if 465 * the JDBC driver does not support this data type 466 * @see JDBCType 467 * @see SQLType 468 * @since 1.8 469 */ writeObject(Object x, SQLType targetSqlType)470 default void writeObject(Object x, SQLType targetSqlType) throws SQLException { 471 throw new SQLFeatureNotSupportedException(); 472 } 473 474 } 475 476