001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.sql;
019:
020: import java.math.BigDecimal;
021: import java.io.Reader;
022: import java.io.InputStream;
023: import java.net.URL;
024:
025: /**
026: * The SQLInput interface defines operations which apply to a type of input
027: * stream which carries a series of values which represent an instance of an SQL
028: * structured type or SQL distinct type.
029: * <p>
030: * SQLInput interface is used for custom mapping of SQL User Defined Types
031: * (UDTs)to Java classes. It is used by JDBC drivers below the level of the
032: * public interfaces and application programs do not normally use the SQLInput
033: * methods directly. Reader methods such as readLong and readBytes provide means
034: * to read values from an SQLInput stream.
035: * <p>
036: * When the getObject method is called with an object which implements the
037: * SQLData interface, the JDBC driver determines the SQL type of the UDT being
038: * mapped by calling the SQLData.getSQLType method. The driver creates an
039: * instance of an SQLInput stream, filling the stream with the attributes of the
040: * UDT. The SQLInput stream is passed to the SQLData.readSQL method which then
041: * calls the SQLInput reader methods to read the attributes.
042: */
043: public interface SQLInput {
044:
045: /**
046: * Returns the next attribute in the stream in the form of a String.
047: *
048: * @return the next attribute as a String. null if the value is SQL NULL.
049: * @throws SQLException
050: * if there is a database error
051: */
052: public String readString() throws SQLException;
053:
054: /**
055: * Returns the next attribute in the stream in the form of a boolean.
056: *
057: * @return the next attribute as a boolean. false if the value is SQL NULL.
058: * @throws SQLException
059: * if there is a database error
060: */
061: public boolean readBoolean() throws SQLException;
062:
063: /**
064: * Returns the next attribute in the stream in the form of a byte.
065: *
066: * @return the next attribute as a byte. 0 if the value is SQL NULL.
067: * @throws SQLException
068: * if there is a database error
069: */
070: public byte readByte() throws SQLException;
071:
072: /**
073: * Returns the next attribute in the stream in the form of a short.
074: *
075: * @return the next attribute as a short. 0 if the value is SQL NULL.
076: * @throws SQLException
077: * if there is a database error
078: */
079: public short readShort() throws SQLException;
080:
081: /**
082: * Returns the next attribute in the stream in the form of an int.
083: *
084: * @return the next attribute as an int. 0 if the value is SQL NULL.
085: * @throws SQLException
086: * if there is a database error
087: */
088: public int readInt() throws SQLException;
089:
090: /**
091: * Returns the next attribute in the stream in the form of a long.
092: *
093: * @return the next attribute as a long. 0 if the value is SQL NULL.
094: * @throws SQLException
095: * if there is a database error
096: */
097: public long readLong() throws SQLException;
098:
099: /**
100: * Returns the next attribute in the stream in the form of a float.
101: *
102: * @return the next attribute as a float. 0 if the value is SQL NULL.
103: * @throws SQLException
104: * if there is a database error
105: */
106: public float readFloat() throws SQLException;
107:
108: /**
109: * Returns the next attribute in the stream in the form of a double.
110: *
111: * @return the next attribute as a double. 0 if the value is SQL NULL.
112: * @throws SQLException
113: * if there is a database error
114: */
115: public double readDouble() throws SQLException;
116:
117: /**
118: * Returns the next attribute in the stream in the form of a
119: * java.math.BigDecimal.
120: *
121: * @return the attribute as a java.math.BigDecimal. null if the read returns
122: * SQL NULL.
123: * @throws SQLException
124: * if there is a database error
125: */
126: public BigDecimal readBigDecimal() throws SQLException;
127:
128: /**
129: * Returns the next attribute in the stream in the form of a byte array.
130: *
131: * @return the attribute as a byte array. null if the read returns SQL NULL.
132: * @throws SQLException
133: * if there is a database error
134: */
135: public byte[] readBytes() throws SQLException;
136:
137: /**
138: * Returns the next attribute in the stream in the form of a java.sql.Date.
139: *
140: * @return the next attribute as a java.sql.Date. null if the value is SQL
141: * NULL.
142: * @throws SQLException
143: * if there is a database error
144: */
145: public Date readDate() throws SQLException;
146:
147: /**
148: * Returns the next attribute in the stream in the form of a java.sql.Time.
149: *
150: * @return the attribute as a java.sql.Time. null if the read returns SQL
151: * NULL.
152: * @throws SQLException
153: * if there is a database error
154: */
155: public Time readTime() throws SQLException;
156:
157: /**
158: * Returns the next attribute in the stream in the form of a
159: * java.sql.Timestamp.
160: *
161: * @return the attribute as a java.sql.Timestamp. null if the read returns
162: * SQL NULL.
163: * @throws SQLException
164: * if there is a database error
165: */
166: public Timestamp readTimestamp() throws SQLException;
167:
168: /**
169: * Returns the next attribute in the stream in the form of a Unicode
170: * character stream embodied as a java.io.Reader.
171: *
172: * @return the next attribute as a java.io.Reader. null if the value is SQL
173: * NULL.
174: * @throws SQLException
175: * if there is a database error
176: */
177: public Reader readCharacterStream() throws SQLException;
178:
179: /**
180: * Returns the next attribute in the stream in the form of an ASCII
181: * character stream embodied as a java.io.InputStream.
182: *
183: * @return the next attribute as a java.io.InputStream. null if the value is
184: * SQL NULL.
185: * @throws SQLException
186: * if there is a database error
187: */
188: public InputStream readAsciiStream() throws SQLException;
189:
190: /**
191: * Returns the next attribute in the stream in the form of a stream of bytes
192: * embodied as a java.io.InputStream.
193: *
194: * @return the next attribute as a java.io.InputStream. null if the value is
195: * SQL NULL.
196: * @throws SQLException
197: * if there is a database error
198: */
199: public InputStream readBinaryStream() throws SQLException;
200:
201: /**
202: * Returns the next attribute in the stream in the form of a
203: * java.lang.Object.
204: * <p>
205: * The type of the Object returned is determined by the type mapping for
206: * this JDBC driver, including any customized mappings in force. A type map
207: * is given to the SQLInput by the JDBC driver before the SQLInput is given
208: * to the application.
209: * <p>
210: * If the attribute is an SQL structured or distinct type, its SQL type is
211: * determined. If the streams type map contains an element for that SQL
212: * type, the driver creates an object of relevant type and invokes the
213: * method SQLData.readSQL on it, which reads supplementary data from the
214: * stream using whichever protocol is defined for that method.
215: *
216: * @return the next attribute as an Object. null if the value is SQL NULL.
217: * @throws SQLException
218: * if there is a database error
219: */
220: public Object readObject() throws SQLException;
221:
222: /**
223: * Returns the next attribute in the stream in the form of a java.sql.Ref.
224: *
225: * @return the next attribute as a java.sql.Ref. null if the value is SQL
226: * NULL.
227: * @throws SQLException
228: * if there is a database error
229: */
230: public Ref readRef() throws SQLException;
231:
232: /**
233: * Returns the next attribute in the stream in the form of a java.sql.Blob.
234: *
235: * @return the next attribute as a java.sql.Blob. null if the value is SQL
236: * NULL.
237: * @throws SQLException
238: * if there is a database error
239: */
240: public Blob readBlob() throws SQLException;
241:
242: /**
243: * Returns the next attribute in the stream in the form of a java.sql.Clob.
244: *
245: * @return the next attribute as a java.sql.Clob. null if the value is SQL
246: * NULL.
247: * @throws SQLException
248: * if there is a database error
249: */
250: public Clob readClob() throws SQLException;
251:
252: /**
253: * Returns the next attribute in the stream in the form of a java.sql.Array.
254: *
255: * @return the next attribute as an Array. null if the value is SQL NULL.
256: * @throws SQLException
257: * if there is a database error
258: */
259: public Array readArray() throws SQLException;
260:
261: /**
262: * Reports whether the last value read was SQL NULL.
263: *
264: * @return true if the last value read was SQL NULL, false otherwise.
265: * @throws SQLException
266: * if there is a database error
267: */
268: public boolean wasNull() throws SQLException;
269:
270: /**
271: * Reads the next attribute in the stream (SQL DATALINK value) and returns
272: * it as a java.net.URL object.
273: *
274: * @return the next attribute as a java.net.URL. null if the value is SQL
275: * NULL.
276: * @throws SQLException
277: * if there is a database error
278: */
279: public URL readURL() throws SQLException;
280: }
|