/*

 * 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.  Oracle designates this

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

 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.sql.rowset;

import java.sql.*;

import javax.sql.*;

import java.util.*;

import java.io.*;

import java.math.*;

import java.io.Serializable;

import javax.sql.rowset.serial.*;

/**

 * An abstract class providing a <code>RowSet</code> object with its basic functionality.

 * The basic functions include having properties and sending event notifications,

 * which all JavaBeans™ components must implement.

 *

 * <h3>1.0 Overview</h3>

 * The <code>BaseRowSet</code> class provides the core functionality

 * for all <code>RowSet</code> implementations,

 * and all standard implementations <b>may</b> use this class in combination with

 * one or more <code>RowSet</code> interfaces in order to provide a standard

 * vendor-specific implementation.  To clarify, all implementations must implement

 * at least one of the <code>RowSet</code> interfaces (<code>JdbcRowSet</code>,

 * <code>CachedRowSet</code>, <code>JoinRowSet</code>, <code>FilteredRowSet</code>,

 * or <code>WebRowSet</code>). This means that any implementation that extends

 * the <code>BaseRowSet</code> class must also implement one of the <code>RowSet</code>

 * interfaces.

 * <p>

 * The <code>BaseRowSet</code> class provides the following:

 *

 * <UL>

 * <LI><b>Properties</b>

 *     <ul>

 *     <li>Fields for storing current properties

 *     <li>Methods for getting and setting properties

 *     </ul>

 *

 * <LI><b>Event notification</b>

 *

 * <LI><b>A complete set of setter methods</b> for setting the parameters in a

 *      <code>RowSet</code> object's command

 *

 * <LI> <b>Streams</b>

 *  <ul>

 *  <li>Fields for storing stream instances

 *  <li>Constants for indicating the type of a stream

 *  </ul>

 * </UL>

 *

 * <h3>2.0 Setting Properties</h3>

 * All rowsets maintain a set of properties, which will usually be set using

 * a tool.  The number and kinds of properties a rowset has will vary,

 * depending on what the <code>RowSet</code> implementation does and how it gets

 * its data.  For example,

 * rowsets that get their data from a <code>ResultSet</code> object need to

 * set the properties that are required for making a database connection.

 * If a <code>RowSet</code> object uses the <code>DriverManager</code> facility to make a

 * connection, it needs to set a property for the JDBC URL that identifies the

 * appropriate driver, and it needs to set the properties that give the

 * user name and password.

 * If, on the other hand, the rowset uses a <code>DataSource</code> object

 * to make the connection, which is the preferred method, it does not need to

 * set the property for the JDBC URL.  Instead, it needs to set the property

 * for the logical name of the data source along with the properties for

 * the user name and password.

 * <P>

 * NOTE:  In order to use a <code>DataSource</code> object for making a

 * connection, the <code>DataSource</code> object must have been registered

 * with a naming service that uses the Java Naming and Directory

 * Interface™ (JNDI) API.  This registration

 * is usually done by a person acting in the capacity of a system administrator.

 *

 * <h3>3.0 Setting the Command and Its Parameters</h3>

 * When a rowset gets its data from a relational database, it executes a command (a query)

 * that produces a <code>ResultSet</code> object.  This query is the command that is set

 * for the <code>RowSet</code> object's command property.  The rowset populates itself with data by reading the

 * data from the <code>ResultSet</code> object into itself. If the query

 * contains placeholders for values to be set, the <code>BaseRowSet</code> setter methods

 * are used to set these values. All setter methods allow these values to be set

 * to <code>null</code> if required.

 * <P>

 * The following code fragment illustrates how the

 * <code>CachedRowSet</code>&trade;

 * object <code>crs</code> might have its command property set.  Note that if a

 * tool is used to set properties, this is the code that the tool would use.

 * <PRE>{@code

 *    crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +

 *                   "WHERE CREDIT_LIMIT > ? AND REGION = ?");

 * }</PRE>

 * <P>

 * In this example, the values for <code>CREDIT_LIMIT</code> and

 * <code>REGION</code> are placeholder parameters, which are indicated with a

 * question mark (?).  The first question mark is placeholder parameter number

 * <code>1</code>, the second question mark is placeholder parameter number

 * <code>2</code>, and so on.  Any placeholder parameters must be set with

 * values before the query can be executed. To set these

 * placeholder parameters, the <code>BaseRowSet</code> class provides a set of setter

 * methods, similar to those provided by the <code>PreparedStatement</code>

 * interface, for setting values of each data type.  A <code>RowSet</code> object stores the

 * parameter values internally, and its <code>execute</code> method uses them internally

 * to set values for the placeholder parameters

 * before it sends the command to the DBMS to be executed.

 * <P>

 * The following code fragment demonstrates

 * setting the two parameters in the query from the previous example.

 * <PRE>{@code

 *    crs.setInt(1, 5000);

 *    crs.setString(2, "West");

 * }</PRE>

 * If the <code>execute</code> method is called at this point, the query

 * sent to the DBMS will be:

 * <PRE>{@code

 *    "SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +

 *                   "WHERE CREDIT_LIMIT > 5000 AND REGION = 'West'"

 * }</PRE>

 * NOTE: Setting <code>Array</code>, <code>Clob</code>, <code>Blob</code> and

 * <code>Ref</code> objects as a command parameter, stores these values as

 * <code>SerialArray</code>, <code>SerialClob</code>, <code>SerialBlob</code>

 * and <code>SerialRef</code> objects respectively.

 *

 * <h3>4.0 Handling of Parameters Behind the Scenes</h3>

 *

 * NOTE: The <code>BaseRowSet</code> class provides two kinds of setter methods,

 * those that set properties and those that set placeholder parameters. The setter

 * methods discussed in this section are those that set placeholder parameters.

 * <P>

 * The placeholder parameters set with the <code>BaseRowSet</code> setter methods

 * are stored as objects in an internal <code>Hashtable</code> object.

 * Primitives are stored as their <code>Object</code> type. For example, <code>byte</code>

 * is stored as <code>Byte</code> object, and <code>int</code> is stored as

 * an <code>Integer</code> object.

 * When the method <code>execute</code> is called, the values in the

 * <code>Hashtable</code> object are substituted for the appropriate placeholder

 * parameters in the command.

 * <P>

 * A call to the method <code>getParams</code> returns the values stored in the

 * <code>Hashtable</code> object as an array of <code>Object</code> instances.

 * An element in this array may be a simple <code>Object</code> instance or an

 * array (which is a type of <code>Object</code>). The particular setter method used

 * determines whether an element in this array is an <code>Object</code> or an array.

 * <P>

 * The majority of methods for setting placeholder parameters take two parameters,

 *  with the first parameter

 * indicating which placeholder parameter is to be set, and the second parameter

 * giving the value to be set.  Methods such as <code>setInt</code>,

 * <code>setString</code>, <code>setBoolean</code>, and <code>setLong</code> fall into

 * this category.  After these methods have been called, a call to the method

 * <code>getParams</code> will return an array with the values that have been set. Each

 * element in the array is an <code>Object</code> instance representing the

 * values that have been set. The order of these values in the array is determined by the

 * <code>int</code> (the first parameter) passed to the setter method. The values in the

 * array are the values (the second parameter) passed to the setter method.

 * In other words, the first element in the array is the value

 * to be set for the first placeholder parameter in the <code>RowSet</code> object's

 * command. The second element is the value to

 * be set for the second placeholder parameter, and so on.

 * <P>

 * Several setter methods send the driver and DBMS information beyond the value to be set.

 * When the method <code>getParams</code> is called after one of these setter methods has

 * been used, the elements in the array will themselves be arrays to accommodate the

 * additional information. In this category, the method <code>setNull</code> is a special case

 * because one version takes only

 * two parameters (<code>setNull(int parameterIndex, int SqlType)</code>). Nevertheless,

 * it requires

 * an array to contain the information that will be passed to the driver and DBMS.  The first

 * element in this array is the value to be set, which is <code>null</code>, and the

 * second element is the <code>int</code> supplied for <i>sqlType</i>, which

 * indicates the type of SQL value that is being set to <code>null</code>. This information

 * is needed by some DBMSs and is therefore required in order to ensure that applications

 * are portable.

 * The other version is intended to be used when the value to be set to <code>null</code>

 * is a user-defined type. It takes three parameters

 * (<code>setNull(int parameterIndex, int sqlType, String typeName)</code>) and also

 * requires an array to contain the information to be passed to the driver and DBMS.

 * The first two elements in this array are the same as for the first version of

 * <code>setNull</code>.  The third element, <i>typeName</i>, gives the SQL name of

 * the user-defined type. As is true with the other setter methods, the number of the

 * placeholder parameter to be set is indicated by an element's position in the array

 * returned by <code>getParams</code>.  So, for example, if the parameter

 * supplied to <code>setNull</code> is <code>2</code>, the second element in the array

 * returned by <code>getParams</code> will be an array of two or three elements.

 * <P>

 * Some methods, such as <code>setObject</code> and <code>setDate</code> have versions

 * that take more than two parameters, with the extra parameters giving information

 * to the driver or the DBMS. For example, the methods <code>setDate</code>,

 * <code>setTime</code>, and <code>setTimestamp</code> can take a <code>Calendar</code>

 * object as their third parameter.  If the DBMS does not store time zone information,

 * the driver uses the <code>Calendar</code> object to construct the <code>Date</code>,

 * <code>Time</code>, or <code>Timestamp</code> object being set. As is true with other

 * methods that provide additional information, the element in the array returned

 * by <code>getParams</code> is an array instead of a simple <code>Object</code> instance.

 * <P>

 * The methods <code>setAsciiStream</code>, <code>setBinaryStream</code>,

 * <code>setCharacterStream</code>, and <code>setUnicodeStream</code> (which is

 * deprecated, so applications should use <code>getCharacterStream</code> instead)

 * take three parameters, so for them, the element in the array returned by

 * <code>getParams</code> is also an array.  What is different about these setter

 * methods is that in addition to the information provided by parameters, the array contains

 * one of the <code>BaseRowSet</code> constants indicating the type of stream being set.

* <p>

* NOTE: The method <code>getParams</code> is called internally by

* <code>RowSet</code> implementations extending this class; it is not normally called by an

* application programmer directly.

*

* <h3>5.0 Event Notification</h3>

* The <code>BaseRowSet</code> class provides the event notification

* mechanism for rowsets.  It contains the field

* <code>listeners</code>, methods for adding and removing listeners, and

* methods for notifying listeners of changes.

* <P>

* A listener is an object that has implemented the <code>RowSetListener</code> interface.

* If it has been added to a <code>RowSet</code> object's list of listeners, it will be notified

*  when an event occurs on that <code>RowSet</code> object.  Each listener's

* implementation of the <code>RowSetListener</code> methods defines what that object

* will do when it is notified that an event has occurred.

* <P>

* There are three possible events for a <code>RowSet</code> object:

* <OL>

* <LI>the cursor moves

* <LI>an individual row is changed (updated, deleted, or inserted)

* <LI>the contents of the entire <code>RowSet</code> object  are changed

* </OL>

* <P>

* The <code>BaseRowSet</code> method used for the notification indicates the

* type of event that has occurred.  For example, the method

* <code>notifyRowChanged</code> indicates that a row has been updated,

* deleted, or inserted.  Each of the notification methods creates a

* <code>RowSetEvent</code> object, which is supplied to the listener in order to

* identify the <code>RowSet</code> object on which the event occurred.

* What the listener does with this information, which may be nothing, depends on how it was

* implemented.

*

* <h3>6.0 Default Behavior</h3>

* A default <code>BaseRowSet</code> object is initialized with many starting values.

*

* The following is true of a default <code>RowSet</code> instance that extends

* the <code>BaseRowSet</code> class:

* <UL>

*   <LI>Has a scrollable cursor and does not show changes

*       made by others.

*   <LI>Is updatable.

*   <LI>Does not show rows that have been deleted.

*   <LI>Has no time limit for how long a driver may take to

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

*   <LI>Has no limit for the number of rows it may contain.

*   <LI>Has no limit for the number of bytes a column may contain. NOTE: This

*   limit applies only to columns that hold values of the

*   following types:  <code>BINARY</code>, <code>VARBINARY</code>,

*   <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,

*   and <code>LONGVARCHAR</code>.

*   <LI>Will not see uncommitted data (make "dirty" reads).

*   <LI>Has escape processing turned on.

*   <LI>Has its connection's type map set to <code>null</code>.

*   <LI>Has an empty <code>Vector</code> object for storing the values set

*       for the placeholder parameters in the <code>RowSet</code> object's command.

* </UL>

* <p>

* If other values are desired, an application must set the property values

* explicitly. For example, the following line of code sets the maximum number

* of rows for the <code>CachedRowSet</code> object <i>crs</i> to 500.

* <PRE>

*    crs.setMaxRows(500);

* </PRE>

* Methods implemented in extensions of this <code>BaseRowSet</code> class <b>must</b> throw an

* <code>SQLException</code> object for any violation of the defined assertions.  Also, if the

* extending class overrides and reimplements any <code>BaseRowSet</code> method and encounters

* connectivity or underlying data source issues, that method <b>may</b> in addition throw an

* <code>SQLException</code> object for that reason.

*/

public abstract class BaseRowSet implements Serializable, Cloneable {

    /**

     * A constant indicating to a <code>RowSetReaderImpl</code> object

     * that a given parameter is a Unicode stream. This

     * <code>RowSetReaderImpl</code> object is provided as an extension of the

     * <code>SyncProvider</code> abstract class defined in the

     * <code>SyncFactory</code> static factory SPI mechanism.

     */

    public static final int UNICODE_STREAM_PARAM = 0;

    /**

     * A constant indicating to a <code>RowSetReaderImpl</code> object

     * that a given parameter is a binary stream. A

     * <code>RowSetReaderImpl</code> object is provided as an extension of the

     * <code>SyncProvider</code> abstract class defined in the

     * <code>SyncFactory</code> static factory SPI mechanism.

     */

    public static final int BINARY_STREAM_PARAM = 1;

    /**

     * A constant indicating to a <code>RowSetReaderImpl</code> object

     * that a given parameter is an ASCII stream. A

     * <code>RowSetReaderImpl</code> object is provided as an extension of the

     * <code>SyncProvider</code> abstract class defined in the

     * <code>SyncFactory</code> static factory SPI mechanism.

     */

    public static final int ASCII_STREAM_PARAM = 2;

    /**

     * The <code>InputStream</code> object that will be

     * returned by the method <code>getBinaryStream</code>, which is

     * specified in the <code>ResultSet</code> interface.

     * @serial

     */

