/*

 * Copyright 2000-2006 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.sql;

import java.sql.*;

import java.io.*;

import java.math.*;

import java.util.*;

/**

 * The interface that adds support to the JDBC API for the

 * JavaBeans<sup><font size=-2>TM</font></sup> component model.

 * A rowset, which can be used as a JavaBeans component in

 * a visual Bean development environment, can be created and

 * configured at design time and executed at run time.

 * <P>

 * The <code>RowSet</code>

 * interface provides a set of JavaBeans properties that allow a <code>RowSet</code>

 * instance to be configured to connect to a JDBC data source and read

 * some data from the data source.  A group of setter methods (<code>setInt</code>,

 * <code>setBytes</code>, <code>setString</code>, and so on)

 * provide a way to pass input parameters to a rowset's command property.

 * This command is the SQL query the rowset uses when it gets its data from

 * a relational database, which is generally the case.

 * <P>

 * The <code>RowSet</code>

 * interface supports JavaBeans events, allowing other components in an

 * application to be notified when an event occurs on a rowset,

 * such as a change in its value.

 *

 * <P>The <code>RowSet</code> interface is unique in that it is intended to be

 * implemented using the rest of the JDBC API.  In other words, a

 * <code>RowSet</code> implementation is a layer of software that executes "on top"

 * of a JDBC driver.  Implementations of the <code>RowSet</code> interface can

 * be provided by anyone, including JDBC driver vendors who want to

 * provide a <code>RowSet</code> implementation as part of their JDBC products.

 * <P>

 * A <code>RowSet</code> object may make a connection with a data source and

 * maintain that connection throughout its life cycle, in which case it is

 * called a <i>connected</i> rowset.  A rowset may also make a connection with

 * a data source, get data from it, and then close the connection. Such a rowset

 * is called a <i>disconnected</i> rowset.  A disconnected rowset may make

 * changes to its data while it is disconnected and then send the changes back

 * to the original source of the data, but it must reestablish a connection to do so.

 * <P>

 * A disconnected rowset may have a reader (a <code>RowSetReader</code> object)

 * and a writer (a <code>RowSetWriter</code> object) associated with it.

 * The reader may be implemented in many different ways to populate a rowset

 * with data, including getting data from a non-relational data source. The

 * writer can also be implemented in many different ways to propagate changes

 * made to the rowset's data back to the underlying data source.

 * <P>

 * Rowsets are easy to use.  The <code>RowSet</code> interface extends the standard

 * <code>java.sql.ResultSet</code> interface.  The <code>RowSetMetaData</code>

 * interface extends the <code>java.sql.ResultSetMetaData</code> interface.

 * Thus, developers familiar

 * with the JDBC API will have to learn a minimal number of new APIs to

 * use rowsets.  In addition, third-party software tools that work with

 * JDBC <code>ResultSet</code> objects will also easily be made to work with rowsets.

 *

 * @since 1.4

 */

public interface RowSet extends ResultSet {

  //-----------------------------------------------------------------------

  // Properties

  //-----------------------------------------------------------------------

  //-----------------------------------------------------------------------

  // The following properties may be used to create a Connection.

  //-----------------------------------------------------------------------

  /**

   * Retrieves the url property this <code>RowSet</code> object will use to

   * create a connection if it uses the <code>DriverManager</code>

   * instead of a <code>DataSource</code> object to establish the connection.

   * The default value is <code>null</code>.

   *

   * @return a string url

   * @exception SQLException if a database access error occurs

   * @see #setUrl

   */

  String getUrl() throws SQLException;

  /**

   * Sets the URL this <code>RowSet</code> object will use when it uses the

   * <code>DriverManager</code> to create a connection.

   *

   * Setting this property is optional.  If a URL is used, a JDBC driver

   * that accepts the URL must be loaded before the

   * rowset is used to connect to a database.  The rowset will use the URL

   * internally to create a database connection when reading or writing

   * data.  Either a URL or a data source name is used to create a

   * connection, whichever was set to non null value most recently.

   *

   * @param url a string value; may be <code>null</code>

   * @exception SQLException if a database access error occurs

   * @see #getUrl

   */

  void setUrl(String url) throws SQLException;

  /**

   * Retrieves the logical name that identifies the data source for this

   * <code>RowSet</code> object.

   *

   * @return a data source name

   * @see #setDataSourceName

   * @see #setUrl

   */

  String getDataSourceName();

