2
+ − 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 * An input stream that contains a stream of values representing an
+ − 30 * instance of an SQL structured type or an SQL distinct type.
+ − 31 * This interface, used only for custom mapping, is used by the driver
+ − 32 * behind the scenes, and a programmer never directly invokes
+ − 33 * <code>SQLInput</code> methods. The <i>reader</i> methods
+ − 34 * (<code>readLong</code>, <code>readBytes</code>, and so on)
+ − 35 * provide a way for an implementation of the <code>SQLData</code>
+ − 36 * interface to read the values in an <code>SQLInput</code> object.
+ − 37 * And as described in <code>SQLData</code>, calls to reader methods must
+ − 38 * be made in the order that their corresponding attributes appear in the
+ − 39 * SQL definition of the type.
+ − 40 * The method <code>wasNull</code> is used to determine whether
+ − 41 * the last value read was SQL <code>NULL</code>.
+ − 42 * <P>When the method <code>getObject</code> is called with an
+ − 43 * object of a class implementing the interface <code>SQLData</code>,
+ − 44 * the JDBC driver calls the method <code>SQLData.getSQLType</code>
+ − 45 * to determine the SQL type of the user-defined type (UDT)
+ − 46 * being custom mapped. The driver
+ − 47 * creates an instance of <code>SQLInput</code>, populating it with the
+ − 48 * attributes of the UDT. The driver then passes the input
+ − 49 * stream to the method <code>SQLData.readSQL</code>, which in turn
+ − 50 * calls the <code>SQLInput</code> reader methods
+ − 51 * in its implementation for reading the
+ − 52 * attributes from the input stream.
+ − 53 * @since 1.2
+ − 54 */
+ − 55
+ − 56 public interface SQLInput {
+ − 57
+ − 58
+ − 59 //================================================================
+ − 60 // Methods for reading attributes from the stream of SQL data.
+ − 61 // These methods correspond to the column-accessor methods of
+ − 62 // java.sql.ResultSet.
+ − 63 //================================================================
+ − 64
+ − 65 /**
+ − 66 * Reads the next attribute in the stream and returns it as a <code>String</code>
+ − 67 * in the Java programming language.
+ − 68 *
+ − 69 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
+ − 70 * @exception SQLException if a database access error occurs
+ − 71 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 72 * this method
+ − 73 * @since 1.2
+ − 74 */
+ − 75 String readString() throws SQLException;
+ − 76
+ − 77 /**
+ − 78 * Reads the next attribute in the stream and returns it as a <code>boolean</code>
+ − 79 * in the Java programming language.
+ − 80 *
+ − 81 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>false</code>
+ − 82 * @exception SQLException if a database access error occurs
+ − 83 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 84 * this method
+ − 85 * @since 1.2
+ − 86 */
+ − 87 boolean readBoolean() throws SQLException;
+ − 88
+ − 89 /**
+ − 90 * Reads the next attribute in the stream and returns it as a <code>byte</code>
+ − 91 * in the Java programming language.
+ − 92 *
+ − 93 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
+ − 94 * @exception SQLException if a database access error occurs
+ − 95 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 96 * this method
+ − 97 * @since 1.2
+ − 98 */
+ − 99 byte readByte() throws SQLException;
+ − 100
+ − 101 /**
+ − 102 * Reads the next attribute in the stream and returns it as a <code>short</code>
+ − 103 * in the Java programming language.
+ − 104 *
+ − 105 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
+ − 106 * @exception SQLException if a database access error occurs
+ − 107 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 108 * this method
+ − 109 * @since 1.2
+ − 110 */
+ − 111 short readShort() throws SQLException;
+ − 112
+ − 113 /**
+ − 114 * Reads the next attribute in the stream and returns it as an <code>int</code>
+ − 115 * in the Java programming language.
+ − 116 *
+ − 117 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
+ − 118 * @exception SQLException if a database access error occurs
+ − 119 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 120 * this method
+ − 121 * @since 1.2
+ − 122 */
+ − 123 int readInt() throws SQLException;
+ − 124
+ − 125 /**
+ − 126 * Reads the next attribute in the stream and returns it as a <code>long</code>
+ − 127 * in the Java programming language.
+ − 128 *
+ − 129 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
+ − 130 * @exception SQLException if a database access error occurs
+ − 131 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 132 * this method
+ − 133 * @since 1.2
+ − 134 */
+ − 135 long readLong() throws SQLException;
+ − 136
+ − 137 /**
+ − 138 * Reads the next attribute in the stream and returns it as a <code>float</code>
+ − 139 * in the Java programming language.
+ − 140 *
+ − 141 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
+ − 142 * @exception SQLException if a database access error occurs
+ − 143 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 144 * this method
+ − 145 * @since 1.2
+ − 146 */
+ − 147 float readFloat() throws SQLException;
+ − 148
+ − 149 /**
+ − 150 * Reads the next attribute in the stream and returns it as a <code>double</code>
+ − 151 * in the Java programming language.
+ − 152 *
+ − 153 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
+ − 154 * @exception SQLException if a database access error occurs
+ − 155 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 156 * this method
+ − 157 * @since 1.2
+ − 158 */
+ − 159 double readDouble() throws SQLException;
+ − 160
+ − 161 /**
+ − 162 * Reads the next attribute in the stream and returns it as a <code>java.math.BigDecimal</code>
+ − 163 * object in the Java programming language.
+ − 164 *
+ − 165 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
+ − 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 java.math.BigDecimal readBigDecimal() throws SQLException;
+ − 172
+ − 173 /**
+ − 174 * Reads the next attribute in the stream and returns it as an array of bytes
+ − 175 * in the Java programming language.
+ − 176 *
+ − 177 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
+ − 178 * @exception SQLException if a database access error occurs
+ − 179 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 180 * this method
+ − 181 * @since 1.2
+ − 182 */
+ − 183 byte[] readBytes() throws SQLException;
+ − 184
+ − 185 /**
+ − 186 * Reads the next attribute in the stream and returns it as a <code>java.sql.Date</code> object.
+ − 187 *
+ − 188 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
+ − 189 * @exception SQLException if a database access error occurs
+ − 190 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 191 * this method
+ − 192 * @since 1.2
+ − 193 */
+ − 194 java.sql.Date readDate() throws SQLException;
+ − 195
+ − 196 /**
+ − 197 * Reads the next attribute in the stream and returns it as a <code>java.sql.Time</code> object.
+ − 198 *
+ − 199 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
+ − 200 * @exception SQLException if a database access error occurs
+ − 201 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 202 * this method
+ − 203 * @since 1.2
+ − 204 */
+ − 205 java.sql.Time readTime() throws SQLException;
+ − 206
+ − 207 /**
+ − 208 * Reads the next attribute in the stream and returns it as a <code>java.sql.Timestamp</code> object.
+ − 209 *
+ − 210 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
+ − 211 * @exception SQLException if a database access error occurs
+ − 212 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 213 * this method
+ − 214 * @since 1.2
+ − 215 */
+ − 216 java.sql.Timestamp readTimestamp() throws SQLException;
+ − 217
+ − 218 /**
+ − 219 * Reads the next attribute in the stream and returns it as a stream of Unicode characters.
+ − 220 *
+ − 221 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
+ − 222 * @exception SQLException if a database access error occurs
+ − 223 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 224 * this method
+ − 225 * @since 1.2
+ − 226 */
+ − 227 java.io.Reader readCharacterStream() throws SQLException;
+ − 228
+ − 229 /**
+ − 230 * Reads the next attribute in the stream and returns it as a stream of ASCII characters.
+ − 231 *
+ − 232 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
+ − 233 * @exception SQLException if a database access error occurs
+ − 234 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 235 * this method
+ − 236 * @since 1.2
+ − 237 */
+ − 238 java.io.InputStream readAsciiStream() throws SQLException;
+ − 239
+ − 240 /**
+ − 241 * Reads the next attribute in the stream and returns it as a stream of uninterpreted
+ − 242 * bytes.
+ − 243 *
+ − 244 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
+ − 245 * @exception SQLException if a database access error occurs
+ − 246 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 247 * this method
+ − 248 * @since 1.2
+ − 249 */
+ − 250 java.io.InputStream readBinaryStream() throws SQLException;
+ − 251
+ − 252 //================================================================
+ − 253 // Methods for reading items of SQL user-defined types from the stream.
+ − 254 //================================================================
+ − 255
+ − 256 /**
+ − 257 * Reads the datum at the head of the stream and returns it as an
+ − 258 * <code>Object</code> in the Java programming language. The
+ − 259 * actual type of the object returned is determined by the default type
+ − 260 * mapping, and any customizations present in this stream's type map.
+ − 261 *
+ − 262 * <P>A type map is registered with the stream by the JDBC driver before the
+ − 263 * stream is passed to the application.
+ − 264 *
+ − 265 * <P>When the datum at the head of the stream is an SQL <code>NULL</code>,
+ − 266 * the method returns <code>null</code>. If the datum is an SQL structured or distinct
+ − 267 * type, it determines the SQL type of the datum at the head of the stream.
+ − 268 * If the stream's type map has an entry for that SQL type, the driver
+ − 269 * constructs an object of the appropriate class and calls the method
+ − 270 * <code>SQLData.readSQL</code> on that object, which reads additional data from the
+ − 271 * stream, using the protocol described for that method.
+ − 272 *
+ − 273 * @return the datum at the head of the stream as an <code>Object</code> in the
+ − 274 * Java programming language;<code>null</code> if the datum is SQL <code>NULL</code>
+ − 275 * @exception SQLException if a database access error occurs
+ − 276 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 277 * this method
+ − 278 * @since 1.2
+ − 279 */
+ − 280 Object readObject() throws SQLException;
+ − 281
+ − 282 /**
+ − 283 * Reads an SQL <code>REF</code> value from the stream and returns it as a
+ − 284 * <code>Ref</code> object in the Java programming language.
+ − 285 *
+ − 286 * @return a <code>Ref</code> object representing the SQL <code>REF</code> value
+ − 287 * at the head of the stream; <code>null</code> if the value read is
+ − 288 * SQL <code>NULL</code>
+ − 289 * @exception SQLException if a database access error occurs
+ − 290 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 291 * this method
+ − 292 * @since 1.2
+ − 293 */
+ − 294 Ref readRef() throws SQLException;
+ − 295
+ − 296 /**
+ − 297 * Reads an SQL <code>BLOB</code> value from the stream and returns it as a
+ − 298 * <code>Blob</code> object in the Java programming language.
+ − 299 *
+ − 300 * @return a <code>Blob</code> object representing data of the SQL <code>BLOB</code> value
+ − 301 * at the head of the stream; <code>null</code> if the value read is
+ − 302 * SQL <code>NULL</code>
+ − 303 * @exception SQLException if a database access error occurs
+ − 304 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 305 * this method
+ − 306 * @since 1.2
+ − 307 */
+ − 308 Blob readBlob() throws SQLException;
+ − 309
+ − 310 /**
+ − 311 * Reads an SQL <code>CLOB</code> value from the stream and returns it as a
+ − 312 * <code>Clob</code> object in the Java programming language.
+ − 313 *
+ − 314 * @return a <code>Clob</code> object representing data of the SQL <code>CLOB</code> value
+ − 315 * at the head of the stream; <code>null</code> if the value read is
+ − 316 * SQL <code>NULL</code>
+ − 317 * @exception SQLException if a database access error occurs
+ − 318 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 319 * this method
+ − 320 * @since 1.2
+ − 321 */
+ − 322 Clob readClob() throws SQLException;
+ − 323
+ − 324 /**
+ − 325 * Reads an SQL <code>ARRAY</code> value from the stream and returns it as an
+ − 326 * <code>Array</code> object in the Java programming language.
+ − 327 *
+ − 328 * @return an <code>Array</code> object representing data of the SQL
+ − 329 * <code>ARRAY</code> value at the head of the stream; <code>null</code>
+ − 330 * if the value read is SQL <code>NULL</code>
+ − 331 * @exception SQLException if a database access error occurs
+ − 332 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 333 * this method
+ − 334 * @since 1.2
+ − 335 */
+ − 336 Array readArray() throws SQLException;
+ − 337
+ − 338 /**
+ − 339 * Retrieves whether the last value read was SQL <code>NULL</code>.
+ − 340 *
+ − 341 * @return <code>true</code> if the most recently read SQL value was SQL
+ − 342 * <code>NULL</code>; <code>false</code> otherwise
+ − 343 * @exception SQLException if a database access error occurs
+ − 344 *
+ − 345 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 346 * this method
+ − 347 * @since 1.2
+ − 348 */
+ − 349 boolean wasNull() throws SQLException;
+ − 350
+ − 351 //---------------------------- JDBC 3.0 -------------------------
+ − 352
+ − 353 /**
+ − 354 * Reads an SQL <code>DATALINK</code> value from the stream and returns it as a
+ − 355 * <code>java.net.URL</code> object in the Java programming language.
+ − 356 *
+ − 357 * @return a <code>java.net.URL</code> object.
+ − 358 * @exception SQLException if a database access error occurs,
+ − 359 * or if a URL is malformed
+ − 360 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 361 * this method
+ − 362 * @since 1.4
+ − 363 */
+ − 364 java.net.URL readURL() throws SQLException;
+ − 365
+ − 366 //---------------------------- JDBC 4.0 -------------------------
+ − 367
+ − 368 /**
+ − 369 * Reads an SQL <code>NCLOB</code> value from the stream and returns it as a
+ − 370 * <code>NClob</code> object in the Java programming language.
+ − 371 *
+ − 372 * @return a <code>NClob</code> object representing data of the SQL <code>NCLOB</code> value
+ − 373 * at the head of the stream; <code>null</code> if the value read is
+ − 374 * SQL <code>NULL</code>
+ − 375 * @exception SQLException if a database access error occurs
+ − 376 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 377 * this method
+ − 378 * @since 1.6
+ − 379 */
+ − 380 NClob readNClob() throws SQLException;
+ − 381
+ − 382 /**
+ − 383 * Reads the next attribute in the stream and returns it as a <code>String</code>
+ − 384 * in the Java programming language. It is intended for use when
+ − 385 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
+ − 386 * and <code>LONGNVARCHAR</code> columns.
+ − 387 *
+ − 388 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
+ − 389 * @exception SQLException if a database access error occurs
+ − 390 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 391 * this method
+ − 392 * @since 1.6
+ − 393 */
+ − 394 String readNString() throws SQLException;
+ − 395
+ − 396 /**
+ − 397 * Reads an SQL <code>XML</code> value from the stream and returns it as a
+ − 398 * <code>SQLXML</code> object in the Java programming language.
+ − 399 *
+ − 400 * @return a <code>SQLXML</code> object representing data of the SQL <code>XML</code> value
+ − 401 * at the head of the stream; <code>null</code> if the value read is
+ − 402 * SQL <code>NULL</code>
+ − 403 * @exception SQLException if a database access error occurs
+ − 404 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 405 * this method
+ − 406 * @since 1.6
+ − 407 */
+ − 408 SQLXML readSQLXML() throws SQLException;
+ − 409
+ − 410 /**
+ − 411 * Reads an SQL <code>ROWID</code> value from the stream and returns it as a
+ − 412 * <code>RowId</code> object in the Java programming language.
+ − 413 *
+ − 414 * @return a <code>RowId</code> object representing data of the SQL <code>ROWID</code> value
+ − 415 * at the head of the stream; <code>null</code> if the value read is
+ − 416 * SQL <code>NULL</code>
+ − 417 * @exception SQLException if a database access error occurs
+ − 418 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
+ − 419 * this method
+ − 420 * @since 1.6
+ − 421 */
+ − 422 RowId readRowId() throws SQLException;
+ − 423
+ − 424 }