KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > sql > rowset > JdbcRowSet


1 /*
2  * @(#)JdbcRowSet.java 1.4 04/02/27
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.sql.rowset;
9
10 import java.sql.*;
11 import javax.sql.*;
12 import javax.naming.*;
13 import java.io.*;
14 import java.math.*;
15 import java.io.*;
16
17 /**
18  * The standard interface that all standard implementations of
19  * <code>JdbcRowSet</code> must implement.
20  *
21  * <h3>1.0 Overview</h3>
22  * A wrapper around a <code>ResultSet</code> object that makes it possible
23  * to use the result set as a JavaBeans<sup><font size=-2>TM</font></sup>
24  * component. Thus, a <code>JdbcRowSet</code> object can be one of the Beans that
25  * a tool makes available for composing an application. Because
26  * a <code>JdbcRowSet</code> is a connected rowset, that is, it continually
27  * maintains its connection to a database using a JDBC technology-enabled
28  * driver, it also effectively makes the driver a JavaBeans component.
29  * <P>
30  * Because it is always connected to its database, an instance of
31  * <code>JdbcRowSet</code>
32  * can simply take calls invoked on it and in turn call them on its
33  * <code>ResultSet</code> object. As a consequence, a result set can, for
34  * example, be a component in a Swing application.
35  * <P>
36  * Another advantage of a <code>JdbcRowSet</code> object is that it can be
37  * used to make a <code>ResultSet</code> object scrollable and updatable. All
38  * <code>RowSet</code> objects are by default scrollable and updatable. If
39  * the driver and database being used do not support scrolling and/or updating
40  * of result sets, an application can populate a <code>JdbcRowSet</code> object
41  * with the data of a <code>ResultSet</code> object and then operate on the
42  * <code>JdbcRowSet</code> object as if it were the <code>ResultSet</code>
43  * object.
44  * <P>
45  * <h3>2.0 Creating a <code>JdbcRowSet</code> Object</h3>
46  * The reference implementation of the <code>JdbcRowSet</code> interface,
47  * <code>JdbcRowSetImpl</code>, provides an implementation of
48  * the default constructor. A new instance is initialized with
49  * default values, which can be set with new values as needed. A
50  * new instance is not really functional until its <code>execute</code>
51  * method is called. In general, this method does the following:
52  * <UL>
53  * <LI> establishes a connection with a database
54  * <LI> creates a <code>PreparedStatement</code> object and sets any of its
55  * placeholder parameters
56  * <LI> executes the statement to create a <code>ResultSet</code> object
57  * </UL>
58  * If the <code>execute</code> method is successful, it will set the
59  * appropriate private <code>JdbcRowSet</code> fields with the following:
60  * <UL>
61  * <LI> a <code>Connection</code> object -- the connection between the rowset
62  * and the database
63  * <LI> a <code>PreparedStatement</code> object -- the query that produces
64  * the result set
65  * <LI> a <code>ResultSet</code> object -- the result set that the rowset's
66  * command produced and that is being made, in effect, a JavaBeans
67  * component
68  * </UL>
69  * If these fields have not been set, meaning that the <code>execute</code>
70  * method has not executed successfully, no methods other than
71  * <code>execute</code> and <code>close</code> may be called on the
72  * rowset. All other public methods will throw an exception.
73  * <P>
74  * Before calling the <code>execute</code> method, however, the command
75  * and properties needed for establishing a connection must be set.
76  * The following code fragment creates a <code>JdbcRowSetImpl</code> object,
77  * sets the command and connection properties, sets the placeholder parameter,
78  * and then invokes the method <code>execute</code>.
79  * <PRE>
80  * JdbcRowSetImpl jrs = new JdbcRowSetImpl();
81  * jrs.setCommand("SELECT * FROM TITLES WHERE TYPE = ?");
82  * jrs.setURL("jdbc:myDriver:myAttribute");
83  * jrs.setUsername("cervantes");
84  * jrs.setPassword("sancho");
85  * jrs.setString(1, "BIOGRAPHY");
86  * jrs.execute();
87  * </PRE>
88  * The variable <code>jrs</code> now represents an instance of
89  * <code>JdbcRowSetImpl</code> that is a thin wrapper around the
90  * <code>ResultSet</code> object containing all the rows in the
91  * table <code>TITLES</code> where the type of book is biography.
92  * At this point, operations called on <code>jrs</code> will
93  * affect the rows in the result set, which is effectively a JavaBeans
94  * component.
95  * <P>
96  * The implementation of the <code>RowSet</code> method <code>execute</code> in the
97  * <code>JdbcRowSet</code> reference implementation differs from that in the
98  * <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>
99  * reference implementation to account for the different
100  * requirements of connected and disconnected <code>RowSet</code> objects.
101  * <p>
102  *
103  * @author Jonathan Bruce
104  */
105
106 public interface JdbcRowSet extends RowSet, Joinable JavaDoc {
107
108     /**
109      * Retrieves a <code>boolean</code> indicating whether rows marked
110      * for deletion appear in the set of current rows. If <code>true</code> is
111      * returned, deleted rows are visible with the current rows. If
112      * <code>false</code> is returned, rows are not visible with the set of
113      * current rows. The default value is <code>false</code>.
114      * <P>
115      * Standard rowset implementations may choose to restrict this behavior
116      * for security considerations or for certain deployment
117      * scenarios. The visibility of deleted rows is implementation-defined
118      * and does not represent standard behavior.
119      * <P>
120      * Note: Allowing deleted rows to remain visible complicates the behavior
121      * of some standard JDBC <code>RowSet</code> implementations methods.
122      * However, most rowset users can simply ignore this extra detail because
123      * only very specialized applications will likely want to take advantage of
124      * this feature.
125      *
126      * @return <code>true</code> if deleted rows are visible;
127      * <code>false</code> otherwise
128      * @exception SQLException if a rowset implementation is unable to
129      * to determine whether rows marked for deletion remain visible
130      * @see #setShowDeleted
131      */
132     public boolean getShowDeleted() throws SQLException;
133
134     /**
135      * Sets the property <code>showDeleted</code> to the given
136      * <code>boolean</code> value. This property determines whether
137      * rows marked for deletion continue to appear in the set of current rows.
138      * If the value is set to <code>true</code>, deleted rows are immediately
139      * visible with the set of current rows. If the value is set to
140      * <code>false</code>, the deleted rows are set as invisible with the
141      * current set of rows.
142      * <P>
143      * Standard rowset implementations may choose to restrict this behavior
144      * for security considerations or for certain deployment
145      * scenarios. This is left as implementation-defined and does not
146      * represent standard behavior.
147      *
148      * @param b <code>true</code> if deleted rows should be shown;
149      * <code>false</code> otherwise
150      * @exception SQLException if a rowset implementation is unable to
151      * to reset whether deleted rows should be visible
152      * @see #getShowDeleted
153      */
154     public void setShowDeleted(boolean b) throws SQLException;
155     
156     /**
157      * Retrieves the first warning reported by calls on this <code>JdbcRowSet</code>
158      * object.
159      * If a second warning was reported on this <code>JdbcRowSet</code> object,
160      * it will be chained to the first warning and can be retrieved by
161      * calling the method <code>RowSetWarning.getNextWarning</code> on the
162      * first warning. Subsequent warnings on this <code>JdbcRowSet</code>
163      * object will be chained to the <code>RowSetWarning</code> objects
164      * returned by the method <code>RowSetWarning.getNextWarning</code>.
165      *
166      * The warning chain is automatically cleared each time a new row is read.
167      * This method may not be called on a <code>RowSet</code> object
168      * that has been closed;
169      * doing so will cause an <code>SQLException</code> to be thrown.
170      * <P>
171      * Because it is always connected to its data source, a <code>JdbcRowSet</code>
172      * object can rely on the presence of active
173      * <code>Statement</code>, <code>Connection</code>, and <code>ResultSet</code>
174      * instances. This means that applications can obtain additional
175      * <code>SQLWarning</code>
176      * notifications by calling the <code>getNextWarning</code> methods that
177      * they provide.
178      * Disconnected <code>Rowset</code> objects, such as a
179      * <code>CachedRowSet</code> object, do not have access to
180      * these <code>getNextWarning</code> methods.
181      *
182      * @return the first <code>RowSetWarning</code>
183      * object reported on this <code>JdbcRowSet</code> object
184      * or <code>null</code> if there are none
185      * @throws SQLException if this method is called on a closed
186      * <code>JdbcRowSet</code> object
187      * @see RowSetWarning
188      */
189     public RowSetWarning JavaDoc getRowSetWarnings() throws SQLException;
190     
191    /**
192     * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
193     * the <code>ResultSet</code> or JDBC properties passed to it's constructors.
194     * This method wraps the <code>Connection</code> commit method to allow flexible
195     * auto commit or non auto commit transactional control support.
196     * <p>
197     * Makes all changes made since the previous commit/rollback permanent
198     * and releases any database locks currently held by this Connection
199     * object. This method should be used only when auto-commit mode has
200     * been disabled.
201     *
202     * @throws SQLException if a database access error occurs or this
203     * Connection object within this <code>JdbcRowSet</code> is in auto-commit mode
204     * @see java.sql.Connection#setAutoCommit
205     */
206     public void commit() throws SQLException;
207
208
209    /**
210     * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
211     * the original <code>ResultSet</code> or JDBC properties passed to it. This
212     * method wraps the <code>Connection</code>'s <code>getAutoCommit</code> method
213     * to allow an application to determine the <code>JdbcRowSet</code> transaction
214     * behavior.
215     * <p>
216     * Sets this connection's auto-commit mode to the given state. If a
217     * connection is in auto-commit mode, then all its SQL statements will
218     * be executed and committed as individual transactions. Otherwise, its
219     * SQL statements are grouped into transactions that are terminated by a
220     * call to either the method commit or the method rollback. By default,
221     * new connections are in auto-commit mode.
222     *
223     * @throws SQLException if a database access error occurs
224     * @see java.sql.Connection#getAutoCommit()
225     */
226     public boolean getAutoCommit() throws SQLException;
227
228
229    /**
230     * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
231     * the original <code>ResultSet</code> or JDBC properties passed to it. This
232     * method wraps the <code>Connection</code>'s <code>getAutoCommit</code> method
233     * to allow an application to set the <code>JdbcRowSet</code> transaction behavior.
234     * <p>
235     * Sets the current auto-commit mode for this <code>Connection</code> object.
236     *
237     * @return the current state of this internal <code>Connection</code> object's
238     * auto-commit mode
239     * @throws SQLException if a database access error occurs
240     * @see java.sql.Connection#setAutoCommit(boolean)
241     */
242     public void setAutoCommit(boolean autoCommit) throws SQLException;
243     
244     /**
245      * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
246      * the original <code>ResultSet</code> or JDBC properties passed to it.
247      * Undoes all changes made in the current transaction and releases any
248      * database locks currently held by this <code>Connection</code> object. This method
249      * should be used only when auto-commit mode has been disabled.
250      *
251      * @throws SQLException if a database access error occurs or this <code>Connection</code>
252      * object within this <code>JdbcRowSet</code> is in auto-commit mode.
253      * @see #rollback(Savepoint)
254      */
255      public void rollback() throws SQLException;
256      
257      
258     /**
259      * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
260      * the original <code>ResultSet</code> or JDBC properties passed to it.
261      * Undoes all changes made in the current transaction to the last set savepoint
262      * and releases any database locks currently held by this <code>Connection</code>
263      * object. This method should be used only when auto-commit mode has been disabled.
264      *
265      * @throws SQLException if a database access error occurs or this <code>Connection</code>
266      * object within this <code>JdbcRowSet</code> is in auto-commit mode.
267      * @see #rollback
268      */
269     public void rollback(Savepoint s) throws SQLException;
270      
271 }
272
273
Popular Tags