001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041: package com.sun.sql.rowset;
042:
043: import javax.sql.rowset.*;
044:
045: import java.sql.*;
046: import javax.sql.*;
047: import java.util.*;
048: import java.io.*;
049: import java.io.Serializable;
050:
051: /**
052: * An abstract class extending <code>javax.sql.rowset.BaseRowSet</code> which contains
053: * changes necessary to support using RowSets as java beans.
054: */
055:
056: public abstract class BaseRowSetX extends BaseRowSet {
057:
058: private static ResourceBundle rb = ResourceBundle.getBundle(
059: "com.sun.sql.rowset.Bundle", Locale.getDefault());
060:
061: /**
062: * The maximum number of rows the reader should read.
063: * @serial
064: */
065: private int maxRows = 0; // default is no limit
066:
067: /**
068: * Supplants the fetchDir in the superclass
069: * A constant used as a hint to the driver that indicates the direction in
070: * which data from this JDBC <code>RowSet</code> object is going
071: * to be fetched. The following <code>ResultSet</code> constants are
072: * possible values:
073: * <code>FETCH_FORWARD</code>,
074: * <code>FETCH_REVERSE</code>,
075: * <code>FETCH_UNKNOWN</code>.
076: * <P>
077: * Unused at this time.
078: * @serial
079: */
080: private int fetchDir = ResultSet.FETCH_FORWARD; // default fetch direction
081:
082: /**
083: * A hint to the driver that indicates the expected number of rows
084: * in this JDBC <code>RowSet</code> object .
085: * <P>
086: * Unused at this time.
087: * @serial
088: */
089: private int fetchSize = 0; // default fetchSize
090:
091: /**
092: * Sets this <code>RowSet</code> object's <code>command</code> property to
093: * the given <code>String</code> object and clears the parameters, if any,
094: * that were set for the previous command.
095: * <P>
096: * The <code>command</code> property may not be needed if the <code>RowSet</code>
097: * object gets its data from a source that does not support commands,
098: * such as a spreadsheet or other tabular file.
099: * Thus, this property is optional and may be <code>null</code>.
100: *
101: * @param cmd a <code>String</code> object containing an SQL query
102: * that will be set as this <code>RowSet</code> object's command
103: * property; may be <code>null</code> but may not be an empty string
104: * @throws SQLException if an empty string is provided as the command value
105: * @see #getCommand
106: */
107: public void setCommand(String cmd) throws SQLException {
108: super .setCommand((cmd == null || cmd.length() == 0) ? null
109: : cmd);
110: }
111:
112: /**
113: * Sets the Url property for this <code>RowSet</code> object
114: * to the given <code>String</code> object and sets the dataSource name
115: * property to <code>null</code>. The Url property is a
116: * JDBC URL that is used when
117: * the connection is created using a JDBC technology-enabled driver
118: * ("JDBC driver") and the <code>DriverManager</code>.
119: * The correct JDBC URL for the specific driver to be used can be found
120: * in the driver documentation. Although there are guidelines for for how
121: * a JDBC URL is formed,
122: * a driver vendor can specify any <code>String</code> object except
123: * one with a length of <code>0</code> (an empty string).
124: * <P>
125: * Setting the Url property is optional if connections are established using
126: * a <code>DataSource</code> object instead of the <code>DriverManager</code>.
127: * The driver will use either the URL property or the
128: * dataSourceName property to create a connection, whichever was
129: * specified most recently. If an application uses a JDBC URL, it
130: * must load a JDBC driver that accepts the JDBC URL before it uses the
131: * <code>RowSet</code> object to connect to a database. The <code>RowSet</code>
132: * object will use the URL internally to create a database connection in order
133: * to read or write data.
134: *
135: * @param url a <code>String</code> object that contains the JDBC URL
136: * that will be used to establish the connection to a database for this
137: * <code>RowSet</code> object; may be <code>null</code> but must not
138: * be an empty string
139: * @throws SQLException if an error occurs setting the Url property or the
140: * parameter supplied is a string with a length of <code>0</code> (an
141: * empty string)
142: * @see #getUrl
143: */
144: public void setUrl(String url) throws SQLException {
145: super .setUrl((url == null || url.length() == 0) ? null : url);
146: }
147:
148: /**
149: * Sets the <code>DataSource</code> name property for this <code>RowSet</code>
150: * object to the given logical name and sets this <code>RowSet</code> object's
151: * Url property to <code>null</code>. The name must have been bound to a
152: * <code>DataSource</code> object in a JNDI naming service so that an
153: * application can do a lookup using that name to retrieve the
154: * <code>DataSource</code> object bound to it. The <code>DataSource</code>
155: * object can then be used to establish a connection to the data source it
156: * represents.
157: * <P>
158: * Users should set either the Url property or the dataSourceName property.
159: * If both properties are set, the driver will use the property set most recently.
160: *
161: * @param name a <code>String</code> object with the name that can be supplied
162: * to a naming service based on JNDI technology to retrieve the
163: * <code>DataSource</code> object that can be used to get a connection;
164: * may be <code>null</code> but must not be an empty string
165: * @throws SQLException if there is a problem setting the
166: * <code>dataSourceName</code> property or <i>name</i> is an empty string
167: * @see #getDataSourceName
168: */
169: public void setDataSourceName(String name) throws SQLException {
170: super
171: .setDataSourceName((name == null || name.length() == 0) ? null
172: : name);
173: }
174:
175: /**
176: * Sets the maximum number of rows that this <code>RowSet</code> object may contain to
177: * the given number. If this limit is exceeded, the excess rows are
178: * silently dropped.
179: *
180: * @param max an <code>int</code> indicating the current maximum number
181: * of rows; zero means that there is no limit
182: * @throws SQLException if an error occurs internally setting the
183: * maximum limit on the number of rows that a JDBC <code>RowSet</code> object
184: * can contain; or if <i>max</i> is less than <code>0</code>; or
185: * if <i>max</i> is less than the <code>fetchSize</code> of the
186: * <code>RowSet</code>
187: */
188: public void setMaxRows(int max) throws SQLException {
189: if (max < 0) {
190: throw new SQLException(rb.getString("MAX_ROWS_INVALID")
191: + " " + max);
192: }
193: this .maxRows = max;
194: }
195:
196: /**
197: * Retrieves the maximum number of rows that this <code>RowSet</code> object may contain. If
198: * this limit is exceeded, the excess rows are silently dropped.
199: *
200: * @return an <code>int</code> indicating the current maximum number of
201: * rows; zero means that there is no limit
202: * @throws SQLException if an error occurs internally determining the
203: * maximum limit of rows that a <code>Rowset</code> object can contain
204: */
205: public int getMaxRows() throws SQLException {
206: return maxRows;
207: }
208:
209: /**
210: * Gives the driver a performance hint as to the direction in
211: * which the rows in this <code>RowSet</code> object will be
212: * processed. The driver may ignore this hint.
213: * <P>
214: * A <code>RowSet</code> object inherits the default properties of the
215: * <code>ResultSet</code> object from which it got its data. That
216: * <code>ResultSet</code> object's default fetch direction is set by
217: * the <code>Statement</code> object that created it.
218: * <P>
219: * This method applies to a <code>RowSet</code> object only while it is
220: * connected to a database using a JDBC driver.
221: * <p>
222: * A <code>RowSet</code> object may use this method at any time to change
223: * its setting for the fetch direction.
224: *
225: * @param direction one of <code>ResultSet.FETCH_FORWARD</code>,
226: * <code>ResultSet.FETCH_REVERSE</code>, or
227: * <code>ResultSet.FETCH_UNKNOWN</code>
228: * @throws SQLException if (1) the <code>RowSet</code> type is
229: * <code>TYPE_FORWARD_ONLY</code> and the given fetch direction is not
230: * <code>FETCH_FORWARD</code> or (2) the given fetch direction is not
231: * one of the following:
232: * ResultSet.FETCH_FORWARD,
233: * ResultSet.FETCH_REVERSE, or
234: * ResultSet.FETCH_UNKNOWN
235: * @see #getFetchDirection
236: */
237: public void setFetchDirection(int direction) throws SQLException {
238: // Changed the condition checking to the below as there were two
239: // conditions that had to be checked
240: // 1. RowSet is TYPE_FORWARD_ONLY and direction is not FETCH_FORWARD
241: // 2. Direction is not one of the valid values
242:
243: /* !JK This violates the java beans rules that properties can be set in any order
244: if (((getType() == ResultSet.TYPE_FORWARD_ONLY) && (direction != ResultSet.FETCH_FORWARD)) ||
245: */
246: if (((direction != ResultSet.FETCH_FORWARD)
247: && (direction != ResultSet.FETCH_REVERSE) && (direction != ResultSet.FETCH_UNKNOWN))) {
248: throw new SQLException(rb
249: .getString("INVALID_FETCH_DIRECTION"));
250: }
251: fetchDir = direction;
252: }
253:
254: /**
255: * Retrieves this <code>RowSet</code> object's current setting for the
256: * fetch direction. The default type is <code>ResultSet.FETCH_FORWARD</code>
257: *
258: * @return one of <code>ResultSet.FETCH_FORWARD</code>,
259: * <code>ResultSet.FETCH_REVERSE</code>, or
260: * <code>ResultSet.FETCH_UNKNOWN</code>
261: * @throws SQLException if an error occurs in determining the
262: * current fetch direction for fetching rows
263: * @see #setFetchDirection
264: */
265: public int getFetchDirection() throws SQLException {
266: return (fetchDir);
267: }
268:
269: /**
270: * Sets the fetch size for this <code>RowSet</code> object to the given number of
271: * rows. The fetch size gives a JDBC technology-enabled driver ("JDBC driver")
272: * a hint as to the
273: * number of rows that should be fetched from the database when more rows
274: * are needed for this <code>RowSet</code> object. If the fetch size specified
275: * is zero, the driver ignores the value and is free to make its own best guess
276: * as to what the fetch size should be.
277: * <P>
278: * A <code>RowSet</code> object inherits the default properties of the
279: * <code>ResultSet</code> object from which it got its data. That
280: * <code>ResultSet</code> object's default fetch size is set by
281: * the <code>Statement</code> object that created it.
282: * <P>
283: * This method applies to a <code>RowSet</code> object only while it is
284: * connected to a database using a JDBC driver.
285: * For connected <code>RowSet</code> implementations such as
286: * <code>JdbcRowSet</code>, this method has a direct and immediate effect
287: * on the underlying JDBC driver.
288: * <P>
289: * A <code>RowSet</code> object may use this method at any time to change
290: * its setting for the fetch size.
291: * <p>
292: * For <code>RowSet</code> implementations such as
293: * <code>CachedRowSet</code>, which operate in a disconnected environment,
294: * the <code>SyncProvider</code> object being used
295: * may leverage the fetch size to poll the data source and
296: * retrieve a number of rows that do not exceed the fetch size and that may
297: * form a subset of the actual rows returned by the original query. This is
298: * an implementation variance determined by the specific <code>SyncProvider</code>
299: * object employed by the disconnected <code>RowSet</code> object.
300: * <P>
301: *
302: * @param rows the number of rows to fetch; <code>0</code> to let the
303: * driver decide what the best fetch size is; must not be less
304: * than <code>0</code> or more than the maximum number of rows
305: * allowed for this <code>RowSet</code> object (the number returned
306: * by a call to the method {@link #getMaxRows})
307: * @throws SQLException if the specified fetch size is less than <code>0</code>
308: * or more than the limit for the maximum number of rows
309: * @see #getFetchSize
310: */
311: public void setFetchSize(int rows) throws SQLException {
312: //Added this checking as maxRows can be 0 when this function is called
313: //maxRows = 0 means rowset can hold any number of rows, os this checking
314: // is needed to take care of this condition.
315: if (rows < 0) {
316: throw new SQLException(rb.getString("INVALID_FETCH_SIZE")
317: + " " + rows);
318: }
319: fetchSize = rows;
320: }
321:
322: /**
323: * Returns the fetch size for this <code>RowSet</code> object. The default
324: * value is zero.
325: *
326: * @return the number of rows suggested as the fetch size when this <code>RowSet</code> object
327: * needs more rows from the database
328: * @throws SQLException if an error occurs determining the number of rows in the
329: * current fetch size
330: * @see #setFetchSize
331: */
332: public int getFetchSize() throws SQLException {
333: return fetchSize;
334: }
335: }
|