RJPreparedStatementInterface


1   
2   /**
3    * RmiJdbc client/server JDBC Driver
4    * (C) GIE Dyade (Groupe BULL / INRIA Research Center) 1997
5    *
6    * @version     1.0
7    * @author      Pierre-Yves Gibello (pierreyves.gibello@experlog.com)
8    */
9   
10  package org.objectweb.rmijdbc;
11  
12  import java.sql.*;
13  import java.rmi.RemoteException  ;
14  
15  import java.util.Calendar  ;
16  
17  // TBD: WARNING This file contains a hack for InputStream class...
18  // InputStream is not serializable, of course !
19  // The right way would be to encapsulate InputStream in a RMI remote object
20  // (hope I'll find time to do that)
21  
22  /**
23   * <P>A SQL statement is pre-compiled and stored in a
24   * PreparedStatement object. This object can then be used to
25   * efficiently execute this statement multiple times. 
26   *
27   * <P><B>Note:</B> The setXXX methods for setting IN parameter values
28   * must specify types that are compatible with the defined SQL type of
29   * the input parameter. For instance, if the IN parameter has SQL type
30   * Integer then setInt should be used.
31   *
32   * <p>If arbitrary parameter type conversions are required then the
33   * setObject method should be used with a target SQL type.
34   *
35   * @see Connection#prepareStatement
36   * @see ResultSet 
37   */
38  
39  public interface RJPreparedStatementInterface extends RJStatementInterface {
40  
41      /**
42       * A prepared SQL query is executed and its ResultSet is returned.
43       *
44       * @return a ResultSet that contains the data produced by the
45       * query; never null
46       */
47    RJResultSetInterface executeQuery() throws RemoteException  , SQLException;
48  
49      /**
50       * Execute a SQL INSERT, UPDATE or DELETE statement. In addition,
51       * SQL statements that return nothing such as SQL DDL statements
52       * can be executed.
53       *
54       * @return either the row count for INSERT, UPDATE or DELETE; or 0
55       * for SQL statements that return nothing
56       */
57    int executeUpdate() throws RemoteException  , SQLException;
58  
59      /**
60       * Set a parameter to SQL NULL.
61       *
62       * <P><B>Note:</B> You must specify the parameter's SQL type.
63       *
64       * @param parameterIndex the first parameter is 1, the second is 2, ...
65       * @param sqlType SQL type code defined by java.sql.Types
66       */
67    void setNull(int parameterIndex, int sqlType) throws RemoteException  , SQLException;
68  
69      /**
70       * Set a parameter to a Java boolean value.  The driver converts this
71       * to a SQL BIT value when it sends it to the database.
72       *
73       * @param parameterIndex the first parameter is 1, the second is 2, ...
74       * @param x the parameter value
75       */
76    void setBoolean(int parameterIndex, boolean x)
77    throws RemoteException  , SQLException;
78  
79      /**
80       * Set a parameter to a Java byte value.  The driver converts this
81       * to a SQL TINYINT value when it sends it to the database.
82       *
83       * @param parameterIndex the first parameter is 1, the second is 2, ...
84       * @param x the parameter value
85       */
86      void setByte(int parameterIndex, byte x) throws RemoteException  , SQLException;
87  
88      /**
89       * Set a parameter to a Java short value.  The driver converts this
90       * to a SQL SMALLINT value when it sends it to the database.
91       *
92       * @param parameterIndex the first parameter is 1, the second is 2, ...
93       * @param x the parameter value
94       */
95      void setShort(int parameterIndex, short x) throws RemoteException  , SQLException;
96  
97      /**
98       * Set a parameter to a Java int value.  The driver converts this
99       * to a SQL INTEGER value when it sends it to the database.
100      *
101      * @param parameterIndex the first parameter is 1, the second is 2, ...
102      * @param x the parameter value
103      */
104     void setInt(int parameterIndex, int x) throws RemoteException  , SQLException;
105 
106     /**
107      * Set a parameter to a Java long value.  The driver converts this
108      * to a SQL BIGINT value when it sends it to the database.
109      *
110      * @param parameterIndex the first parameter is 1, the second is 2, ...
111      * @param x the parameter value
112      */
113     void setLong(int parameterIndex, long x) throws RemoteException  , SQLException;
114 
115     /**
116      * Set a parameter to a Java float value.  The driver converts this
117      * to a SQL FLOAT value when it sends it to the database.
118      *
119      * @param parameterIndex the first parameter is 1, the second is 2, ...
120      * @param x the parameter value
121      */
122     void setFloat(int parameterIndex, float x) throws RemoteException  , SQLException;
123 
124     /**
125      * Set a parameter to a Java double value.  The driver converts this
126      * to a SQL DOUBLE value when it sends it to the database.
127      *
128      * @param parameterIndex the first parameter is 1, the second is 2, ...
129      * @param x the parameter value
130      */
131   void setDouble(int parameterIndex, double x) throws RemoteException  , SQLException;
132 
133     /**
134      * Set a parameter to a java.lang.BigDecimal value.  The driver converts
135      * this to a SQL NUMERIC value when it sends it to the database.
136      *
137      * @param parameterIndex the first parameter is 1, the second is 2, ...
138      * @param x the parameter value
139      */
140   void setBigDecimal(int parameterIndex, java.math.BigDecimal   x)
141   throws RemoteException  , SQLException;
142 
143     /**
144      * Set a parameter to a Java String value.  The driver converts this
145      * to a SQL VARCHAR or LONGVARCHAR value (depending on the arguments
146      * size relative to the driver's limits on VARCHARs) when it sends
147      * it to the database.
148      *
149      * @param parameterIndex the first parameter is 1, the second is 2, ...
150      * @param x the parameter value
151      */
152   void setString(int parameterIndex, String   x) throws RemoteException  , SQLException;
153 
154     /**
155      * Set a parameter to a Java array of bytes.  The driver converts
156      * this to a SQL VARBINARY or LONGVARBINARY (depending on the
157      * argument's size relative to the driver's limits on VARBINARYs)
158      * when it sends it to the database.
159      *
160      * @param parameterIndex the first parameter is 1, the second is 2, ...
161      * @param x the parameter value 
162      */
163   void setBytes(int parameterIndex, byte x[]) throws RemoteException  , SQLException;
164 
165     /**
166      * Set a parameter to a java.sql.Date value.  The driver converts this
167      * to a SQL DATE value when it sends it to the database.
168      *
169      * @param parameterIndex the first parameter is 1, the second is 2, ...
170      * @param x the parameter value
171      */
172   void setDate(int parameterIndex, java.sql.Date   x)
173   throws RemoteException  , SQLException;
174 
175     /**
176      * Set a parameter to a java.sql.Time value.  The driver converts this
177      * to a SQL TIME value when it sends it to the database.
178      *
179      * @param parameterIndex the first parameter is 1, the second is 2, ...
180      * @param x the parameter value
181      */
182   void setTime(int parameterIndex, java.sql.Time   x) 
183   throws RemoteException  , SQLException;
184 
185     /**
186      * Set a parameter to a java.sql.Timestamp value.  The driver
187      * converts this to a SQL TIMESTAMP value when it sends it to the
188      * database.
189      *
190      * @param parameterIndex the first parameter is 1, the second is 2, ...
191      * @param x the parameter value 
192      */
193   void setTimestamp(int parameterIndex, java.sql.Timestamp   x)
194   throws RemoteException  , SQLException;
195 
196     /**
197      * When a very large ASCII value is input to a LONGVARCHAR
198      * parameter, it may be more practical to send it via a
199      * java.io.InputStream. JDBC will read the data from the stream
200      * as needed, until it reaches end-of-file.  The JDBC driver will
201      * do any necessary conversion from ASCII to the database char format.
202      * 
203      * <P><B>Note:</B> This stream object can either be a standard
204      * Java stream object or your own subclass that implements the
205      * standard interface.
206      *
207      * @param parameterIndex the first parameter is 1, the second is 2, ...
208      * @param x the java input stream which contains the ASCII parameter value
209      * @param length the number of bytes in the stream 
210      */
211 //TBD  This is a hack (InputStream not serializable)
212 //  void setAsciiStream(int parameterIndex, java.io.InputStream x,
213   void setAsciiStream(int parameterIndex, byte[] x,
214   int length) throws RemoteException  , SQLException;
215 
216     /**
217      * When a very large UNICODE value is input to a LONGVARCHAR
218      * parameter, it may be more practical to send it via a
219      * java.io.InputStream. JDBC will read the data from the stream
220      * as needed, until it reaches end-of-file.  The JDBC driver will
221      * do any necessary conversion from UNICODE to the database char format.
222      * 
223      * <P><B>Note:</B> This stream object can either be a standard
224      * Java stream object or your own subclass that implements the
225      * standard interface.
226      *
227      * @param parameterIndex the first parameter is 1, the second is 2, ...  
228      * @param x the java input stream which contains the
229      * UNICODE parameter value 
230      * @param length the number of bytes in the stream 
231      */
232 //TBD  This is a hack (InputStream not serializable)
233 //  void setUnicodeStream(int parameterIndex, java.io.InputStream x,
234   void setUnicodeStream(int parameterIndex, byte[] x,
235   int length) throws RemoteException  , SQLException;
236 
237     /**
238      * When a very large binary value is input to a LONGVARBINARY
239      * parameter, it may be more practical to send it via a
240      * java.io.InputStream. JDBC will read the data from the stream
241      * as needed, until it reaches end-of-file.
242      * 
243      * <P><B>Note:</B> This stream object can either be a standard
244      * Java stream object or your own subclass that implements the
245      * standard interface.
246      *
247      * @param parameterIndex the first parameter is 1, the second is 2, ...
248      * @param x the java input stream which contains the binary parameter value
249      * @param length the number of bytes in the stream 
250      */
251 //TBD  This is a hack (InputStream not serializable)
252 //  void setBinaryStream(int parameterIndex, java.io.InputStream x,
253   void setBinaryStream(int parameterIndex, byte[] x,
254   int length) throws RemoteException  , SQLException;
255 
256     /**
257      * <P>In general, parameter values remain in force for repeated use of a
258      * Statement. Setting a parameter value automatically clears its
259      * previous value.  However, in some cases it is useful to immediately
260      * release the resources used by the current parameter values; this can
261      * be done by calling clearParameters.
262      */
263   void clearParameters() throws RemoteException  , SQLException;
264 
265   //----------------------------------------------------------------------
266   // Advanced features:
267 
268   /**
269    * <p>Set the value of a parameter using an object; use the
270    * java.lang equivalent objects for integral values.
271    *
272    * <p>The given Java object will be converted to the targetSqlType
273    * before being sent to the database.
274    *
275    * <p>Note that this method may be used to pass datatabase-
276    * specific abstract data types. This is done by using a Driver-
277    * specific Java type and using a targetSqlType of
278    * java.sql.types.OTHER.
279    *
280    * @param parameterIndex The first parameter is 1, the second is 2, ...
281    * @param x The object containing the input parameter value
282    * @param targetSqlType The SQL type (as defined in java.sql.Types) to be 
283    * sent to the database. The scale argument may further qualify this type.
284    * @param scale For java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types
285    *          this is the number of digits after the decimal.  For all other
286    *          types this value will be ignored,
287    * @see Types 
288    */
289   void setObject(int parameterIndex, Object   x, int targetSqlType,
290   int scale) throws RemoteException  , SQLException;
291 
292   /**
293    * This method is like setObject above, but assumes a scale of zero.
294    */
295   void setObject(int parameterIndex, Object   x, int targetSqlType)
296   throws RemoteException  , SQLException;
297 
298   /**
299    * <p>Set the value of a parameter using an object; use the
300    * java.lang equivalent objects for integral values.
301    *
302    * <p>The JDBC specification specifies a standard mapping from
303    * Java Object types to SQL types.  The given argument java object
304    * will be converted to the corresponding SQL type before being
305    * sent to the database.
306    *
307    * <p>Note that this method may be used to pass datatabase
308    * specific abstract data types, by using a Driver specific Java
309    * type.
310    *
311    * @param parameterIndex The first parameter is 1, the second is 2, ...
312    * @param x The object containing the input parameter value 
313    */
314   void setObject(int parameterIndex, Object   x) throws RemoteException  , SQLException;
315 
316   /**
317    * Some prepared statements return multiple results; the execute
318    * method handles these complex statements as well as the simpler
319    * form of statements handled by executeQuery and executeUpdate.
320    *
321    * @see Statement#execute
322    */
323   boolean execute() throws RemoteException  , SQLException;
324     //--------------------------JDBC 2.0-----------------------------
325 
326     /**
327      * JDBC 2.0
328      *
329      * Adds a set of parameters to the batch.
330      * 
331      * @exception SQLException if a database access error occurs
332      * @see Statement#addBatch
333      */
334     void addBatch() throws java.rmi.RemoteException  , SQLException;
335 
336     /**
337      * JDBC 2.0
338      *
339      * Sets the designated parameter to the given <code>Reader</code>
340      * object, which is the given number of characters long.
341      * When a very large UNICODE value is input to a LONGVARCHAR
342      * parameter, it may be more practical to send it via a
343      * java.io.Reader. JDBC will read the data from the stream
344      * as needed, until it reaches end-of-file.  The JDBC driver will
345      * do any necessary conversion from UNICODE to the database char format.
346      * 
347      * <P><B>Note:</B> This stream object can either be a standard
348      * Java stream object or your own subclass that implements the
349      * standard interface.
350      *
351      * @param parameterIndex the first parameter is 1, the second is 2, ...
352      * @param x the java reader which contains the UNICODE data
353      * @param length the number of characters in the stream 
354      * @exception SQLException if a database access error occurs
355      */
356     void setCharacterStream(int parameterIndex,
357                   java.io.Reader   reader,
358               int length) throws java.rmi.RemoteException  , SQLException;
359     // TBD The following hack allows to transfer the reader's content as a char
360     // array... not optimal, but readers are nor serializable!
361     void setCharacterStream(int parameterIndex,
362                   char serialized[],
363               int length) throws java.rmi.RemoteException  , SQLException;
364 
365     /**
366      * JDBC 2.0
367      *
368      * Sets a REF(&lt;structured-type&gt;) parameter.
369      *
370      * @param i the first parameter is 1, the second is 2, ...
371      * @param x an object representing data of an SQL REF Type
372      * @exception SQLException if a database access error occurs
373      */
374     void setRef (int i, Ref x) throws java.rmi.RemoteException  , SQLException;
375 
376     /**
377      * JDBC 2.0
378      *
379      * Sets a BLOB parameter.
380      *
381      * @param i the first parameter is 1, the second is 2, ...
382      * @param x an object representing a BLOB
383      * @exception SQLException if a database access error occurs
384      */
385     void setBlob (int i, Blob x) throws java.rmi.RemoteException  , SQLException;
386 
387     /**
388      * JDBC 2.0
389      *
390      * Sets a CLOB parameter.
391      *
392      * @param i the first parameter is 1, the second is 2, ...
393      * @param x an object representing a CLOB
394      * @exception SQLException if a database access error occurs
395      */
396     void setClob (int i, Clob x) throws java.rmi.RemoteException  , SQLException;
397 
398     /**
399      * JDBC 2.0
400      *
401      * Sets an Array parameter.
402      *
403      * @param i the first parameter is 1, the second is 2, ...
404      * @param x an object representing an SQL array
405      * @exception SQLException if a database access error occurs
406      */
407     void setArray (int i, Array x) throws java.rmi.RemoteException  , SQLException;
408 
409     /**
410      * JDBC 2.0
411      *
412      * Gets the number, types and properties of a ResultSet's columns.
413      *
414      * @return the description of a ResultSet's columns
415      * @exception SQLException if a database access error occurs
416      */
417     RJResultSetMetaDataInterface getMetaData()
418     throws java.rmi.RemoteException  , SQLException;
419 
420     /**
421      * JDBC 2.0
422      *
423      * Sets the designated parameter to a java.sql.Date value,
424      * using the given <code>Calendar</code> object.  The driver uses
425      * the <code>Calendar</code> object to construct an SQL DATE,
426      * which the driver then sends to the database.  With a
427      * a <code>Calendar</code> object, the driver can calculate the date
428      * taking into account a custom timezone and locale.  If no
429      * <code>Calendar</code> object is specified, the driver uses the default
430      * timezone and locale.
431      *
432      * @param parameterIndex the first parameter is 1, the second is 2, ...
433      * @param x the parameter value
434      * @param cal the <code>Calendar</code> object the driver will use
435      *            to construct the date
436      * @exception SQLException if a database access error occurs
437      */
438     void setDate(int parameterIndex, java.sql.Date   x, Calendar   cal)
439         throws java.rmi.RemoteException  , SQLException;
440 
441     /**
442      * JDBC 2.0
443      *
444      * Sets the designated parameter to a java.sql.Time value,
445      * using the given <code>Calendar</code> object.  The driver uses
446      * the <code>Calendar</code> object to construct an SQL TIME,
447      * which the driver then sends to the database.  With a
448      * a <code>Calendar</code> object, the driver can calculate the time
449      * taking into account a custom timezone and locale.  If no
450      * <code>Calendar</code> object is specified, the driver uses the default
451      * timezone and locale.
452      *
453      * @param parameterIndex the first parameter is 1, the second is 2, ...
454      * @param x the parameter value
455      * @param cal the <code>Calendar</code> object the driver will use
456      *            to construct the time
457      * @exception SQLException if a database access error occurs
458      */
459     void setTime(int parameterIndex, java.sql.Time   x, Calendar   cal) 
460         throws java.rmi.RemoteException  , SQLException;
461 
462     /**
463      * JDBC 2.0
464      *
465      * Sets the designated parameter to a java.sql.Timestamp value,
466      * using the given <code>Calendar</code> object.  The driver uses
467      * the <code>Calendar</code> object to construct an SQL TIMESTAMP,
468      * which the driver then sends to the database.  With a
469      * a <code>Calendar</code> object, the driver can calculate the timestamp
470      * taking into account a custom timezone and locale.  If no
471      * <code>Calendar</code> object is specified, the driver uses the default
472      * timezone and locale.
473      *
474      * @param parameterIndex the first parameter is 1, the second is 2, ...
475      * @param x the parameter value 
476      * @param cal the <code>Calendar</code> object the driver will use
477      *            to construct the timestamp
478      * @exception SQLException if a database access error occurs
479      */
480     void setTimestamp(int parameterIndex, java.sql.Timestamp   x, Calendar   cal)
481         throws java.rmi.RemoteException  , SQLException;
482 
483     /**
484      * JDBC 2.0
485      *
486      * Sets the designated parameter to SQL NULL.  This version of setNull should
487      * be used for user-named types and REF type parameters.  Examples
488      * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and 
489      * named array types.
490      *
491      * <P><B>Note:</B> To be portable, applications must give the
492      * SQL type code and the fully-qualified SQL type name when specifying
493      * a NULL user-defined or REF parameter.  In the case of a user-named type 
494      * the name is the type name of the parameter itself.  For a REF 
495      * parameter the name is the type name of the referenced type.  If 
496      * a JDBC driver does not need the type code or type name information, 
497      * it may ignore it.     
498      *
499      * Although it is intended for user-named and Ref parameters,
500      * this method may be used to set a null parameter of any JDBC type.
501      * If the parameter does not have a user-named or REF type, the given
502      * typeName is ignored.
503      *
504      *
505      * @param parameterIndex the first parameter is 1, the second is 2, ...
506      * @param sqlType a value from java.sql.Types
507      * @param typeName the fully-qualified name of an SQL user-named type,
508      *  ignored if the parameter is not a user-named type or REF 
509      * @exception SQLException if a database access error occurs
510      */
511   void setNull (int paramIndex, int sqlType, String   typeName) 
512     throws java.rmi.RemoteException  , SQLException;
513 
514     //------------------------- JDBC 3.0 -----------------------------------
515 
516     /**
517      * Sets the designated parameter to the given <code>java.net.URL</code> value. 
518      * The driver converts this to an SQL <code>DATALINK</code> value
519      * when it sends it to the database.
520      *
521      * @param parameterIndex the first parameter is 1, the second is 2, ...
522      * @param x the <code>java.net.URL</code> object to be set
523      * @exception SQLException if a database access error occurs
524      * @since 1.4
525      */ 
526     void setURL(int parameterIndex, java.net.URL   x)
527     throws java.rmi.RemoteException  , SQLException;
528 
529     /**
530      * Retrieves the number, types and properties of this 
531      * <code>PreparedStatement</code> object's parameters.
532      *
533      * @return a <code>ParameterMetaData</code> object that contains information
534      *         about the number, types and properties of this 
535      *         <code>PreparedStatement</code> object's parameters
536      * @exception SQLException if a database access error occurs
537      * @see ParameterMetaData
538      * @since 1.4
539      */
540     RJParameterMetaDataInterface getParameterMetaData()
541     throws java.rmi.RemoteException  , SQLException;
542   
543 };
544 
545
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags