/* * Copyright (c) 2003, 2010, Oracle and/or its affiliates. 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. 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<sup><font size=-2>TM</font></sup> components must implement. * <P> * <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: * <p> * <UL> * <LI><b>Properties</b> * <ul> * <li>Fields for storing current properties * <li>Methods for getting and setting properties * </ul> * <p> * <LI><b>Event notification</b> * <P> * <LI><b>A complete set of setter methods</b> for setting the parameters in a * <code>RowSet</code> object's command * <p> * <LI> <b>Streams</b> * <ul> * <li>Fields for storing stream instances * <li>Constants for indicating the type of a stream * </ul> * <p> * </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<sup><font size=-2>TM</font></sup> (JNDI) API. This registration * is usually done by a person acting in the capacity of a system administrator. * <P> * <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><sup><font size=-2>TM</font></sup> * 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> * 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> * 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> * "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 drivern 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.* <p>* <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 fetchSizeLines 1–500 of 4512. Load more
/* * Copyright (c) 2003, 2010, Oracle and/or its affiliates. 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. 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<sup><font size=-2>TM</font></sup> components must implement. * <P> * <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: * <p> * <UL> * <LI><b>Properties</b> * <ul> * <li>Fields for storing current properties * <li>Methods for getting and setting properties * </ul> * <p> * <LI><b>Event notification</b> * <P> * <LI><b>A complete set of setter methods</b> for setting the parameters in a * <code>RowSet</code> object's command * <p> * <LI> <b>Streams</b> * <ul> * <li>Fields for storing stream instances * <li>Constants for indicating the type of a stream * </ul> * <p> * </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<sup><font size=-2>TM</font></sup> (JNDI) API. This registration * is usually done by a person acting in the capacity of a system administrator. * <P> * <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><sup><font size=-2>TM</font></sup> * 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> * 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> * 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> * "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 drivern 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. * <p> * <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