  /**

   * Sets the data source name property for this <code>RowSet</code> object to the

   * given <code>String</code>.

   * <P>

   * The value of the data source name property can be used to do a lookup of

   * a <code>DataSource</code> object that has been registered with a naming

   * service.  After being retrieved, the <code>DataSource</code> object can be

   * used to create a connection to the data source that it represents.

   *

   * @param name the logical name of the data source for this <code>RowSet</code>

   *        object; may be <code>null</code>

   * @exception SQLException if a database access error occurs

   * @see #getDataSourceName

   */

  void setDataSourceName(String name) throws SQLException;

  /**

   * Retrieves the username used to create a database connection for this

   * <code>RowSet</code> object.

   * The username property is set at run time before calling the method

   * <code>execute</code>.  It is

   * not usually part of the serialized state of a <code>RowSet</code> object.

   *

   * @return the username property

   * @see #setUsername

   */

  String getUsername();

  /**

   * Sets the username property for this <code>RowSet</code> object to the

   * given <code>String</code>.

   *

   * @param name a user name

   * @exception SQLException if a database access error occurs

   * @see #getUsername

   */

  void setUsername(String name) throws SQLException;

  /**

   * Retrieves the password used to create a database connection.

   * The password property is set at run time before calling the method

   * <code>execute</code>.  It is not usually part of the serialized state

   * of a <code>RowSet</code> object.

   *

   * @return the password for making a database connection

   * @see #setPassword

   */

  String getPassword();

  /**

   * Sets the database password for this <code>RowSet</code> object to

   * the given <code>String</code>.

   *

   * @param password the password string

   * @exception SQLException if a database access error occurs

   * @see #getPassword

   */

  void setPassword(String password) throws SQLException;

  /**

   * Retrieves the transaction isolation level set for this

   * <code>RowSet</code> object.

   *

   * @return the transaction isolation level; one of

   *      <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,

   *      <code>Connection.TRANSACTION_READ_COMMITTED</code>,

   *      <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or

   *      <code>Connection.TRANSACTION_SERIALIZABLE</code>

   * @see #setTransactionIsolation

   */

  int getTransactionIsolation();

  /**

   * Sets the transaction isolation level for this <code>RowSet</code> obejct.

   *

   * @param level the transaction isolation level; one of

   *      <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,

   *      <code>Connection.TRANSACTION_READ_COMMITTED</code>,

   *      <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or

   *      <code>Connection.TRANSACTION_SERIALIZABLE</code>

   * @exception SQLException if a database access error occurs

   * @see #getTransactionIsolation

   */

  void setTransactionIsolation(int level) throws SQLException;

  /**

   * Retrieves the <code>Map</code> object associated with this

   * <code>RowSet</code> object, which specifies the custom mapping

   * of SQL user-defined types, if any.  The default is for the

   * type map to be empty.

   *

   * @return a <code>java.util.Map</code> object containing the names of

   *         SQL user-defined types and the Java classes to which they are

   *         to be mapped

   *

   * @exception SQLException if a database access error occurs

   * @see #setTypeMap

   */

   java.util.Map<String,Class<?>> getTypeMap() throws SQLException;

  /**

   * Installs the given <code>java.util.Map</code> object as the default

   * type map for this <code>RowSet</code> object. This type map will be

   * used unless another type map is supplied as a method parameter.

   *

   * @param map  a <code>java.util.Map</code> object containing the names of

   *         SQL user-defined types and the Java classes to which they are

   *         to be mapped

   * @exception SQLException if a database access error occurs

   * @see #getTypeMap

   */

   void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException;

  //-----------------------------------------------------------------------

  // The following properties may be used to create a Statement.

  //-----------------------------------------------------------------------

  /**

   * Retrieves this <code>RowSet</code> object's command property.

   *

   * The command property contains a command string, which must be an SQL

   * query, that can be executed to fill the rowset with data.

   * The default value is <code>null</code>.

   *

   * @return the command string; may be <code>null</code>

   * @see #setCommand

   */

  String getCommand();

  /**

   * Sets this <code>RowSet</code> object's command property to the given

   * SQL query.

   *

   * This property is optional

   * when a rowset gets its data from a data source that does not support

   * commands, such as a spreadsheet.

   *

   * @param cmd the SQL query that will be used to get the data for this

   *        <code>RowSet</code> object; may be <code>null</code>

   * @exception SQLException if a database access error occurs

   * @see #getCommand

   */

  void setCommand(String cmd) throws SQLException;

  /**

   * Retrieves whether this <code>RowSet</code> object is read-only.

   * If updates are possible, the default is for a rowset to be

   * updatable.

   * <P>

   * Attempts to update a read-only rowset will result in an

   * <code>SQLException</code> being thrown.

   *

   * @return <code>true</code> if this <code>RowSet</code> object is

   *         read-only; <code>false</code> if it is updatable

   * @see #setReadOnly

   */