    protected java.io.InputStream binaryStream;

    /**

     * The <code>InputStream</code> object that will be

     * returned by the method <code>getUnicodeStream</code>,

     * which is specified in the <code>ResultSet</code> interface.

     * @serial

     */

    protected java.io.InputStream unicodeStream;

    /**

     * The <code>InputStream</code> object that will be

     * returned by the method <code>getAsciiStream</code>,

     * which is specified in the <code>ResultSet</code> interface.

     * @serial

     */

    protected java.io.InputStream asciiStream;

    /**

     * The <code>Reader</code> object that will be

     * returned by the method <code>getCharacterStream</code>,

     * which is specified in the <code>ResultSet</code> interface.

     * @serial

     */

    protected java.io.Reader charStream;

    /**

     * The query that will be sent to the DBMS for execution when the

     * method <code>execute</code> is called.

     * @serial

     */

    private String command;

    /**

     * The JDBC URL the reader, writer, or both supply to the method

     * <code>DriverManager.getConnection</code> when the

     * <code>DriverManager</code> is used to get a connection.

     * <P>

     * The JDBC URL identifies the driver to be used to make the conndection.

     * This URL can be found in the documentation supplied by the driver

     * vendor.

     * @serial

     */

    private String URL;

    /**

     * The logical name of the data source that the reader/writer should use

     * in order to retrieve a <code>DataSource</code> object from a Java

     * Directory and Naming Interface (JNDI) naming service.

     * @serial

     */

