libcore/luni/src/main/java/java/sql/SQLInput.java

   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 }