  boolean isReadOnly();

  /**

   * Sets whether this <code>RowSet</code> object is read-only to the

   * given <code>boolean</code>.

   *

   * @param value <code>true</code> if read-only; <code>false</code> if

   *        updatable

   * @exception SQLException if a database access error occurs

   * @see #isReadOnly

   */

  void setReadOnly(boolean value) throws SQLException;

  /**

   * Retrieves the maximum number of bytes that may be returned

   * for certain column values.

   * This limit applies only to <code>BINARY</code>,

   * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>,

   * <code>VARCHAR</code>, <code>LONGVARCHAR</code>, <code>NCHAR</code>

   * and <code>NVARCHAR</code> columns.

   * If the limit is exceeded, the excess data is silently discarded.

   *

   * @return the current maximum column size limit; zero means that there

   *          is no limit

   * @exception SQLException if a database access error occurs

   * @see #setMaxFieldSize

   */

  int getMaxFieldSize() throws SQLException;

  /**

   * Sets the maximum number of bytes that can be returned for a column

   * value to the given number of bytes.

   * This limit applies only to <code>BINARY</code>,

   * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>,

   * <code>VARCHAR</code>, <code>LONGVARCHAR</code>, <code>NCHAR</code>

   * and <code>NVARCHAR</code> columns.

   * If the limit is exceeded, the excess data is silently discarded.

   * For maximum portability, use values greater than 256.

   *

   * @param max the new max column size limit in bytes; zero means unlimited

   * @exception SQLException if a database access error occurs

   * @see #getMaxFieldSize

   */

  void setMaxFieldSize(int max) throws SQLException;

  /**

   * Retrieves the maximum number of rows that this <code>RowSet</code>

   * object can contain.

   * If the limit is exceeded, the excess rows are silently dropped.

   *

   * @return the current maximum number of rows that this <code>RowSet</code>

   *         object can contain; zero means unlimited

   * @exception SQLException if a database access error occurs

   * @see #setMaxRows

   */

  int getMaxRows() throws SQLException;

  /**

   * Sets the maximum number of rows that this <code>RowSet</code>

   * object can contain to the specified number.

   * If the limit is exceeded, the excess rows are silently dropped.

   *

   * @param max the new maximum number of rows; zero means unlimited

   * @exception SQLException if a database access error occurs

   * @see #getMaxRows

   */

  void setMaxRows(int max) throws SQLException;

  /**

   * Retrieves whether escape processing is enabled for this

   * <code>RowSet</code> object.

   * If escape scanning is enabled, which is the default, the driver will do

   * escape substitution before sending an SQL statement to the database.

   *

   * @return <code>true</code> if escape processing is enabled;

   *         <code>false</code> if it is disabled

   * @exception SQLException if a database access error occurs

   * @see #setEscapeProcessing

   */

  boolean getEscapeProcessing() throws SQLException;

  /**

   * Sets escape processing for this <code>RowSet</code> object on or

   * off. If escape scanning is on (the default), the driver will do

   * escape substitution before sending an SQL statement to the database.

   *

   * @param enable <code>true</code> to enable escape processing;

   *        <code>false</code> to disable it

   * @exception SQLException if a database access error occurs

   * @see #getEscapeProcessing

   */

  void setEscapeProcessing(boolean enable) throws SQLException;

  /**

   * Retrieves the maximum number of seconds the driver will wait for

   * a statement to execute.

   * If this limit is exceeded, an <code>SQLException</code> is thrown.

   *

   * @return the current query timeout limit in seconds; zero means

   *          unlimited

   * @exception SQLException if a database access error occurs

   * @see #setQueryTimeout

   */

  int getQueryTimeout() throws SQLException;

  /**

   * Sets the maximum time the driver will wait for

   * a statement to execute to the given number of seconds.

   * If this limit is exceeded, an <code>SQLException</code> is thrown.

   *

   * @param seconds the new query timeout limit in seconds; zero means

   *        that there is no limit

   * @exception SQLException if a database access error occurs

   * @see #getQueryTimeout

   */

  void setQueryTimeout(int seconds) throws SQLException;

  /**

   * Sets the type of this <code>RowSet</code> object to the given type.

   * This method is used to change the type of a rowset, which is by

   * default read-only and non-scrollable.

   *

   * @param type one of the <code>ResultSet</code> constants specifying a type:

   *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,

   *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or

   *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>

   * @exception SQLException if a database access error occurs

   * @see java.sql.ResultSet#getType

   */

