001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.sql;
023:
024: import java.sql.*;
025: import java.io.InputStream;
026: import java.io.Reader;
027: import java.math.BigDecimal;
028: import java.util.Calendar;
029: import java.util.Map;
030:
031: /**
032: * <p>The RowSet interface adds support to the JDBC API for the JavaBeans(TM) component model. A rowset can
033: * be used as a JavaBean in a visual Bean development environment. A RowSet can be created and configured at
034: * design time and executed at runtime. The RowSet interface provides a set of JavaBeans properties that allow
035: * a RowSet instance to be configured to connect to a JDBC data source and read some data from the data source.
036: * A group of setXXX() methods provide a way to pass input parameters to a rowset. The RowSet interface supports
037: * JavaBeans events, allowing other components in an application to be notified when an important event on a rowset
038: * occurs, such as a change in its value.</p>
039: *
040: * <p>The RowSet interface is unique in that it is intended to be implemented using the rest of the JDBC(TM) API.
041: * In other words, a RowSet implementation is a layer of software that executes "on top" of a JDBC driver.
042: * Implementations of the RowSet interface can be provided by anyone, including JDBC driver vendors who want to provide
043: * a RowSet implementation as part of their JDBC products.</p>
044: *
045: * <p>Rowsets are easy to use. The RowSet interface extends the standard java.sql.ResultSet interface. The RowSetMetaData
046: * interface extends the java.sql.ResultSetMetaData interface. Thus, developers familiar with the JDBC API will have to learn
047: * a minimal number of new APIs to use rowsets. In addition, third-party software tools that work with JDBC ResultSets will
048: * also easily be made to work with rowsets.</p>
049: */
050: public interface RowSet extends ResultSet {
051:
052: /**
053: * RowSet listener registration. Listeners are notified when an event occurs.
054: *
055: * @param rowSetListener - an event listener
056: */
057: public void addRowSetListener(RowSetListener rowSetListener);
058:
059: /**
060: * In general, parameter values remain in force for repeated use of a RowSet. Setting a parameter value
061: * automatically clears its previous value. However, in some cases it is useful to immediately release the
062: * resources used by the current parameter values; this can be done by calling clearParameters.
063: *
064: * @exception SQLException - if a database-access error occurs.
065: */
066: public void clearParameters() throws SQLException;
067:
068: /**
069: * Fills the rowset with data. Execute() may use the following properties: url, data source name, user name,
070: * password, transaction isolation, and type map to create a connection for reading data. Execute may use the
071: * following properties to create a statement to execute a command: command, read only, maximum field size, maximum rows,
072: * escape processing, and query timeout. If the required properties have not been set, an exception is thrown.
073: * If successful, the current contents of the rowset are discarded and the rowset's metadata is also (re)set.
074: * If there are outstanding updates, they are ignored.
075: *
076: * @exception SQLException - if a database-access error occurs.
077: */
078: public void execute() throws SQLException;
079:
080: /**
081: * Get the rowset's command property. The command property contains a command string that can be executed to fill
082: * the rowset with data. The default value is null.
083: *
084: * @return the command string, may be null
085: */
086: public String getCommand();
087:
088: /**
089: * The JNDI name that identifies a JDBC data source. Users should set either the url or data source name properties.
090: * The most recent property set is used to get a connection.
091: *
092: * @return a data source name
093: */
094: public String getDataSourceName();
095:
096: /**
097: * If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database.
098: *
099: * @return true if enabled; false if disabled
100: * @exception SQLException - if a database-access error occurs.
101: */
102: public boolean getEscapeProcessing() throws SQLException;
103:
104: /**
105: * The maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value; it only applies
106: * to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. If the limit is exceeded, the excess data
107: * is silently discarded.
108: *
109: * @return the current max column size limit; zero means unlimited
110: * @exception SQLException - if a database-access error occurs.
111: */
112: public int getMaxFieldSize() throws SQLException;
113:
114: /**
115: * The maxRows limit is the maximum number of rows that a RowSet can contain. If the limit is exceeded, the excess
116: * rows are silently dropped.
117: *
118: * @return the current max row limit; zero means unlimited
119: * @exception SQLException - if a database-access error occurs.
120: */
121: public int getMaxRows() throws SQLException;
122:
123: /**
124: * The password used to create a database connection. The password property is set at runtime before calling execute().
125: * It is not usually part of the serialized state of a rowset object.
126: *
127: * @return a password
128: */
129: public String getPassword();
130:
131: /**
132: * The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute.
133: * If the limit is exceeded, a SQLException is thrown.
134: *
135: * @return the current query timeout limit in seconds; zero means unlimited
136: * @exception SQLException - if a database-access error occurs.
137: */
138: public int getQueryTimeout() throws SQLException;
139:
140: /**
141: * The transaction isolation property contains the JDBC transaction isolation level used.
142: *
143: * @return the transaction isolation level
144: */
145: public int getTransactionIsolation();
146:
147: /**
148: * Get the type-map object associated with this rowset. By default, the map returned is empty.
149: *
150: * @return a map object
151: * @exception SQLException - if a database-access error occurs.
152: */
153: public Map getTypeMap() throws SQLException;
154:
155: /**
156: * Get the url used to create a JDBC connection. The default value is null.
157: *
158: * @return a string url
159: * @exception SQLException - if a database-access error occurs.
160: */
161: public String getUrl() throws SQLException;
162:
163: /**
164: * The username used to create a database connection. The username property is set at runtime before calling execute().
165: * It is not usually part of the serialized state of a rowset object.
166: *
167: * @return a user name
168: */
169: public String getUsername();
170:
171: /**
172: * A rowset may be read-only. Attempts to update a read-only rowset will result in an SQLException being thrown.
173: * Rowsets are updateable, by default, if updates are possible.
174: *
175: * @return true if not updatable, false otherwise
176: */
177: public boolean isReadOnly();
178:
179: /**
180: * RowSet listener deregistration.
181: *
182: * @param rowSetListener - an event listener
183: */
184: public void removeRowSetListener(RowSetListener rowSetListener);
185:
186: /**
187: * Set an Array parameter.
188: *
189: * @param i - the first parameter is 1, the second is 2, ...
190: * @param array - an object representing an SQL array
191: * @exception SQLException - if a database-access error occurs.
192: */
193: public void setArray(int i, Array array) throws SQLException;
194:
195: /**
196: * <p>When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via
197: * a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file.</p>
198: *
199: * <p><b>Note:</b> This stream object can either be a standard Java stream object or your own subclass that implements
200: * the standard interface.</p>
201: *
202: * @param i - the first parameter is 1, the second is 2, ...
203: * @param inputStream - the java input stream which contains the ASCII parameter value
204: * @param j - the number of bytes in the stream
205: * @exception SQLException - if a database-access error occurs.
206: */
207: public void setAsciiStream(int i, InputStream inputStream, int j)
208: throws SQLException;
209:
210: /**
211: * Set a parameter to a java.lang.BigDecimal value.
212: *
213: * @param i - the first parameter is 1, the second is 2, ...
214: * @param bigDecimal - the parameter value
215: * @exception SQLException - if a database-access error occurs.
216: */
217: public void setBigDecimal(int i, BigDecimal bigDecimal)
218: throws SQLException;
219:
220: /**
221: * <p>When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it
222: * via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file.</p>
223: *
224: * <p><b>Note:</b> This stream object can either be a standard Java stream object or your own subclass that implements
225: * the standard interface.</p>
226: *
227: * @param i - the first parameter is 1, the second is 2, ...
228: * @param inputStream - the java input stream which contains the binary parameter value
229: * @param j - the number of bytes in the stream
230: * @exception SQLException - if a database-access error occurs.
231: */
232: public void setBinaryStream(int i, InputStream inputStream, int j)
233: throws SQLException;
234:
235: /**
236: * Set a BLOB parameter.
237: *
238: * @param i - the first parameter is 1, the second is 2, ...
239: * @param blob - an object representing a BLOB
240: * @exception SQLException - if a database-access error occurs.
241: */
242: public void setBlob(int i, Blob blob) throws SQLException;
243:
244: /**
245: * Set a parameter to a Java boolean value.
246: *
247: * @param i - the first parameter is 1, the second is 2, ...
248: * @param flag - the parameter value
249: * @exception SQLException - if a database-access error occurs.
250: */
251: public void setBoolean(int i, boolean flag) throws SQLException;
252:
253: /**
254: * Set a parameter to a Java byte value.
255: *
256: * @param i - the first parameter is 1, the second is 2, ...
257: * @param b - the parameter value
258: * @exception SQLException - if a database-access error occurs.
259: */
260: public void setByte(int i, byte b) throws SQLException;
261:
262: /**
263: * Set a parameter to a Java array of bytes.
264: *
265: * @param i - the first parameter is 1, the second is 2, ...
266: * @param ab - the parameter value
267: * @exception SQLException - if a database-access error occurs.
268: */
269: public void setBytes(int i, byte ab[]) throws SQLException;
270:
271: /**
272: * <p>When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a
273: * java.io.Reader. JDBC will read the data from the stream as needed, until it reaches end-of-file.</p>
274: *
275: * <p><b>Note:</b> This stream object can either be a standard Java stream object or your own subclass that implements
276: * the standard interface.</p>
277: *
278: * @param i - the first parameter is 1, the second is 2, ...
279: * @param reader - the java reader which contains the UNICODE data
280: * @param j - the number of characters in the stream
281: * @exception SQLException - if a database-access error occurs.
282: */
283: public void setCharacterStream(int i, Reader reader, int j)
284: throws SQLException;
285:
286: /**
287: * Set a CLOB parameter.
288: *
289: * @param i - the first parameter is 1, the second is 2, ...
290: * @param clob - an object representing a CLOB
291: * @exception SQLException - if a database-access error occurs.
292: */
293: public void setClob(int i, Clob clob) throws SQLException;
294:
295: /**
296: * Set the rowset's command property. This property is optional. The command property may not be needed
297: * when a rowset is produced by a data source that doesn't support commands, such as a spreadsheet.
298: *
299: * @param string - a command string, may be null
300: * @exception SQLException - if a database-access error occurs.
301: */
302: public void setCommand(String string) throws SQLException;
303:
304: /**
305: * Set the rowset concurrency.
306: *
307: * @param i - a value from ResultSet.CONCUR_XXX
308: * @exception SQLException - if a database-access error occurs.
309: */
310: public void setConcurrency(int i) throws SQLException;
311:
312: /**
313: * Set the data source name.
314: *
315: * @param string - a data source name
316: * @exception SQLException - if a database-access error occurs.
317: */
318: public void setDataSourceName(String string) throws SQLException;
319:
320: /**
321: * Set a parameter to a java.sql.Date value.
322: *
323: * @param i - the first parameter is 1, the second is 2, ...
324: * @param date - the parameter value
325: * @exception SQLException - if a database-access error occurs.
326: */
327: public void setDate(int i, Date date) throws SQLException;
328:
329: /**
330: * Set a parameter to a java.sql.Date value. The driver converts this to a SQL DATE value when
331: * it sends it to the database.
332: *
333: * @param i - the first parameter is 1, the second is 2, ...
334: * @param date - the parameter value
335: * @param calendar - the calendar used
336: * @exception SQLException - if a database-access error occurs.
337: */
338: public void setDate(int i, Date date, Calendar calendar)
339: throws SQLException;
340:
341: /**
342: * Set a parameter to a Java double value.
343: *
344: * @param i - the first parameter is 1, the second is 2, ...
345: * @param d - the parameter value
346: * @exception SQLException - if a database-access error occurs.
347: */
348: public void setDouble(int i, double d) throws SQLException;
349:
350: /**
351: * If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database.
352: *
353: * @param flag - true to enable; false to disable
354: * @exception SQLException - if a database-access error occurs.
355: */
356: public void setEscapeProcessing(boolean flag) throws SQLException;
357:
358: /**
359: * Set a parameter to a Java float value. The driver converts this to a SQL FLOAT value when it sends it to the database.
360: *
361: * @param i - the first parameter is 1, the second is 2, ...
362: * @param f - the parameter value
363: * @exception SQLException - if a database-access error occurs.
364: */
365: public void setFloat(int i, float f) throws SQLException;
366:
367: /**
368: * Set a parameter to a Java int value.
369: *
370: * @param i - the first parameter is 1, the second is 2, ...
371: * @param j - the parameter value
372: * @exception SQLException - if a database-access error occurs.
373: */
374: public void setInt(int i, int j) throws SQLException;
375:
376: /**
377: * Set a parameter to a Java long value.
378: *
379: * @param i - the first parameter is 1, the second is 2, ...
380: * @param j - the parameter value
381: * @exception SQLException - if a database-access error occurs.
382: */
383: public void setLong(int i, long j) throws SQLException;
384:
385: /**
386: * The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value;
387: * it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. If the limit is exceeded,
388: * the excess data is silently discarded. For maximum portability use values greater than 256.
389: *
390: * @param i - the new max column size limit; zero means unlimited
391: * @exception SQLException - if a database-access error occurs.
392: */
393: public void setMaxFieldSize(int i) throws SQLException;
394:
395: /**
396: * The maxRows limit is set to limit the number of rows that any RowSet can contain. If the limit is exceeded,
397: * the excess rows are silently dropped.
398: *
399: * @param i - the new max rows limit; zero means unlimited
400: * @exception SQLException - if a database-access error occurs.
401: */
402: public void setMaxRows(int i) throws SQLException;
403:
404: /**
405: * <p>Set a parameter to SQL NULL.</p>
406: *
407: * <p><b>Note:</b> You must specify the parameter's SQL type.</p>
408: *
409: * @param parameterIndex - the first parameter is 1, the second is 2, ...
410: * @param sqlType - SQL type code defined by java.sql.Types
411: * @exception SQLException - if a database-access error occurs.
412: */
413: public void setNull(int parameterIndex, int sqlType)
414: throws SQLException;
415:
416: /**
417: * <p>JDBC 2.0 Set a parameter to SQL NULL. This version of setNull should be used for user-named types and
418: * REF type parameters. Examples of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and named array types.</p>
419: *
420: * <p><b>Note:</b> To be portable, applications must give the SQL type code and the fully qualified SQL type name when
421: * specifying a NULL user-named or REF parameter. In the case of a user-named type the name is the type name of the
422: * parameter itself. For a REF parameter the name is the type name of the referenced type. If a JDBC driver does not
423: * need the type code or type name information, it may ignore it. Although it is intended for user-named and Ref parameters,
424: * this method may be used to set a null parameter of any JDBC type. If the parameter does not have a user-named or REF
425: * type then the typeName is ignored.</p>
426: *
427: * @param paramIndex - the first parameter is 1, the second is 2, ...
428: * @param sqlType - a value from java.sql.Types
429: * @param typeName - the fully qualified name of a SQL user-named type, ignored if the parameter is not a user-named type or REF
430: * @exception SQLException - if a database-access error occurs.
431: */
432: public void setNull(int paramIndex, int sqlType, String typeName)
433: throws SQLException;
434:
435: /**
436: * <p>Set the value of a parameter using an object; use the java.lang equivalent objects for integral values.</p>
437: *
438: * <p>The JDBC specification specifies a standard mapping from Java Object types to SQL types. The given argument
439: * java object will be converted to the corresponding SQL type before being sent to the database.</p>
440: *
441: * <p>Note that this method may be used to pass datatabase specific abstract data types, by using a Driver specific
442: * Java type. If the object is of a class implementing SQLData, the rowset should call its method writeSQL() to write
443: * it to the SQL data stream. else If the object is of a class implementing Ref, Blob, Clob, Struct, or Array then pass
444: * it to the database as a value of the corresponding SQL type. Raise an exception if there is an ambiguity, for example,
445: * if the object is of a class implementing more than one of those interfaces.</p>
446: *
447: * @param parameterIndex - The first parameter is 1, the second is 2, ...
448: * @param object - The object containing the input parameter value
449: * @exception SQLException - if a database-access error occurs.
450: */
451: public void setObject(int parameterIndex, Object object)
452: throws SQLException;
453:
454: /**
455: * This method is like setObject above, but the scale used is the scale of the second parameter. Scalar values have a scale
456: * of zero. Literal values have the scale present in the literal. While it is supported, it is not recommended that this
457: * method not be called with floating point input values.
458: *
459: * @param parameterIndex - The first parameter is 1, the second is 2, ...
460: * @param object - The object containing the input parameter value
461: * @param targetSqlType - The SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may
462: * further qualify this type.
463: * @exception SQLException - if a database-access error occurs.
464: */
465: public void setObject(int parameterIndex, Object object,
466: int targetSqlType) throws SQLException;
467:
468: /**
469: * <p>Set the value of a parameter using an object; use the java.lang equivalent objects for integral values.</p>
470: *
471: * <p>The given Java object will be converted to the targetSqlType before being sent to the database. If the object
472: * is of a class implementing SQLData, the rowset should call its method writeSQL() to write it to the SQL data stream.
473: * else If the object is of a class implementing Ref, Blob, Clob, Struct, or Array then pass it to the database as
474: * a value of the corresponding SQL type.</p>
475: *
476: * <p>Note that this method may be used to pass datatabase- specific abstract data types.</p>
477: *
478: * @param parameterIndex - The first parameter is 1, the second is 2, ...
479: * @param object - The object containing the input parameter value
480: * @param j - The SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may further qualify this type.
481: * @param scale - For java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types this is the number of digits after the decimal.
482: * For all other types this value will be ignored
483: * @exception SQLException - if a database-access error occurs.
484: */
485: public void setObject(int parameterIndex, Object object, int j,
486: int scale) throws SQLException;
487:
488: /**
489: * Set the password.
490: *
491: * @param string - the password string
492: * @exception SQLException - if a database-access error occurs.
493: */
494: public void setPassword(String string) throws SQLException;
495:
496: /**
497: * The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute.
498: * If the limit is exceeded, a SQLException is thrown.
499: *
500: * @param seconds - the new query timeout limit in seconds; zero means unlimited
501: * @exception SQLException - if a database-access error occurs.
502: */
503: public void setQueryTimeout(int seconds) throws SQLException;
504:
505: /**
506: * Set the read-onlyness of the rowset
507: *
508: * @param flag - true if read-only, false otherwise
509: * @exception SQLException - if a database-access error occurs.
510: */
511: public void setReadOnly(boolean flag) throws SQLException;
512:
513: /**
514: * Set a REF(<structured-type>) parameter.
515: *
516: * @param i - the first parameter is 1, the second is 2, ...
517: * @param ref - an object representing data of an SQL REF Type
518: * @exception SQLException - if a database-access error occurs.
519: */
520: public void setRef(int i, Ref ref) throws SQLException;
521:
522: /**
523: * Set a parameter to a Java short value.
524: *
525: * @param i - the first parameter is 1, the second is 2, ...
526: * @param s - the parameter value
527: * @exception SQLException - if a database-access error occurs.
528: */
529: public void setShort(int i, short s) throws SQLException;
530:
531: /**
532: * Set a parameter to a Java String value.
533: *
534: * @param parameterIndex - the first parameter is 1, the second is 2, ...
535: * @param string - the parameter value
536: * @exception SQLException - if a database-access error occurs.
537: */
538: public void setString(int parameterIndex, String string)
539: throws SQLException;
540:
541: /**
542: * Set a parameter to a java.sql.Time value.
543: *
544: * @param parameterIndex - the first parameter is 1, the second is 2, ...
545: * @param time - the parameter value
546: * @exception SQLException - if a database-access error occurs.
547: */
548: public void setTime(int parameterIndex, Time time)
549: throws SQLException;
550:
551: /**
552: * Set a parameter to a java.sql.Time value.
553: *
554: * @param parameterIndex - the first parameter is 1, the second is 2, ...
555: * @param time - the parameter value
556: * @param calendar - the calendar used
557: * @exception SQLException - if a database-access error occurs.
558: */
559: public void setTime(int parameterIndex, Time time, Calendar calendar)
560: throws SQLException;
561:
562: /**
563: * Set a parameter to a java.sql.Timestamp value.
564: *
565: * @param parameterIndex - the first parameter is 1, the second is 2, ...
566: * @param timestamp - the parameter value
567: * @exception SQLException - if a database-access error occurs.
568: */
569: public void setTimestamp(int parameterIndex, Timestamp timestamp)
570: throws SQLException;
571:
572: /**
573: * Set a parameter to a java.sql.Timestamp value.
574: *
575: * @param parameterIndex - the first parameter is 1, the second is 2, ...
576: * @param timestamp - the parameter value
577: * @param calendar - the calendar used
578: * @exception SQLException - if a database-access error occurs.
579: */
580: public void setTimestamp(int parameterIndex, Timestamp timestamp,
581: Calendar calendar) throws SQLException;
582:
583: /**
584: * Set the transaction isolation.
585: *
586: * @param level - the transaction isolation level
587: * @exception SQLException - if a database-access error occurs.
588: */
589: public void setTransactionIsolation(int level) throws SQLException;
590:
591: /**
592: * Set the rowset type.
593: *
594: * @param i - a value from ResultSet.TYPE_XXX
595: * @exception SQLException - if a database-access error occurs.
596: */
597: public void setType(int i) throws SQLException;
598:
599: /**
600: * Install a type-map object as the default type-map for this rowset.
601: *
602: * @param map - a map object
603: * @exception SQLException - if a database-access error occurs.
604: */
605: public void setTypeMap(Map map) throws SQLException;
606:
607: /**
608: * Set the url used to create a connection. Setting this property is optional. If a url is used, a JDBC driver that
609: * accepts the url must be loaded by the application before the rowset is used to connect to a database. The rowset
610: * will use the url internally to create a database connection when reading or writing data. Either a url or a data
611: * source name is used to create a connection, whichever was specified most recently.
612: *
613: * @param url - a string value, may be null
614: * @exception SQLException - if a database-access error occurs.
615: */
616: public void setUrl(String url) throws SQLException;
617:
618: /**
619: * Set the user name.
620: *
621: * @param name - a user name
622: * @exception SQLException - if a database-access error occurs.
623: */
624: public void setUsername(String name) throws SQLException;
625: }
|