1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.sql; 19 20 import java.io.InputStream; 21 import java.io.Reader; 22 import java.math.BigDecimal; 23 import java.net.URL; 24 25 /** 26 * The {@code SQLInput} interface defines operations which apply to a type of 27 * input stream which carries a series of values representing an instance of 28 * an SQL structured type or SQL distinct type. 29 * <p> 30 * This interface is used to define custom mappings of SQL <i>User Defined 31 * Types</i> (UDTs) to Java classes. It is used by JDBC drivers, therefore 32 * application programmers do not normally use the {@code SQLInput} methods 33 * directly. Reader methods such as {@code readLong} and {@code readBytes} 34 * provide means to read values from an {@code SQLInput} stream. 35 * <p> 36 * When the {@code getObject} method is called with an object which implements 37 * the {@code SQLData} interface, the JDBC driver determines the SQL type of the 38 * UDT being mapped by calling the {@code SQLData.getSQLType} method. The driver 39 * creates an instance of an {@code SQLInput} stream, filling the stream with 40 * the attributes of the UDT. The {@code SQLInput} stream is passed to the 41 * {@code SQLData.readSQL} method which then calls the {@code SQLInput} reader 42 * methods to read the attributes. 43 * 44 * @see SQLData 45 */ 46 public interface SQLInput { 47 48 /** 49 * Returns the next attribute in the stream in the form of a {@code String}. 50 * 51 * @return the next attribute. {@code null} if the value is SQL {@code NULL}. 52 * 53 * @throws SQLException 54 * if there is a database error. 55 */ 56 public String readString() throws SQLException; 57 58 /** 59 * Returns the next attribute in the stream in the form of a {@code boolean} 60 * . 61 * 62 * @return the next attribute as a {@code boolean}. {@code false} if the 63 * value is SQL {@code NULL}. 64 * @throws SQLException 65 * if there is a database error. 66 */ 67 public boolean readBoolean() throws SQLException; 68 69 /** 70 * Returns the next attribute in the stream in the form of a {@code byte}. 71 * 72 * @return the next attribute as a {@code byte}. 0 if the value is SQL 73 * {@code NULL}. 74 * @throws SQLException 75 * if there is a database error. 76 */ 77 public byte readByte() throws SQLException; 78 79 /** 80 * Returns the next attribute in the stream in the form of a {@code short}. 81 * 82 * @return the next attribute as a {@code short}. 0 if the value is SQL 83 * {@code NULL}. 84 * @throws SQLException 85 * if there is a database error. 86 */ 87 public short readShort() throws SQLException; 88 89 /** 90 * Returns the next attribute in the stream in the form of an {@code int}. 91 * 92 * @return the next attribute as an {@code int}. 0 if the value is SQL 93 * {@code NULL}. 94 * @throws SQLException 95 * if there is a database error. 96 */ 97 public int readInt() throws SQLException; 98 99 /** 100 * Returns the next attribute in the stream in the form of a {@code long}. 101 * 102 * @return the next attribute as a {@code long}. 0 if the value is SQL 103 * {@code NULL}. 104 * @throws SQLException 105 * if there is a database error. 106 */ 107 public long readLong() throws SQLException; 108 109 /** 110 * Returns the next attribute in the stream in the form of a {@code float}. 111 * 112 * @return the next attribute as a {@code float}. 0 if the value is SQL 113 * {@code NULL}. 114 * @throws SQLException 115 * if there is a database error. 116 */ 117 public float readFloat() throws SQLException; 118 119 /** 120 * Returns the next attribute in the stream in the form of a {@code double}. 121 * 122 * @return the next attribute as a {@code double}. 0 if the value is SQL 123 * {@code NULL}. 124 * @throws SQLException 125 * if there is a database error. 126 */ 127 public double readDouble() throws SQLException; 128 129 /** 130 * Returns the next attribute in the stream in the form of a {@code 131 * java.math.BigDecimal}. 132 * 133 * @return the attribute as a {@code java.math.BigDecimal}. {@code null} if 134 * the read returns SQL {@code NULL}. 135 * @throws SQLException 136 * if there is a database error. 137 * @see java.math.BigDecimal 138 */ 139 public BigDecimal readBigDecimal() throws SQLException; 140 141 /** 142 * Returns the next attribute in the stream in the form of a byte array. 143 * 144 * @return the attribute as a byte array. {@code null} if the read returns 145 * SQL {@code NULL}. 146 * @throws SQLException 147 * if there is a database error. 148 */ 149 public byte[] readBytes() throws SQLException; 150 151 /** 152 * Returns the next attribute in the stream in the form of a {@code 153 * java.sql.Date}. 154 * 155 * @return the next attribute as a {@code java.sql.Date}. {@code null} if 156 * the value is SQL {@code NULL}. 157 * @throws SQLException 158 * if there is a database error. 159 * @see Date 160 */ 161 public Date readDate() throws SQLException; 162 163 /** 164 * Returns the next attribute in the stream in the form of a {@code 165 * java.sql.Time}. 166 * 167 * @return the attribute as a {@code java.sql.Time}. {@code null} if the 168 * read returns SQL {@code NULL}. 169 * @throws SQLException 170 * if there is a database error. 171 * @see Time 172 */ 173 public Time readTime() throws SQLException; 174 175 /** 176 * Returns the next attribute in the stream in the form of a {@code 177 * java.sql.Timestamp}. 178 * 179 * @return the attribute as a {@code java.sql.Timestamp}. {@code null} if 180 * the read returns SQL {@code NULL}. 181 * @throws SQLException 182 * if there is a database error. 183 * @see Timestamp 184 */ 185 public Timestamp readTimestamp() throws SQLException; 186 187 /** 188 * Returns the next attribute in the stream in the form of a Unicode 189 * character stream embodied as a {@code java.io.Reader}. 190 * 191 * @return the next attribute as a {@code java.io.Reader}. {@code null} if 192 * the value is SQL {@code NULL}. 193 * @throws SQLException 194 * if there is a database error. 195 * @see java.io.Reader 196 */ 197 public Reader readCharacterStream() throws SQLException; 198 199 /** 200 * Returns the next attribute in the stream in the form of an ASCII 201 * character stream embodied as a {@code java.io.InputStream}. 202 * 203 * @return the next attribute as a {@code java.io.InputStream}. {@code null} 204 * if the value is SQL {@code NULL}. 205 * @throws SQLException 206 * if there is a database error. 207 * @see java.io.InputStream 208 */ 209 public InputStream readAsciiStream() throws SQLException; 210 211 /** 212 * Returns the next attribute in the stream in the form of a stream of bytes 213 * embodied as a {@code java.io.InputStream}. 214 * 215 * @return the next attribute as a {@code java.io.InputStream}. {@code null} 216 * if the value is SQL {@code NULL}. 217 * @throws SQLException 218 * if there is a database error. 219 * @see java.io.InputStream 220 */ 221 public InputStream readBinaryStream() throws SQLException; 222 223 /** 224 * Returns the next attribute in the stream in the form of a {@code 225 * java.lang.Object}. 226 * <p> 227 * The type of the {@code Object} returned is determined by the type mapping 228 * for this JDBC driver, including any customized mappings, if present. A 229 * type map is given to the {@code SQLInput} by the JDBC driver before the 230 * {@code SQLInput} is given to the application. 231 * <p> 232 * If the attribute is an SQL structured or distinct type, its SQL type is 233 * determined. If the stream's type map contains an element for that SQL 234 * type, the driver creates an object for the relevant type and invokes the 235 * method {@code SQLData.readSQL} on it, which reads supplementary data from 236 * the stream using whichever protocol is defined for that method. 237 * 238 * @return the next attribute as an Object. {@code null} if the value is SQL 239 * {@code NULL}. 240 * @throws SQLException 241 * if there is a database error. 242 */ 243 public Object readObject() throws SQLException; 244 245 /** 246 * Returns the next attribute in the stream in the form of a {@code 247 * java.sql.Ref}. 248 * 249 * @return the next attribute as a {@code java.sql.Ref}. {@code null} if the 250 * value is SQL {@code NULL}. 251 * @throws SQLException 252 * if there is a database error. 253 * @see Ref 254 */ 255 public Ref readRef() throws SQLException; 256 257 /** 258 * Returns the next attribute in the stream in the form of a {@code 259 * java.sql.Blob}. 260 * 261 * @return the next attribute as a {@code java.sql.Blob}. {@code null} if 262 * the value is SQL {@code NULL}. 263 * @throws SQLException 264 * if there is a database error. 265 */ 266 public Blob readBlob() throws SQLException; 267 268 /** 269 * Returns the next attribute in the stream in the form of a {@code 270 * java.sql.Clob}. 271 * 272 * @return the next attribute as a {@code java.sql.Clob}. {@code null} if 273 * the value is SQL {@code NULL}. 274 * @throws SQLException 275 * if there is a database error. 276 * @see Clob 277 */ 278 public Clob readClob() throws SQLException; 279 280 /** 281 * Returns the next attribute in the stream in the form of a {@code 282 * java.sql.Array}. 283 * 284 * @return the next attribute as an {@code Array}. {@code null} if the value 285 * is SQL {@code NULL}. 286 * @throws SQLException 287 * if there is a database error. 288 * @see Array 289 */ 290 public Array readArray() throws SQLException; 291 292 /** 293 * Reports whether the last value read was SQL {@code NULL}. 294 * 295 * @return {@code true} if the last value read was SQL {@code NULL}, {@code 296 * false} otherwise. 297 * @throws SQLException 298 * if there is a database error. 299 */ 300 public boolean wasNull() throws SQLException; 301 302 /** 303 * Reads the next attribute in the stream (SQL DATALINK value) and returns 304 * it as a {@code java.net.URL} object. 305 * 306 * @return the next attribute as a {@code java.net.URL}. {@code null} if the 307 * value is SQL {@code NULL}. 308 * @throws SQLException 309 * if there is a database error. 310 * @see java.net.URL 311 */ 312 public URL readURL() throws SQLException; 313 314 /** 315 * Returns the next attribute in the stream in the form of a {@code 316 * java.sql.NClob}. 317 * 318 * @return the next attribute as a {@code java.sql.NClob}. {@code null} if 319 * the value is SQL {@code NULL}. 320 * @throws SQLException 321 * if there is a database error. 322 */ 323 public NClob readNClob() throws SQLException; 324 325 /** 326 * Returns the next attribute in the stream in the form of a {@code 327 * java.lang.String}. Used for the NCHAR, NVARCHAR and LONGNVARCHAR types. 328 * See {@link #readString} otherwise. 329 * 330 * @return the next attribute as a {@code java.lang.String}. {@code null} if 331 * the value is SQL {@code NULL}. 332 * @throws SQLException 333 * if there is a database error. 334 */ 335 public String readNString() throws SQLException; 336 337 /** 338 * Returns the next attribute in the stream in the form of a {@code 339 * java.sql.SQLXML}. 340 * 341 * @return the next attribute as a {@code java.sql.SQLXML}. {@code null} if 342 * the value is SQL {@code NULL}. 343 * @throws SQLException 344 * if there is a database error. 345 */ 346 public SQLXML readSQLXML() throws SQLException; 347 348 /** 349 * Returns the next attribute in the stream in the form of a {@code 350 * java.sql.RowId}. Used for the ROWID type. 351 * 352 * @return the next attribute as a {@code java.sql.RowId}. {@code null} if 353 * the value is SQL {@code NULL}. 354 * @throws SQLException 355 * if there is a database error. 356 */ 357 public RowId readRowId() throws SQLException; 358 } 359