    private String dataSource;

    /**

     * The user name the reader, writer, or both supply to the method

     * <code>DriverManager.getConnection</code> when the

     * <code>DriverManager</code> is used to get a connection.

     * @serial

     */

    private transient String username;

    /**

     * The password the reader, writer, or both supply to the method

     * <code>DriverManager.getConnection</code> when the

     * <code>DriverManager</code> is used to get a connection.

     * @serial

     */

    private transient String password;

    /**

     * A constant indicating the type of this JDBC <code>RowSet</code>

     * object. It must be one of the following <code>ResultSet</code>

     * constants:  <code>TYPE_FORWARD_ONLY</code>,

     * <code>TYPE_SCROLL_INSENSITIVE</code>, or

     * <code>TYPE_SCROLL_SENSITIVE</code>.

     * @serial

     */

    private int rowSetType = ResultSet.TYPE_SCROLL_INSENSITIVE;

    /**

     * A <code>boolean</code> indicating whether deleted rows are visible in this

     * JDBC <code>RowSet</code> object .

     * @serial

     */

    private boolean showDeleted = false; // default is false

    /**

     * The maximum number of seconds the driver

     * will wait for a command to execute.  This limit applies while

     * this JDBC <code>RowSet</code> object is connected to its data

     * source, that is, while it is populating itself with

     * data and while it is writing data back to the data source.

     * @serial

     */