  void setType(int type) throws SQLException;

  /**

   * Sets the concurrency of this <code>RowSet</code> object to the given

   * concurrency level. This method is used to change the concurrency level

   * of a rowset, which is by default <code>ResultSet.CONCUR_READ_ONLY</code>

   *

   * @param concurrency one of the <code>ResultSet</code> constants specifying a

   *        concurrency level:  <code>ResultSet.CONCUR_READ_ONLY</code> or

   *        <code>ResultSet.CONCUR_UPDATABLE</code>

   * @exception SQLException if a database access error occurs

   * @see ResultSet#getConcurrency

   */

  void setConcurrency(int concurrency) throws SQLException;

  //-----------------------------------------------------------------------

  // Parameters

  //-----------------------------------------------------------------------

  /**

   * The <code>RowSet</code> setter methods are used to set any input parameters

   * needed by the <code>RowSet</code> object's command.

   * Parameters are set at run time, as opposed to design time.

   */

  /**

   * Sets the designated parameter in this <code>RowSet</code> object's SQL

   * command to SQL <code>NULL</code>.

   *

   * <P><B>Note:</B> You must specify the parameter's SQL type.

   *

   * @param parameterIndex the first parameter is 1, the second is 2, ...

   * @param sqlType a SQL type code defined by <code>java.sql.Types</code>

   * @exception SQLException if a database access error occurs

   */

  void setNull(int parameterIndex, int sqlType) throws SQLException;

  /**

     * Sets the designated parameter to SQL <code>NULL</code>.

     *

     * <P><B>Note:</B> You must specify the parameter's SQL type.

     *

     * @param parameterName the name of the parameter

     * @param sqlType the SQL type code defined in <code>java.sql.Types</code>

     * @exception SQLException if a database access error occurs or

     * this method is called on a closed <code>CallableStatement</code>

     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

     * this method

     * @since 1.4

     */

    void setNull(String parameterName, int sqlType) throws SQLException;

  /**

   * Sets the designated parameter in this <code>RowSet</code> object's SQL

   * command to SQL <code>NULL</code>. This version of the method <code>setNull</code>

   * should  be used for SQL user-defined types (UDTs) and <code>REF</code> type

   * parameters.  Examples of UDTs include: <code>STRUCT</code>, <code>DISTINCT</code>,

   * <code>JAVA_OBJECT</code>, and named array types.

   *

   * <P><B>Note:</B> To be portable, applications must give the

   * SQL type code and the fully qualified SQL type name when specifying

   * a NULL UDT or <code>REF</code> parameter.  In the case of a UDT,

   * the name is the type name of the parameter itself.  For a <code>REF</code>

   * parameter, the name is the type name of the referenced type.  If

   * a JDBC driver does not need the type code or type name information,

   * it may ignore it.

   *

   * Although it is intended for UDT and <code>REF</code> parameters,

   * this method may be used to set a null parameter of any JDBC type.

   * If the parameter does not have a user-defined or <code>REF</code> type,

   * the typeName parameter is ignored.

   *

   *

   * @param paramIndex the first parameter is 1, the second is 2, ...

   * @param sqlType a value from <code>java.sql.Types</code>

   * @param typeName the fully qualified name of an SQL UDT or the type

   *        name of the SQL structured type being referenced by a <code>REF</code>

   *        type; ignored if the parameter is not a UDT or <code>REF</code> type

   * @exception SQLException if a database access error occurs

   */

  void setNull (int paramIndex, int sqlType, String typeName)

    throws SQLException;

  /**

     * Sets the designated parameter to SQL <code>NULL</code>.

     * This version of the method <code>setNull</code> should

     * be used for user-defined types and REF type parameters.  Examples

     * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and

     * named array types.

     *

     * <P><B>Note:</B> To be portable, applications must give the

     * SQL type code and the fully-qualified SQL type name when specifying

     * a NULL user-defined or REF parameter.  In the case of a user-defined type

     * the name is the type name of the parameter itself.  For a REF

     * parameter, the name is the type name of the referenced type.  If

     * a JDBC driver does not need the type code or type name information,

     * it may ignore it.

     *

     * Although it is intended for user-defined and Ref parameters,

     * this method may be used to set a null parameter of any JDBC type.

     * If the parameter does not have a user-defined or REF type, the given

     * typeName is ignored.

     *

     *

     * @param parameterName the name of the parameter

     * @param sqlType a value from <code>java.sql.Types</code>

     * @param typeName the fully-qualified name of an SQL user-defined type;

     *        ignored if the parameter is not a user-defined type or

     *        SQL <code>REF</code> value