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.util.Calendar;
021: import java.net.URL;
022: import java.io.InputStream;
023: import java.io.Reader;
024: import java.math.BigDecimal;
025:
026: /**
027: * An interface for a Precompiled SQL Statement.
028: * <p>
029: * An SQL Statement is put into a PreparedStatement and is precompiled so that
030: * it can be executed multiple times efficiently.
031: * <p>
032: * Setter methods are supplied in the PreparedStatement interface for the
033: * setting of IN parameters for the Statement. The setter method used for each
034: * IN parameter must match the type of the IN parameter being set.
035: */
036: public interface PreparedStatement extends Statement {
037:
038: /**
039: * Add a set of parameters to the PreparedStatement's command batch.
040: *
041: * @throws SQLException
042: * if a database error happens
043: */
044: public void addBatch() throws SQLException;
045:
046: /**
047: * Clear the current parameter values.
048: * <p>
049: * Typically, parameter values are retained for multiple executions of the
050: * Statement. Setting a parameter value replaces the previous value. This
051: * method clears the values for all parameters, releasing all resources used
052: * by those parameters.
053: *
054: * @throws SQLException
055: * if a database error happens
056: */
057: public void clearParameters() throws SQLException;
058:
059: /**
060: * Executes the SQL statement in this PreparedStatement.
061: * <p>
062: * A PreparedStatement may return multiple results. The execute method
063: * returns a flag indicating the kind of result produced by
064: * PreparedStatement. The methods <code>
065: * getResultSet</code> or
066: * <code>getUpdateCount</code> are used to retrieve the first result,
067: * while <code>getMoreResults</code> must be used to retrieve the second
068: * and subsequent results.
069: *
070: * @return true if the result of the execution is a ResultSet, false if
071: * there is no result or if the result is an update count.
072: * @throws SQLException
073: * if a database error happens
074: */
075: public boolean execute() throws SQLException;
076:
077: /**
078: * Execute the SQL query in the PreparedStatement and return the ResultSet
079: * generated by the query.
080: *
081: * @return the ResultSet generated by the query - never null.
082: * @throws SQLException
083: * if a database error happens or if the SQL statement does not
084: * produce a ResultSet.
085: */
086: public ResultSet executeQuery() throws SQLException;
087:
088: /**
089: * Invoke the SQL command contained within the Prepared Statement. This must
090: * be INSERT, UPDATE, DELETE, or a command that returns nothing.
091: *
092: * @return the count of rows for INSERT, UPDATE or DELETE statements, 0 for
093: * statements that return nothing
094: * @throws SQLException
095: * if a database error happens or if the SQL statement returns a
096: * ResultSet.
097: */
098: public int executeUpdate() throws SQLException;
099:
100: /**
101: * Returns a ResultSetMetaData containing data from the ResultSet that is
102: * produced when the PreparedStatement is invoked.
103: * <p>
104: * It is possible to know the Metadata for the ResultSet without executing
105: * the PreparedStatement, because the PreparedStatement is precompiled. As a
106: * result the Metadata can be queried ahead of time without actually
107: * executing the statement.
108: *
109: * @return a ResultSetMetaData object with the information about the columns
110: * of the ResultSet, if the driver can return a ResultSetMetaData.
111: * null otherwise.
112: * @throws SQLException
113: * if there is a database error
114: */
115: public ResultSetMetaData getMetaData() throws SQLException;
116:
117: /**
118: * Gets information about the parameters of the PreparedStatement.
119: *
120: * @return a ParameterMetaData object which holds information about the
121: * number, type and properties of the parameters of this
122: * PreparedStatement.
123: * @throws SQLException
124: * if a database error happens
125: */
126: public ParameterMetaData getParameterMetaData() throws SQLException;
127:
128: /**
129: * Sets the value of a specified parameter to the supplied Array object.
130: *
131: * @param parameterIndex
132: * the parameter number index, where the first parameter has
133: * index 1
134: * @param theArray
135: * a java.sql.Array holing the data to set.
136: * @throws SQLException
137: * if a database error happens
138: */
139: public void setArray(int parameterIndex, Array theArray)
140: throws SQLException;
141:
142: /**
143: * Sets the value of a specified parameter to the content of a supplied
144: * InputStream, which has a specified number of bytes.
145: * <p>
146: * This is a good method for setting an SQL LONVARCHAR parameter where the
147: * length of the data is large. Data is read from the InputStream until
148: * end-of-file is reached or the specified number of bytes is copied.
149: *
150: * @param parameterIndex
151: * the parameter number index, where the first parameter has
152: * index 1
153: * @param theInputStream
154: * the ASCII InputStream carrying the data to update the
155: * parameter
156: * @param length
157: * the number of bytes in the InputStream to copy to the
158: * parameter
159: * @throws SQLException
160: * if a database error happens
161: */
162: public void setAsciiStream(int parameterIndex,
163: InputStream theInputStream, int length) throws SQLException;
164:
165: /**
166: * Sets the value of a specified parameter to a supplied
167: * java.math.BigDecimal value.
168: *
169: * @param parameterIndex
170: * the parameter number index, where the first parameter has
171: * index 1
172: * @param theBigDecimal
173: * the java.math.BigInteger value to set
174: * @throws SQLException
175: * if a database error happens
176: */
177: public void setBigDecimal(int parameterIndex,
178: BigDecimal theBigDecimal) throws SQLException;
179:
180: /**
181: * Sets the value of a specified parameter to the content of a supplied
182: * binary InputStream, which has a specified number of bytes.
183: * <p>
184: * Use this method when a large amount of data needs to be set into a
185: * LONGVARBINARY parameter.
186: *
187: * @param parameterIndex
188: * the parameter number index, where the first parameter has
189: * index 1
190: * @param theInputStream
191: * the binary InputStream carrying the data to update the
192: * parameter
193: * @param length
194: * the number of bytes in the InputStream to copy to the
195: * parameter
196: * @throws SQLException
197: * if a database error happens
198: */
199: public void setBinaryStream(int parameterIndex,
200: InputStream theInputStream, int length) throws SQLException;
201:
202: /**
203: * Sets the value of a specified parameter to the given Blob object.
204: *
205: * @param parameterIndex
206: * the parameter number index, where the first parameter has
207: * index 1
208: * @param theBlob
209: * a java.sql.Blob holding the data to update the parameter
210: * @throws SQLException
211: * if a database error happens
212: */
213: public void setBlob(int parameterIndex, Blob theBlob)
214: throws SQLException;
215:
216: /**
217: * Sets the value of a specified parameter to a supplied boolean value.
218: *
219: * @param parameterIndex
220: * the parameter number index, where the first parameter has
221: * index 1
222: * @param theBoolean
223: * the boolean value to update the parameter
224: * @throws SQLException
225: * if a database error happens
226: */
227: public void setBoolean(int parameterIndex, boolean theBoolean)
228: throws SQLException;
229:
230: /**
231: * Sets the value of a specified parameter to a supplied byte value.
232: *
233: * @param parameterIndex
234: * the parameter number index, where the first parameter has
235: * index 1
236: * @param theByte
237: * the byte value to update the parameter
238: * @throws SQLException
239: * if a database error happens
240: */
241: public void setByte(int parameterIndex, byte theByte)
242: throws SQLException;
243:
244: /**
245: * Sets the value of a specified parameter to a supplied array of bytes. The
246: * array is mapped to a VARBINARY or LONGVARBINARY in the database.
247: *
248: * @param parameterIndex
249: * the parameter number index, where the first parameter has
250: * index 1
251: * @param theBytes
252: * the array of bytes to update the parameter
253: * @throws SQLException
254: * if a database error happens
255: */
256: public void setBytes(int parameterIndex, byte[] theBytes)
257: throws SQLException;
258:
259: /**
260: * Sets the value of a specified parameter to the character content of a
261: * Reader object, with the specified length of character data.
262: *
263: * @param parameterIndex
264: * the parameter number index, where the first parameter has
265: * index 1
266: * @param reader
267: * the java.io.Reader encompassing the character data
268: * @param length
269: * the amount of characters to be read
270: * @throws SQLException
271: * if a database error happens
272: */
273: public void setCharacterStream(int parameterIndex, Reader reader,
274: int length) throws SQLException;
275:
276: /**
277: * Sets the value of a specified parameter to the given Clob object.
278: *
279: * @param parameterIndex
280: * the parameter number index, where the first parameter has
281: * index 1
282: * @param theClob
283: * a java.sql.Clob holding the data to update the parameter
284: * @throws SQLException
285: * if a database error happens
286: */
287: public void setClob(int parameterIndex, Clob theClob)
288: throws SQLException;
289:
290: /**
291: * Sets the value of a specified parameter to a supplied java.sql.Date
292: * value.
293: *
294: * @param parameterIndex
295: * the parameter number index, where the first parameter has
296: * index 1
297: * @param theDate
298: * a java.sql.Date to update the parameter
299: * @throws SQLException
300: * if a database error happens
301: */
302: public void setDate(int parameterIndex, Date theDate)
303: throws SQLException;
304:
305: /**
306: * Sets the value of a specified parameter to a supplied java.sql.Date
307: * value, using a supplied Calendar to map the Date. The Calendar allows the
308: * application to control the timezone used to compute the SQL DATE in the
309: * database - without the supplied Calendar, the driver uses the default
310: * timezone of the Java virtual machine.
311: *
312: * @param parameterIndex
313: * the parameter number index, where the first parameter has
314: * index 1
315: * @param theDate
316: * a java.sql.Date to update the parameter
317: * @param cal
318: * a Calendar to use to construct the SQL DATE value
319: * @throws SQLException
320: * if a database error happens
321: */
322: public void setDate(int parameterIndex, Date theDate, Calendar cal)
323: throws SQLException;
324:
325: /**
326: * Sets the value of a specified parameter to a supplied double value.
327: *
328: * @param parameterIndex
329: * the parameter number index, where the first parameter has
330: * index 1
331: * @param theDouble
332: * the double value to update the parameter
333: * @throws SQLException
334: * if a database error happens
335: */
336: public void setDouble(int parameterIndex, double theDouble)
337: throws SQLException;
338:
339: /**
340: * Sets the value of a specified parameter to to a supplied float value.
341: *
342: * @param parameterIndex
343: * the parameter number index, where the first parameter has
344: * index 1
345: * @param theFloat
346: * the float value to update the parameter
347: * @throws SQLException
348: * if a database error happens
349: */
350: public void setFloat(int parameterIndex, float theFloat)
351: throws SQLException;
352:
353: /**
354: * Sets the value of a specified parameter to a supplied int value.
355: *
356: * @param parameterIndex
357: * the parameter number index, where the first parameter has
358: * index 1
359: * @param theInt
360: * the int value to update the parameter
361: * @throws SQLException
362: * if a database error happens
363: */
364: public void setInt(int parameterIndex, int theInt)
365: throws SQLException;
366:
367: /**
368: * Sets the value of a specified parameter to a supplied long value.
369: *
370: * @param parameterIndex
371: * the parameter number index, where the first parameter has
372: * index 1
373: * @param theLong
374: * the long value to update the parameter
375: * @throws SQLException
376: * if a database error happens
377: */
378: public void setLong(int parameterIndex, long theLong)
379: throws SQLException;
380:
381: /**
382: * Sets the value of a specified parameter to SQL NULL. Don't use this
383: * version of setNull for User Defined Types or for REF type parameters.
384: *
385: * @param parameterIndex
386: * the parameter number index, where the first parameter has
387: * index 1
388: * @param sqlType
389: * the SQL Type of the parameter, as defined in java.sql.Types
390: * @throws SQLException
391: * if a database error happens
392: */
393: public void setNull(int parameterIndex, int sqlType)
394: throws SQLException;
395:
396: /**
397: * Sets the value of a specified parameter to SQL NULL. This version of
398: * setNull should be used for User Defined Types (UDTs) and also REF types.
399: * UDTs can be STRUCT, DISTINCT, JAVA_OBJECT and named array types.
400: * <p>
401: * Applications must provide the SQL Type code and also a fully qualified
402: * SQL Type name when supplying a NULL UDT or REF. For a UDT, the type name
403: * is the type name of the parameter itself, but for a REF parameter the
404: * type name is the type name of the referenced type.
405: *
406: * @param paramIndex
407: * the parameter number index, where the first parameter has
408: * index 1
409: * @param sqlType
410: * the SQL Type of the parameter, as defined in java.sql.Types
411: * @param typeName
412: * the fully qualified name of a UDT or REF type - ignored if the
413: * parameter is not a UDT.
414: * @throws SQLException
415: * if a database error happens
416: */
417: public void setNull(int paramIndex, int sqlType, String typeName)
418: throws SQLException;
419:
420: /**
421: * Sets the value of a specified parameter using a supplied object.
422: * <p>
423: * There is a standard mapping from Java types to SQL types, defined in the
424: * JDBC specification. The passed object is then transformed into the
425: * appropriate SQL type, and then transferred to the database. setObject can
426: * be used to pass abstract data types unique to the database, by using a
427: * JDBC driver specific Java type. If the object's class implements the
428: * interface SQLData, the JDBC driver calls <code>SQLData.writeSQL</code>
429: * to write it to the SQL data stream. If the object's class implements Ref,
430: * Blob, Clob, Struct, or Array, the driver passes it to the database as a
431: * value of the corresponding SQL type.
432: *
433: * @param parameterIndex
434: * the parameter number index, where the first parameter has
435: * index 1
436: * @param theObject
437: * the Object containing the value to update the parameter
438: * @throws SQLException
439: * if a database error happens
440: */
441: public void setObject(int parameterIndex, Object theObject)
442: throws SQLException;
443:
444: /**
445: * Sets the value of a specified parameter.
446: * <p>
447: * The Object is converted to the target SQL type before it is added to the
448: * database. If the Object is an instance of SQLData then SQLData.writeSQL
449: * is called to write out its data.
450: * </p>
451: *
452: * @param parameterIndex
453: * the parameter index, where the first parameter has index 1
454: * @param theObject
455: * the Object containing the value to update the parameter
456: * @param targetSqlType
457: * the SQL Type to send to the database, as defined in
458: * java.sql.Types
459: * @throws SQLException
460: * if a database error happens
461: */
462: public void setObject(int parameterIndex, Object theObject,
463: int targetSqlType) throws SQLException;
464:
465: /**
466: * Sets the value of a specified parameter.
467: * <p>
468: * The Object is converted to the target SQL type before it is added to the
469: * database. If the Object is an instance of SQLData then SQLData.writeSQL
470: * is called to write out its data.
471: * </p>
472: *
473: * @param parameterIndex
474: * the parameter index, where the first parameter has index 1
475: * @param theObject
476: * the Object containing the value to update the parameter
477: * @param targetSqlType
478: * the SQL Type to send to the database, as defined in
479: * java.sql.Types
480: * @param scale
481: * the number of decimal places if the types is
482: * java.sql.Types.DECIMAL or java.sql.Types.NUMERIC
483: * @throws SQLException
484: * if a database error happens
485: */
486: public void setObject(int parameterIndex, Object theObject,
487: int targetSqlType, int scale) throws SQLException;
488:
489: /**
490: * Sets the value of a specified parameter to a supplied REF(<structured-type>)
491: * value. This is stored as an SQL REF.
492: *
493: * @param parameterIndex
494: * the parameter number index, where the first parameter has
495: * index 1
496: * @param theRef
497: * a java.sql.Ref value to update the parameter
498: * @throws SQLException
499: * if a database error happens
500: */
501: public void setRef(int parameterIndex, Ref theRef)
502: throws SQLException;
503:
504: /**
505: * Sets the value of a specified parameter to a supplied short value.
506: *
507: * @param parameterIndex
508: * the parameter number index, where the first parameter has
509: * index 1
510: * @param theShort
511: * a short value to update the parameter
512: * @throws SQLException
513: * if a database error happens
514: */
515: public void setShort(int parameterIndex, short theShort)
516: throws SQLException;
517:
518: /**
519: * Sets the value of a specified parameter to a supplied String.
520: *
521: * @param parameterIndex
522: * the parameter number index, where the first parameter has
523: * index 1
524: * @param theString
525: * a String value to update the parameter
526: * @throws SQLException
527: * if a database error happens
528: */
529: public void setString(int parameterIndex, String theString)
530: throws SQLException;
531:
532: /**
533: * Sets the value of a specified parameter to a supplied java.sql.Time
534: * value.
535: *
536: * @param parameterIndex
537: * the parameter number index, where the first parameter has
538: * index 1
539: * @param theTime
540: * a java.sql.Time value to update the parameter
541: * @throws SQLException
542: * if a database error happens
543: */
544: public void setTime(int parameterIndex, Time theTime)
545: throws SQLException;
546:
547: /**
548: * Sets the value of a specified parameter to a supplied java.sql.Time
549: * value, using a supplied Calendar.
550: * <p>
551: * The driver uses the supplied Calendar to create the SQL TIME value, which
552: * allows it to use a custom timezone - otherwise the driver uses the
553: * default timezone of the Java virtual machine.
554: *
555: * @param parameterIndex
556: * the parameter number index, where the first parameter has
557: * index 1
558: * @param theTime
559: * a java.sql.Time value to update the parameter
560: * @param cal
561: * a Calendar to use to construct the SQL TIME value
562: * @throws SQLException
563: * if a database error happens
564: */
565: public void setTime(int parameterIndex, Time theTime, Calendar cal)
566: throws SQLException;
567:
568: /**
569: * Sets the value of a specified parameter to a supplied java.sql.Timestamp
570: * value.
571: *
572: * @param parameterIndex
573: * the parameter number index, where the first parameter has
574: * index 1
575: * @param theTimestamp
576: * the java.sql.Timestamp value to update the parameter
577: * @throws SQLException
578: * if a database error happens
579: */
580: public void setTimestamp(int parameterIndex, Timestamp theTimestamp)
581: throws SQLException;
582:
583: /**
584: * Sets the value of a specified parameter to a supplied java.sql.Timestamp
585: * value, using the supplied Calendar.
586: * <p>
587: * The driver uses the supplied Calendar to create the SQL TIMESTAMP value,
588: * which allows it to use a custom timezone - otherwise the driver uses the
589: * default timezone of the Java virtual machine.
590: *
591: * @param parameterIndex
592: * the parameter number index, where the first parameter has
593: * index 1
594: * @param theTimestamp
595: * the java.sql.Timestamp value to update the parameter
596: * @param cal
597: * a Calendar to use to construct the SQL TIMESTAMP value
598: * @throws SQLException
599: * if a database error happens
600: */
601: public void setTimestamp(int parameterIndex,
602: Timestamp theTimestamp, Calendar cal) throws SQLException;
603:
604: /**
605: * @deprecated Sets the value of a specified parameter to the characters
606: * from a supplied InputStream, with a specified number of
607: * bytes.
608: * @param parameterIndex
609: * the parameter number index, where the first parameter has
610: * index 1
611: * @param theInputStream
612: * the InputStream with the character data to update the
613: * parameter
614: * @param length
615: * the number of bytes to read from the InputStream
616: * @throws SQLException
617: * if a database error happens
618: */
619: @Deprecated
620: public void setUnicodeStream(int parameterIndex,
621: InputStream theInputStream, int length) throws SQLException;
622:
623: /**
624: * Sets the value of a specified parameter to a supplied java.net.URL.
625: *
626: * @param parameterIndex
627: * the parameter number index, where the first parameter has
628: * index 1
629: * @param theURL
630: * the URL to update the parameter
631: * @throws SQLException
632: * if a database error happens
633: */
634: public void setURL(int parameterIndex, URL theURL)
635: throws SQLException;
636: }
|