    private int queryTimeout = 0; // default is no timeout

    /**

     * The maximum number of rows the reader should read.

     * @serial

     */

    private int maxRows = 0; // default is no limit

    /**

     * The maximum field size the reader should read.

     * @serial

     */

    private int maxFieldSize = 0; // default is no limit

    /**

     * A constant indicating the concurrency of this JDBC <code>RowSet</code>

     * object. It must be one of the following <code>ResultSet</code>

     * constants: <code>CONCUR_READ_ONLY</code> or

     * <code>CONCUR_UPDATABLE</code>.

     * @serial

     */

    private int concurrency = ResultSet.CONCUR_UPDATABLE;

    /**

     * A <code>boolean</code> indicating whether this JDBC <code>RowSet</code>

     * object is read-only.  <code>true</code> indicates that it is read-only;

     * <code>false</code> that it is writable.

     * @serial

     */

    private boolean readOnly;

    /**

     * A <code>boolean</code> indicating whether the reader for this

     * JDBC <code>RowSet</code> object should perform escape processing.

     * <code>true</code> means that escape processing is turned on;

     * <code>false</code> that it is not. The default is <code>true</code>.

     * @serial

     */

    private boolean escapeProcessing;

    /**

     * A constant indicating the isolation level of the connection

     * for this JDBC <code>RowSet</code> object . It must be one of

     * the following <code>Connection</code> constants:

     * <code>TRANSACTION_NONE</code>,

     * <code>TRANSACTION_READ_UNCOMMITTED</code>,

     * <code>TRANSACTION_READ_COMMITTED</code>,

     * <code>TRANSACTION_REPEATABLE_READ</code> or

     * <code>TRANSACTION_SERIALIZABLE</code>.

     * @serial

     */

    private int isolation;

    /**

     * A constant used as a hint to the driver that indicates the direction in

     * which data from this JDBC <code>RowSet</code> object  is going

     * to be fetched. The following <code>ResultSet</code> constants are

     * possible values:

     * <code>FETCH_FORWARD</code>,

     * <code>FETCH_REVERSE</code>,

     * <code>FETCH_UNKNOWN</code>.

     * <P>

     * Unused at this time.

     * @serial

     */

    private int fetchDir = ResultSet.FETCH_FORWARD; // default fetch direction

    /**

     * A hint to the driver that indicates the expected number of rows

     * in this JDBC <code>RowSet</code> object .

     * <P>

     * Unused at this time.

     * @serial

     */

    private int fetchSize = 0; // default fetchSize

    /**

     * The <code>java.util.Map</code> object that contains entries mapping

     * SQL type names to classes in the Java programming language for the

     * custom mapping of user-defined types.

     * @serial

     */

    private Map<String, Class<?>> map;

    /**

     * A <code>Vector</code> object that holds the list of listeners

     * that have registered with this <code>RowSet</code> object.

     * @serial

     */

    private Vector<RowSetListener> listeners;

    /**

     * A <code>Vector</code> object that holds the parameters set

     * for this <code>RowSet</code> object's current command.

     * @serial

     */

    private Hashtable<Integer, Object> params; // could be transient?