20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.sql.rowset;
27
28 import java.sql.*;
29 import javax.sql.*;
30 import java.util.*;
31 import java.io.*;
32 import java.math.*;
33 import java.io.Serializable;
34
35 import javax.sql.rowset.serial.*;
36
37 /**
38 * An abstract class providing a <code>RowSet</code> object with its basic functionality.
39 * The basic functions include having properties and sending event notifications,
40 * which all JavaBeans™ components must implement.
41 *
42 * <h2>1.0 Overview</h2>
43 * The <code>BaseRowSet</code> class provides the core functionality
44 * for all <code>RowSet</code> implementations,
45 * and all standard implementations <b>may</b> use this class in combination with
46 * one or more <code>RowSet</code> interfaces in order to provide a standard
47 * vendor-specific implementation. To clarify, all implementations must implement
48 * at least one of the <code>RowSet</code> interfaces (<code>JdbcRowSet</code>,
49 * <code>CachedRowSet</code>, <code>JoinRowSet</code>, <code>FilteredRowSet</code>,
50 * or <code>WebRowSet</code>). This means that any implementation that extends
51 * the <code>BaseRowSet</code> class must also implement one of the <code>RowSet</code>
52 * interfaces.
53 * <p>
54 * The <code>BaseRowSet</code> class provides the following:
55 *
56 * <UL>
57 * <LI><b>Properties</b>
58 * <ul>
59 * <li>Fields for storing current properties
60 * <li>Methods for getting and setting properties
75 * <h2>2.0 Setting Properties</h2>
76 * All rowsets maintain a set of properties, which will usually be set using
77 * a tool. The number and kinds of properties a rowset has will vary,
78 * depending on what the <code>RowSet</code> implementation does and how it gets
79 * its data. For example,
80 * rowsets that get their data from a <code>ResultSet</code> object need to
81 * set the properties that are required for making a database connection.
82 * If a <code>RowSet</code> object uses the <code>DriverManager</code> facility to make a
83 * connection, it needs to set a property for the JDBC URL that identifies the
84 * appropriate driver, and it needs to set the properties that give the
85 * user name and password.
86 * If, on the other hand, the rowset uses a <code>DataSource</code> object
87 * to make the connection, which is the preferred method, it does not need to
88 * set the property for the JDBC URL. Instead, it needs to set the property
89 * for the logical name of the data source along with the properties for
90 * the user name and password.
91 * <P>
92 * NOTE: In order to use a <code>DataSource</code> object for making a
93 * connection, the <code>DataSource</code> object must have been registered
94 * with a naming service that uses the Java Naming and Directory
95 * Interface™ (JNDI) API. This registration
96 * is usually done by a person acting in the capacity of a system administrator.
97 *
98 * <h2>3.0 Setting the Command and Its Parameters</h2>
99 * When a rowset gets its data from a relational database, it executes a command (a query)
100 * that produces a <code>ResultSet</code> object. This query is the command that is set
101 * for the <code>RowSet</code> object's command property. The rowset populates itself with data by reading the
102 * data from the <code>ResultSet</code> object into itself. If the query
103 * contains placeholders for values to be set, the <code>BaseRowSet</code> setter methods
104 * are used to set these values. All setter methods allow these values to be set
105 * to <code>null</code> if required.
106 * <P>
107 * The following code fragment illustrates how the
108 * <code>CachedRowSet</code>™
109 * object <code>crs</code> might have its command property set. Note that if a
110 * tool is used to set properties, this is the code that the tool would use.
111 * <PRE>{@code
112 * crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
113 * "WHERE CREDIT_LIMIT > ? AND REGION = ?");
114 * }</PRE>
115 * <P>
116 * In this example, the values for <code>CREDIT_LIMIT</code> and
117 * <code>REGION</code> are placeholder parameters, which are indicated with a
118 * question mark (?). The first question mark is placeholder parameter number
119 * <code>1</code>, the second question mark is placeholder parameter number
120 * <code>2</code>, and so on. Any placeholder parameters must be set with
121 * values before the query can be executed. To set these
122 * placeholder parameters, the <code>BaseRowSet</code> class provides a set of setter
123 * methods, similar to those provided by the <code>PreparedStatement</code>
124 * interface, for setting values of each data type. A <code>RowSet</code> object stores the
125 * parameter values internally, and its <code>execute</code> method uses them internally
126 * to set values for the placeholder parameters
127 * before it sends the command to the DBMS to be executed.
128 * <P>
|
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.sql.rowset;
27
28 import java.sql.*;
29 import javax.sql.*;
30 import java.util.*;
31 import java.io.*;
32 import java.math.*;
33 import java.io.Serializable;
34
35 import javax.sql.rowset.serial.*;
36
37 /**
38 * An abstract class providing a <code>RowSet</code> object with its basic functionality.
39 * The basic functions include having properties and sending event notifications,
40 * which all JavaBeans components must implement.
41 *
42 * <h2>1.0 Overview</h2>
43 * The <code>BaseRowSet</code> class provides the core functionality
44 * for all <code>RowSet</code> implementations,
45 * and all standard implementations <b>may</b> use this class in combination with
46 * one or more <code>RowSet</code> interfaces in order to provide a standard
47 * vendor-specific implementation. To clarify, all implementations must implement
48 * at least one of the <code>RowSet</code> interfaces (<code>JdbcRowSet</code>,
49 * <code>CachedRowSet</code>, <code>JoinRowSet</code>, <code>FilteredRowSet</code>,
50 * or <code>WebRowSet</code>). This means that any implementation that extends
51 * the <code>BaseRowSet</code> class must also implement one of the <code>RowSet</code>
52 * interfaces.
53 * <p>
54 * The <code>BaseRowSet</code> class provides the following:
55 *
56 * <UL>
57 * <LI><b>Properties</b>
58 * <ul>
59 * <li>Fields for storing current properties
60 * <li>Methods for getting and setting properties
75 * <h2>2.0 Setting Properties</h2>
76 * All rowsets maintain a set of properties, which will usually be set using
77 * a tool. The number and kinds of properties a rowset has will vary,
78 * depending on what the <code>RowSet</code> implementation does and how it gets
79 * its data. For example,
80 * rowsets that get their data from a <code>ResultSet</code> object need to
81 * set the properties that are required for making a database connection.
82 * If a <code>RowSet</code> object uses the <code>DriverManager</code> facility to make a
83 * connection, it needs to set a property for the JDBC URL that identifies the
84 * appropriate driver, and it needs to set the properties that give the
85 * user name and password.
86 * If, on the other hand, the rowset uses a <code>DataSource</code> object
87 * to make the connection, which is the preferred method, it does not need to
88 * set the property for the JDBC URL. Instead, it needs to set the property
89 * for the logical name of the data source along with the properties for
90 * the user name and password.
91 * <P>
92 * NOTE: In order to use a <code>DataSource</code> object for making a
93 * connection, the <code>DataSource</code> object must have been registered
94 * with a naming service that uses the Java Naming and Directory
95 * Interface (JNDI) API. This registration
96 * is usually done by a person acting in the capacity of a system administrator.
97 *
98 * <h2>3.0 Setting the Command and Its Parameters</h2>
99 * When a rowset gets its data from a relational database, it executes a command (a query)
100 * that produces a <code>ResultSet</code> object. This query is the command that is set
101 * for the <code>RowSet</code> object's command property. The rowset populates itself with data by reading the
102 * data from the <code>ResultSet</code> object into itself. If the query
103 * contains placeholders for values to be set, the <code>BaseRowSet</code> setter methods
104 * are used to set these values. All setter methods allow these values to be set
105 * to <code>null</code> if required.
106 * <P>
107 * The following code fragment illustrates how the
108 * <code>CachedRowSet</code>
109 * object <code>crs</code> might have its command property set. Note that if a
110 * tool is used to set properties, this is the code that the tool would use.
111 * <PRE>{@code
112 * crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
113 * "WHERE CREDIT_LIMIT > ? AND REGION = ?");
114 * }</PRE>
115 * <P>
116 * In this example, the values for <code>CREDIT_LIMIT</code> and
117 * <code>REGION</code> are placeholder parameters, which are indicated with a
118 * question mark (?). The first question mark is placeholder parameter number
119 * <code>1</code>, the second question mark is placeholder parameter number
120 * <code>2</code>, and so on. Any placeholder parameters must be set with
121 * values before the query can be executed. To set these
122 * placeholder parameters, the <code>BaseRowSet</code> class provides a set of setter
123 * methods, similar to those provided by the <code>PreparedStatement</code>
124 * interface, for setting values of each data type. A <code>RowSet</code> object stores the
125 * parameter values internally, and its <code>execute</code> method uses them internally
126 * to set values for the placeholder parameters
127 * before it sends the command to the DBMS to be executed.
128 * <P>
|