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 * 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 */ readString()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 */ readBoolean()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 */ readByte()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 */ readShort()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 */ readInt()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 */ readLong()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 */ readFloat()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 */ readDouble()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 */ readBigDecimal()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 */ readBytes()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 */ readDate()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 */ readTime()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 */ readTimestamp()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 */ readCharacterStream()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 */ readAsciiStream()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 */ readBinaryStream()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 */ readObject()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 */ readRef()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 */ readBlob()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 */ readClob()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 */ readArray()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 */ wasNull()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 */ readURL()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 */ readNClob()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 */ readNString()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 */ readSQLXML()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 */ readRowId()422 RowId readRowId() throws SQLException; 423 424 } 425