java.lang.Object com.ibm.db.beans.DBStatement com.ibm.db.beans.DBSelect
public class DBSelect
implements Serializable
extends DBStatement
This class allows you to execute a query and use its result set in a bean which exposes JDBC 2.0 RowSet functionality and adds its own useful functions for managing a RowSet.
The JDBC RowSet "wraps" a connection, a statement, and a result set as a bean, and provides properties, methods, and events for using them. This includes the ability to update, delete, and insert rows in the result set without writing additional statements.
Some of the functions this class adds to the JDBC RowSet help with managing a large result set. Others make it easy to use the bean in a graphical user interface -- for example the ability to fire PropertyChange events for dynamically generated bound "properties" corresponding to the columns of the result set. You can also connect this bean to the utility bean DBTableModel, which adapts it for use as the model of a javax.swing.JTable.
Field | Description |
---|---|
DEFER_NOTHING | |
DEFER_WRITE_TO_DATABASE | |
DEFER_WRITE_TO_DATABASE_AND_ROW_NUMBER_CHANGE | |
FETCH_FORWARD | |
FETCH_REVERSE |
Constructor | Description |
---|---|
DBSelect() | Default constructor for a DBSelect bean. |
Method | Description |
---|---|
void addDBAfterListener(DBAfterListener) | Adds a listener to the DBAfter event set. |
void addDBBeforeListener(DBBeforeListener) | Adds a listener to the DBBefore event set. |
void addPropertyChangeListener(PropertyChangeListener) | Adds a listener to the PropertyChange event set. |
void applyUpdates() | Apply all updateRow, deleteRow, and newRow actions that have been deferred. |
boolean areDistinctTypesEnabled() | Returns true if use of user-defined distinct types is enabled for this RowSet. |
void cancelRowUpdates() | Cancels any value changes made in a row. |
void cancelUpdates() | Cancel all updateRow, deleteRow, and newRow actions that have been deferred and not yet applied. |
void close() | Releases the database and JDBC resources of the underlying
RowSet object immediately instead of waiting for
this to happen when it is automatically closed. |
void close(int) | Applies any changes in the current row of the underlying RowSet to the database, and then releases the database and JDBC resources of the RowSet immediately instead of waiting for this to happen when it is automatically closed. |
void deleteRow() | Deletes the current row from the result set and the underlying database. |
void execute() | Executes the query, connecting to the database if not already connected, and fills the rowset with data, positioning to the first row. |
void execute(int) | Executes the query, connecting to the database if not already connected, and fills the rowset with data, positioning to the specified row. |
boolean fetchMoreRows() | Fetches more rows from the database into the row cache. |
boolean fetchMoreRows(int) | Fetches more rows from the database into the row cache. |
int findColumn(String) | Maps the given column label to its column index. |
boolean first() | Applies any changes in the current row to the database, and then moves to the first row in the result set. |
int getCacheLimit() | Gets the maximum number of rows to be kept in an in-memory cache of result set rows. |
int getCacheRowCount() | Returns the number of rows in the cache. |
Object getCacheValueAt(int, int) | Returns the value at rowIndex and columnIndex in the cache. |
Object getColumn(int) | Returns the value of the column at the specified index in the current row. |
Object getColumn(String) | Returns the value of the column with the specified name in the current row. |
String getColumnAsString(int) | Returns the value of the column at the specified index in the current row as a String. |
String getColumnAsString(String) | Returns the value of the column with the specified name in the current row as a String. |
int getColumnCount() | Returns the number of columns in the RowSet. |
String getColumnName(int) | Returns the name of the column at columnIndex. |
int getFetchSize() | Gets the number of rows that should be fetched from the database when more rows are needed. |
int getMaxFieldSize() | The maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value. |
int getMaxRows() | The maxRows limit is the maximum number of rows that a RowSet can contain. |
DBSelectMetaData getMetaData() | Retrieves the DBSelectMetaData object describing the result set. |
int getRow() | Retrieves the current row number. |
int getRowCount() | Returns the number of rows currently in the result set. |
int getRowInCache() | Returns the index in the cache of the current row in the result set. |
int getUpdateDeferral() | Gets the style of update deferral in effect. |
boolean hasMoreRows() | Indicates whether there are more rows to be fetched beyond the last row now in the cache. |
boolean hasMoreRows(int) | Indicates whether there are more rows to be fetched in a specific direction beyond those now in the cache. |
boolean isCompareLargeColumns() | Returns true if large columns should be compared when locking the current row. |
boolean isFirst() | Indicates whether the first row of the result set is the current row. |
boolean isLast() | Indicates whether the last row of the result set is the current row. |
boolean isLockRows() | Returns true if a database lock is automatically held on a row while it is the current row. |
boolean isOpen() | Returns true if the underlying RowSet is open, otherwise returns false. |
boolean isOpen(int) | Returns true if the JDBC resource at the specified level is open, otherwise returns false. |
boolean isReadOnly() | Returns true if the RowSet is read-only, otherwise returns false. |
boolean isValidateLOBs() | Returns true if LOBs will be validated before they are returned from the cache. |
boolean last() | Applies any changes in the current row to the database, and then moves to the last row in the result set. |
void lockRow() | Locks the current row in the database. |
void newRow(boolean) | Applies any changes in the current row to the database, inserts a new empty row into the result set, and positions to the new row. |
boolean next() | Applies any changes in the current row to the database, and then moves to the next row in the result set. |
boolean onRow() | Returns true if you are currently positioned on a row; returns false otherwise. |
boolean previous() | Applies any changes in the current row to the database, and then moves to the previous row in the result set. |
void reExecute() | Re-executes the statement without re-preparing. |
void refreshRow() | Refreshes the current row with its most recent value in the database. |
void removeDBAfterListener(DBAfterListener) | Removes a listener to the DBAfter event set. |
void removeDBBeforeListener(DBBeforeListener) | Removes a listener to the DBBefore event set. |
void removePropertyChangeListener(PropertyChangeListener) | Removes a listener to the PropertyChange event set. |
void setCacheLimit(int) | Provides a hint for the maximum number of rows to be kept in an in-memory cache of result set rows. |
void setCacheValueAt(Object, int, int) | Sets the value of the column at columnIndex and rowIndex in the cache. |
void setColumn(int, Object) | Sets (in memory) the value of the column at the specified index in the current row. |
void setColumn(String, Object) | Sets (in memory) the value of the column with the specified name in the current row. |
void setColumnFromString(int, String) | Sets (in memory) the value of the column at the specified index in the current row. |
void setColumnFromString(String, String) | Sets (in memory) the value of the column with the specified name in the current row. |
void setCompareLargeColumns(boolean) | If true, large columns will be compared when locking the current row. |
void setDistinctTypesEnabled(boolean) | If true, use of user-defined distinct types is enabled for this RowSet. |
void setFetchSize(int) | Sets the number of rows that should be fetched from the database when more rows are needed. |
void setLockRows(boolean) | If true, a database lock is automatically held on a row while it is the current row. |
void setMaxFieldSize(int) | The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value. |
void setMaxRows(int) | The maxRows limit is set to limit the number of rows that any RowSet can contain. |
void setReadOnly(boolean) | Set the read-only property of the RowSet |
boolean setRow(int) | Applies any changes in the current row to the database, and then positions to the specified row in the result set. |
boolean setRowInCache(int) | Makes the specified row in the cache the current row in the result set. |
void setUpdateDeferral(int) | Sets the style of update deferral. |
void setValidateLOBs(boolean) | If true, LOBs will be validated before they are returned from the cache. |
void unlockRow() | Unlocks the current row. |
void updateRow() | Updates the database with the values of the current row in the result set. |
public static final int DEFER_NOTHING
public static final int DEFER_WRITE_TO_DATABASE
public static final int DEFER_WRITE_TO_DATABASE_AND_ROW_NUMBER_CHANGE
public static final int FETCH_FORWARD
public static final int FETCH_REVERSE
public DBSelect()Default constructor for a DBSelect bean. This constructor also creates associated beans of types DBSelectMetaData, and DBParameterMetaData.
public synchronized void addDBAfterListener(DBAfterListener listener)Adds a listener to the DBAfter event set. DBAfter events occur after significant actions have been completed via the DBSelect.
- Parameters
- listener - DBAfterListener
- Overrides
- addDBAfterListener in class DBStatement
- See Also
public synchronized void addDBBeforeListener(DBBeforeListener listener)Adds a listener to the DBBefore event set. DBBefore events occur before significant actions have been completed via the DBSelect.
- Parameters
- listener - DBBeforeListener
- Overrides
- addDBBeforeListener in class DBStatement
- See Also
public synchronized void addPropertyChangeListener(PropertyChangeListener listener)Adds a listener to the PropertyChange event set.
- Parameters
- listener - PropertyChangeListener
- Overrides
- addPropertyChangeListener in class DBStatement
- See Also
public void applyUpdates() throws DBException, SQLExceptionApply all updateRow, deleteRow, and newRow actions that have been deferred. You will be positioned to the same row before and after applyUpdates, except that its row number may be adjusted for changes that occured while applying the actions. If the current row was deleted, the current row will be the next row, if there is one.
Actions may be deferred simply to delay propagation of changes to the database until a set of changes have occurred, or to both delay propagation of changes to the database and to delay any row number changes that will occur. (Actions such as newRow and deleteRow affect the numbering of subsequent rows.)
- Throws
DBException
readOnly - if the result set is read only- Throws
SQLException
- if a database access error occurred
- See Also
public boolean areDistinctTypesEnabled()Returns true if use of user-defined distinct types is enabled for this RowSet. See the
setDistinctTypesEnabled
method for a fuller discussion of what it means for use of user-defined distinct types to be enabled.
- Returns
- true if use of user-defined distinct types is enabled, otherwise false.
- See Also
public void cancelRowUpdates() throws DBException, SQLExceptionCancels any value changes made in a row. This method may be called after calling a setColumn method and before calling
updateRow
to undo any value changes made in a row. If no updates have been made orupdateRow
has already been called, then this method has no effect.
- Throws
DBException
notExecuted - if associated statement has not been executed- Throws
DBException
noResults - if the result set is empty- Throws
DBException
readOnly - if the result set is read only
public void cancelUpdates() throws DBException, SQLExceptionCancel all updateRow, deleteRow, and newRow actions that have been deferred and not yet applied. If an exception occurred during processing of applyUpdates, you may be unable to proceed without using this method to cancel the remaining changes. The method undoes any changes that were made in the cache as a result of the actions that are being cancelled.
You will be positioned to the same row before and after cancelUpdates, except that its row number may be adjusted.
- Throws
DBException
readOnly - if the result set is read only
- See Also
public void close() throws DBException, SQLExceptionReleases the database and JDBC resources of the underlying
RowSet
object immediately instead of waiting for this to happen when it is automatically closed.The JDBC resources that are released include the Statement, the ResultSet, and the Connection. If
autoCommit
is false, you must explicitly do a commit or rollback before using the close method.
- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
SQLException
if a database access error occurs- Overrides
- close in class DBStatement
public void close(int resourceLevel) throws DBException, SQLExceptionApplies any changes in the current row of the underlying RowSet to the database, and then releases the database and JDBC resources of the RowSet immediately instead of waiting for this to happen when it is automatically closed.
The JDBC resources that may be released include the Statement, the ResultSet, and the Connection. The value of the resourceLevel parameter determines which resources are released. If all resources, including the Connection, are released, and
autoCommit
is false, you must explicitly do a commit or rollback before using the close method.
- Parameters
- resourceLevel - LEVEL_RESULTSET indicates only ResultSet resources should be released. ;LEVEL_STATEMENT indicates Statement and ResultSet resources should be released. LEVEL_CONNECTION indicates Connection, Statement, and ResultSet resources should be released.
- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
SQLException
if a database access error occurs- Overrides
- close in class DBStatement
public void deleteRow() throws DBException, SQLExceptionDeletes the current row from the result set and the underlying database. (If the current row is a new empty row created by the
newRow
method, it is not yet in the database, and is simply deleted from the result set.)The events
aboutToChangeRow_delete
androwChanged_delete
are triggered by this method. The eventsaboutToChangeRowSet_deleteRow
androwSetChanged_deleteRow
are also triggered by this method.
- Throws
DBException
notExecuted - if associated statement has not been executed- Throws
DBException
noActiveConnection - if no active connection exists- Throws
DBException
readOnly - if the result set is read only- Throws
DBException
noResults - if the result set is empty- Throws
DBException
rowChanged - if the current row cannot be deleted because it cannot be found in the database- Throws
DBException
rowNotFound - if the lockRows property of the associated SelectStatement is true and the new current row cannot be locked- Throws
DBException
truncated - if data truncation occurred on retrieval- Throws
SQLException
- if a database access error occurs
public synchronized void execute() throws DBException, SQLExceptionExecutes the query, connecting to the database if not already connected, and fills the rowset with data, positioning to the first row. If successful, any previous contents of the rowset are discarded and the rowset's metadata is also (re)set.
- Returns
- true if the bean was able to position to the first row; false if the rowset is empty
- Throws
DBException
badUidPwd - if incorrect username or password specified- Throws
DBException
noSQL - if the SQL statement is null- Throws
DBException
notSelect - if SQL statement is not a SELECT statement- Throws
DBException
noTransactions - if database does not support transactions and autoCommit set to false- Throws
SQLException
- if a database access error occurred- Overrides
- execute in class DBStatement
public synchronized void execute(int position) throws DBException, SQLExceptionExecutes the query, connecting to the database if not already connected, and fills the rowset with data, positioning to the specified row.
After this method, the specified row is the first row in the cache, as well as being the current row. Assuming the result set contained enough rows to satisfy your request, getRow() should return the number of the row you requested, and getRowInCache() should return 1. Any rows that preceded this one have been passed over, and are only available if the underlying database supports scrollable cursors. In that case, the preceding rows can be reached via methods such as previous(), first(), or setRow().
If the result set did not contain enough rows to satisfy your request, the cache will be empty, getRow() should return the number of the last row in the result set (which has been passed over), and getRowInCache() should return 0.
- Parameters
- position - row number that should be both the current row and the first row in the cache after execution
- Throws
DBException
badUidPwd - if incorrect username or password specified- Throws
DBException
noSQL - if the SQL statement is null- Throws
DBException
notSelect - if SQL statement is not a SELECT statement- Throws
DBException
noTransactions - if database does not support transactions and autoCommit set to false- Throws
SQLException
- if a database access error occurred
- See Also
public boolean fetchMoreRows() throws DBException, SQLExceptionFetches more rows from the database into the row cache. This will normally displace some of the rows currently in the cache. The method does not change which row is current unless the current row is displaced from the cache. In that case, any changes in the current row are first applied to the database and the closest row still in the cache becomes the current row.
This method always fetches in a forward direction. If the underlying result set is scrollable, you can use the fetchMoreRows(int) method to fetch backward towards the beginning of the result set.
If there were no more rows to fetch (including the case where the result set is empty) the method returns false.
- Returns
- true if any rows were fetched; false if there were no rows to fetch
- Throws
DBException
notExecuted - if the query has not been executed- Throws
DBException
notOpen - if the result set is not open- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
DBException
rowNotFound - if the lockRows property is true and the new current row cannot be locked- Throws
SQLException
- if a database access error occurred
- See Also
public synchronized boolean fetchMoreRows(int direction) throws DBException, SQLExceptionFetches more rows from the database into the row cache. This will normally displace some of the rows currently in the cache. The method does not change which row is current unless the current row is displaced from the cache. In that case, any changes in the current row are first applied to the database and the closest row still in the cache becomes the current row.
You can use this method to fetch in a forward direction, or, if the underlying result set is scrollable, to fetch backwards towards the beginning of the result set.
If there were no more rows to fetch (including the case where the result set is empty) the method returns false.
- Parameters
- direction - the direction in which to fetch; valid values are FETCH_FORWARD and FETCH_REVERSE.
- Returns
- true if any rows were fetched; false if there were no rows to fetch
- Throws
DBException
notExecuted - if the query has not been executed- Throws
DBException
notOpen - if the result set is not open- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
DBException
rowNotFound - if the lockRows property is true and the new current row cannot be locked- Throws
SQLException
- if a database access error occurred
- See Also
public int findColumn(String columnName) throws DBException, SQLExceptionMaps the given column label to its column index. The index of the first column is 1.
- Parameters
- columnName - the label of the column
- Returns
- the column index
- Throws
DBException
columnNotDefined - the column with the specified label is not defined
public synchronized boolean first() throws DBException, SQLExceptionApplies any changes in the current row to the database, and then moves to the first row in the result set. If the first row has been displaced from the cache and it is not possible to re-fetch displaced rows (re-fetching is never possible for an updatable DBSelect bean) the method leaves the cursor on the first row in the cache and returns false.
If row locking has been requested, the new current row is locked in the database.
The event
propertyChange
is triggered by this method for the bound properties row and rowInCache. The eventsaboutToChangeRowSet_fetchRow
androwSetChanged_fetchRow
may be triggered by this method.
- Returns
- true if the position moved to the first row; false if the result set is empty or the first row is no longer accessible
- Throws
DBException
notExecuted - if the query has not been executed- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
DBException
rowNotFound - if the lockRows property is true and the new current row cannot be locked- Throws
SQLException
- if a database access error occured
- See Also
public int getCacheLimit()Gets the maximum number of rows to be kept in an in-memory cache of result set rows. A value of 0 means that there is no limit on the number of rows in the cache. If you do not set cacheLimit, it will default to 0 (unlimited).
There are interactions between the values you specify for fetchSize and cacheLimit. If you specify a fetchSize greater than 1 row, and cacheLimit is not an exact multiple of fetchSize, cacheLimit is rounded up to the next multiple of fetchSize.
The actual number of rows in the cache will grow or shrink when you perform newRow() or deleteRow(), and may at times actually exceed. the cacheLimit value. But whenever more rows are fetched from the database, the number of rows in the cache will re-adjust to the specified limit.
For a DBProcedureCall bean, this property is the maximum number of rows for each result set. Thus the true maximum is this number times the number of result sets. For a DBSelect bean, there is only one result set.
- Returns
- the maximum number of rows kept in the in-memory cache
- See Also
public int getCacheRowCount()Returns the number of rows in the cache.
For a DBProcedureCall bean, this is the number of rows in the cache for the current result set. Rows may also be cached for other result sets, and they are not included in this count. For a DBSelect bean, there is only one result set.
- Returns
- the number of rows in cache
- See Also
public Object getCacheValueAt(int rowIndex, int columnIndex) throws DBException, SQLExceptionReturns the value at rowIndex and columnIndex in the cache. The index of the first row or column in the cache is 1.
For a DBProcedureCall bean, the value is from the current result set.
- Parameters
- rowIndex - the row number in the cache
- columnIndex - the column number in the cache
- Returns
- the value Object at the specified row and column
- Throws
DBException
notExecuted - if statement has not been executed- Throws
DBException
noCurrentResult - if the you are not positioned on a result set.- Throws
DBException
noResults - if the result set is empty- Throws
DBException
cacheEmpty - if there are no rows in the cache- Throws
DBException
invalidRowNumber - if requested row number is less than 1- Throws
DBException
columnNotDefined - if the column index is not defined- Throws
DBException
indexTooLarge - if the row index is too large
- See Also
public Object getColumn(int columnNumber) throws DBException, SQLExceptionReturns the value of the column at the specified index in the current row. The index of the first column is 1.
For a DBProcedureCall bean, the value is from the current row of the current result set.
- Parameters
- columnNumber - index of the column
- Returns
- value of the column
- Throws
DBException
notExecuted - if associated statement has not been executed- Throws
DBException
noResults - if the result set is empty- Throws
DBException
columnNotDefined - if the column index is not defined
public Object getColumn(String columnName) throws DBException, SQLExceptionReturns the value of the column with the specified name in the current row.
For a DBProcedureCall bean, the value is from the current row of the current result set.
- Parameters
- columnName - name of the column
- Returns
- value of the column
- Throws
DBException
notExecuted - if associated statement has not been executed- Throws
DBException
noResults - if the result set is empty- Throws
DBException
columnNotDefined - if the column index is not defined
public String getColumnAsString(int columnNumber) throws DBException, SQLExceptionReturns the value of the column at the specified index in the current row as a String. The value of the column is converted to a String before it is returned. If the column value is null, a null is returned. The index of the first column is 1.
For a DBProcedureCall bean, the value is from the current row of the current result set.
- Parameters
- columnNumber - index of the column
- Returns
- value of the column as a String.
- Throws
DBException
notExecuted - if associated statement has not been executed- Throws
DBException
noResults - if the result set is empty- Throws
DBException
columnNotDefined - if the column index is not defined
public String getColumnAsString(String columnName) throws DBException, SQLExceptionReturns the value of the column with the specified name in the current row as a String. The value of the column is converted to a String before it is returned. If the column value is null, a null is returned.
For a DBProcedureCall bean, the value is from the current row of the current result set.
- Parameters
- columnName - name of the column
- Returns
- value of the column as a String.
- Throws
DBException
notExecuted - if associated statement has not been executed- Throws
DBException
noResults - if the result set is empty- Throws
DBException
columnNotDefined - if the column index is not defined
public int getColumnCount() throws SQLExceptionReturns the number of columns in the RowSet. Until the statement has been executed, this returns information based on the user-provided meta data provided for the bean. Once it has been executed, it returns the actual number of columns in the result set.
For a DBProcedureCall bean, the method applies to the current result set.
- Returns
- the number of columns in the RowSet
- See Also
public String getColumnName(int columnIndex) throws DBException, SQLExceptionReturns the name of the column at columnIndex. The index of the first column is 1.
For a DBProcedureCall bean, the method applies to the current result set.
- Parameters
- columnIndex - the index of column
- Returns
- the name of the column
- Throws
DBException
columnNotDefined - if column not defined in the meta data.
public int getFetchSize() throws SQLExceptionGets the number of rows that should be fetched from the database when more rows are needed. If you do not set fetchSize, it will default to 1. Setting fetchSize to 0 is equivalent to setting it to 1. (At least one row will always be fetched.)
There are interactions between the values for fetchSize and cacheLimit. If you use the cacheLimit property to limit the number of rows stored at one time in the cache, then whenever more rows are fetched, enough rows are displaced from the cache to make room for fetchSize number of new rows. If you specify a cacheLimit that is not an exact multiple of fetchSize, cacheLimit is treated as a hint, and rounded up to the next multiple of fetchSize.
- Returns
- the number of rows to fetch
- See Also
public int getMaxFieldSize() throws SQLExceptionThe maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value. Itt only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. If the limit is exceeded, the excess data is silently discarded.
- Returns
- the current max column size limit; zero means unlimited
- Throws
SQLException
if a database-access error occurs.
- See Also
public int getMaxRows() throws SQLExceptionThe maxRows limit is the maximum number of rows that a RowSet can contain. If the limit is exceeded, the excess rows are silently dropped.
For a DBProcedureCall bean, this property is the maximum number of rows for each result set. Thus the true maximum is this number times the number of result sets. For a DBSelect bean, there is only one result set.
- Returns
- the current max row limit; zero means unlimited
- Throws
SQLException
if a database-access error occurs.
- See Also
public DBSelectMetaData getMetaData() throws SQLExceptionRetrieves the DBSelectMetaData object describing the result set.
The DBSelectMetaData object describes the columns of the result. You can also obtain the java.sql.ResultSetMetaData object itself from the DBSelectMetaData.
For a DBProcedureCall bean, the DBSelectMetaData object describes the current result set. If the stored procedure has not yet been executed, or did not return a result set, the method returns a null value. For a DBSelect bean, there is exactly one result set, and its description is always returned.
- Returns
- the DBSelectMetaData describing the result set
- See Also
public int getRow() throws SQLExceptionRetrieves the current row number. The first row is number 1, the second number 2, and so on.
For a DBProcedureCall bean, the method applies to the current result set.
- Returns
- the current row number; 0 if there is no current row
- Throws
SQLException
if a database access error occurs
- See Also
public int getRowCount()Returns the number of rows currently in the result set. This number changes as rows are fetched from the database, deleted, or added via the
newRow
method. It does not reflect the total number of rows available to be fetched, but only those rows whose existence has been established by fetches done thus far.For a DBProcedureCall bean, the method applies to the current result set.
- Returns
- the number of rows in the result set
- See Also
public int getRowInCache() throws SQLExceptionReturns the index in the cache of the current row in the result set. The index of the first row in the cache is 1. If there are no rows in the result set, or the cursor in the RowSet is before the cache, a value of 0 is returned.
The values of rowInCache and row will be the same unless you have set cacheLimit to a value other than 0 and one or more rows have been displaced from the cache. For example, if 10 rows have been displaced from the cache and the current row is 11, the value of rowInCache would be 1.
For a DBProcedureCall bean, the method applies to the current result set.
- Returns
- index in the cache of the current row
- See Also
public int getUpdateDeferral()Gets the style of update deferral in effect.
See the
setUpdateDeferral
method for an explanation of the possible values returned.
- Returns
- the style of update deferral in effect.
- See Also
public boolean hasMoreRows()Indicates whether there are more rows to be fetched beyond the last row now in the cache.
For a DBProcedureCall bean, the method applies to the current result set.
- Returns
- true if there are more rows to fetch, false otherwise.
- See Also
public boolean hasMoreRows(int direction) throws DBException, SQLExceptionIndicates whether there are more rows to be fetched in a specific direction beyond those now in the cache.
For a DBProcedureCall bean, the method applies to the current result set.
- Parameters
- direction - valid values are FETCH_FORWARD and FETCH_REVERSE.
- Returns
- true if there are more rows to fetch, false otherwise.
- Throws
- See Also
public boolean isCompareLargeColumns()Returns true if large columns should be compared when locking the current row.
Before locking a row in the database, its values are compared with those last known by this bean to be in the database. If no row is an exact match (the row may have been deleted or updated) no lock is obtained. If positional updates and deletes are being used, this lock must be obtained before the update or delete can occur.
When this property is set, columns of types BLOB, CLOB, LONGVARBINARY, and LONGVARCHAR will not be compared. This can be a performance enhancement. However, if users of this bean will be updating columns of these types and the property is false, it is possible to overwrite updates made outside of the bean.
If you do not execute this method, the value defaults to false.
- Returns
- true if large columns should be compared when obtaining row lock
- See Also
public boolean isFirst() throws SQLExceptionIndicates whether the first row of the result set is the current row.
For a DBProcedureCall bean, the method applies to the current result set.
- Returns
- true if the first row is the current row, false otherwise.
- Throws
SQLException
if a database access error occurs
- See Also
public boolean isLast() throws SQLExceptionIndicates whether the last row of the result set is the current row.
For a DBProcedureCall bean, the method applies to the current result set.
- Returns
- true if the last row is the current row, false otherwise.
- Throws
SQLException
if a database access error occurs
- See Also
public boolean isLockRows()Returns true if a database lock is automatically held on a row while it is the current row. Returns false if a database lock is only held on a row while it is being updated in the database.
See the
lockRow
method for a fuller discussion of what it means for a row to be locked.
- Returns
- true if a database lock is automatically held on a row while it is the current row; else false.
- See Also
public boolean isOpen() throws SQLExceptionReturns true if the underlying RowSet is open, otherwise returns false.
When
isOpen
returns true, the database Connection, Statement, and ResultSet are all open, and the RowSet is fully functional.When
isOpen
returns false, it may be because the statement has not been executed, theclose
method has been invoked, or the DBSelect bean has been serialized and then de-serialized.If the RowSet is not open, you can scroll among the rows currently in the cache, and you can even perform inserts, updates, and deletes, but you cannot fetch any additional rows.
- Returns
- true if the RowSet is open, otherwise false.
- Overrides
- isOpen in class DBStatement
public boolean isOpen(int resourceLevel) throws DBException, SQLExceptionReturns true if the JDBC resource at the specified level is open, otherwise returns false. If the resourceLevel is LEVEL_CONNECTION, a return value of true indicates that the Connection is open. If the resourceLevel is LEVEL_STATEMENT, a return value of true indicates that the Statement, and therefore also the Connection are open. If the resourceLevel is LEVEL_RESULTSET, a return value of true indicates that the ResultSet, and therefore also the Statement, and Connection are open.
For a DBProcedureCall bean, if the resourceLevel is LEVEL_RESULTSET, the method applies to the current result set.
- Parameters
- resourceLevel - A resource level: LEVEL_CONNECTION, LEVEL_STATEMENT, or LEVEL_RESULTSET.
- Returns
- true if the JDBC resource at the specified level is open, otherwise false.
- Throws
DBException
invalidResourceLevel - if the resource level is not valid- Throws
SQLException
if a database-access error occurs.- Overrides
- isOpen in class DBStatement
public boolean isReadOnly()Returns true if the RowSet is read-only, otherwise returns false.
Attempts to update a read-only rowset will result in an exception being thrown. RowSets are updateable by default, if updates are possible.
- Returns
- true if the RowSet is read-only, otherwise false.
- See Also
public boolean isValidateLOBs()Returns true if LOBs will be validated before they are returned from the cache.
A LOB is validated by attempting to access its data. If this fails (because, for example, a commit has occurred since the value was fetched), a new LOB is obtained and returned to you by re-fetching the column from the database.
- Returns
- true if LOBs will be validated. else false.
- See Also
public synchronized boolean last() throws DBException, SQLExceptionApplies any changes in the current row to the database, and then moves to the last row in the result set.
If the last row is not in the cache, additional rows will be fetched so as to put the last row into the cache.
If row locking has been requested, the new current row is locked in the database.
For a DBProcedureCall bean, the method applies to the current result set.
The event
propertyChange
is triggered by this method for the bound properties row and rowInCache. The eventsaboutToChangeRowSet_fetchRow
androwSetChanged_fetchRow
may be triggered by this method.
- Returns
- true if the position moved to the last row; false if the result set is empty
- Throws
SQLException
if a database access error occurs or the result set is empty- Throws
DBException
notExecuted - if the query has not been executed- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
DBException
rowNotFound - if the lockRows property is true and the new current row cannot be locked- Throws
SQLException
- if a database access error occured
- See Also
public synchronized void lockRow() throws DBException, SQLExceptionLocks the current row in the database. No updates can be made to this row using another connection until the lock is released. The lock is automatically released when you move to another row. You can release the lock without moving to another row by invoking the
unlockRow
method.To implement this method, we generate and execute an SQL query that opens a database cursor locking the row. If no row can be found in the database exactly matching the current row, an exception is thrown. Failure to find a matching row may occur if the row was changed in the database by means other than this SelectResult after being fetched.
If more than one row is found in the database, an exception is thrown. To insure that only one row is found, make sure that the query used to produce the result set includes columns that uniquely identify a row.
For a DBProcedureCall bean, the method applies to the current result set.
- Throws
DBException
notExecuted - if the query has not been executed- Throws
DBException
noResults - if the result set is empty- Throws
DBException
noActiveConnection - if no active connection exists- Throws
DBException
readOnly - if the result set is read only- Throws
DBException
multipleRowsFound - if the current row cannot be locked because it cannot be uniquely identified in the database- Throws
DBException
rowNotFound - if the current row cannot be locked because it cannot be found in the database- Throws
DBException
rowNotInDatabase - if the current row cannot be locked in the database because it has not yet been written to the database- Throws
DBException
lockNotSupported - if the current row cannot be locked because the database does not have function required to do so- Throws
DBException
truncated - if data truncation occurred on retrieval- Throws
SQLException
- if a database access error occurred
- See Also
public void newRow(boolean beforeCurrent) throws DBException, SQLExceptionApplies any changes in the current row to the database, inserts a new empty row into the result set, and positions to the new row. Use the
setColumnValue
method to set values for its columns. The new row is not inserted into the database until you set values and move to another row or invoke theupdateRow
method.If you move to another row without setting any values in the new row, the new row remains in the result set, but has not yet been inserted into the database. You can return to it later, set values, and insert it into the database.
For a DBProcedureCall bean, the method applies to the current result set.
The event
propertyChange
is triggered by this method for the bound properties row and rowInCache. The eventsaboutToChangeRowSet_newRow
androwSetChanged_newRow
are triggered by this method.
- Parameters
- beforeCurrent - true, add the new row before the current row; false add the new row after the current row.
- Throws
DBException
notExecuted - if associated statement has not been executed- Throws
DBException
readOnly - if the result set is read only- Throws
DBException
maxSize - if the maximum number of rows in the result set has been reached- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
SQLException
- if a database access error occurred
public synchronized boolean next() throws DBException, SQLExceptionApplies any changes in the current row to the database, and then moves to the next row in the result set.
If the next row is not in the cache, fetchSize number of rows are fetched. If no more rows can be fetched, the method returns false, your position does not change, and no exception is thrown. Thus, if the result set is empty, or you are at the end of the result set, repeatedly invoking this method has no effect. For a discussion of when no more rows can be fetched, see the
isEnd
method.If row locking has been requested, the new current row is locked in the database.
For a DBProcedureCall bean, the method applies to the current result set.
The event
propertyChange
is triggered by this method for the bound properties row and rowInCache. The eventsaboutToChangeRowSet_fetchRow
androwSetChanged_fetchRow
may be triggered by this method.
- Returns
- true if the position moved to the next row; false if there was no next row
- Throws
DBException
notExecuted - if the query has not been executed- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
DBException
rowNotFound - if the lockRows property is true and the new current row cannot be locked- Throws
SQLException
- if a database access error occurred
- See Also
public boolean onRow()Returns true if you are currently positioned on a row; returns false otherwise.
If you call this method immediately after the
execute()
method, it tells you whether there are any rows in the result set.There are very limited circumstances in which there can be rows in the result set, but you are not positioned to any of them. This can only occur when you have limited the cache size to support large result sets, and you have deleted all the rows in the cache. There may still be rows both before and after the cache, but because none of these rows is currently in the cache, you are not positioned to any of them. Note that when this situation arises,
getRow()
will return the number of the last row before the start of the cache, butonRow()
will tell you that you are not actually positioned to it.For a DBProcedureCall bean, the method applies to the current result set.
- Returns
- true if you are positined on a row, otherwise false.
public synchronized boolean previous() throws DBException, SQLExceptionApplies any changes in the current row to the database, and then moves to the previous row in the result set.
If the previous row is not in the cache, and displaced rows can be re-fetched, fetchSize number of rows are re-fetched. If there is no previous row to fetch or the result set does not support re-fetching displaced rows, the method returns false, your position does not change, and no exception is thrown. Thus, if the result set is empty, or you are at the beginning of the result set, or you are at the beginning of the cache and displaced rows cannot be re-fetched, repeatedly invoking this method has no effect.
Displaced rows can only be re-fetched if the rowset is read-only and you are using a JDBC 2.0 driver that supports scrollable cursors.
If row locking has been requested, the new current row is locked in the database.
For a DBProcedureCall bean, the method applies to the current result set.
The event
propertyChange
is triggered by this method for the bound properties row and rowInCache. The eventsaboutToChangeRowSet_fetchRow
androwSetChanged_fetchRow
may be triggered by this method.
- Returns
- true if the position moved to the previous row; false if there was no previous row
- Throws
DBException
notExecuted - if the query has not been executed- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
DBException
rowNotFound - if the lockRows property is true and the new current row cannot be locked- Throws
SQLException
- if a database access error occurred
- See Also
public synchronized void reExecute() throws DBException, SQLExceptionRe-executes the statement without re-preparing. The rowset must currently be open. If successful, the current contents of the rowset are discarded. Any changes you have made to statement parameters will take effect when the statement is re-executed. If you have changed the query itself, that change will not take effect. (To make the latter change take effect, use the
execute
method.
- Throws
DBException
noActiveConnection - if no active connection exists- Throws
DBException
notOpen - if the statement is not open- Throws
SQLException
- if a database access error occurred- Overrides
- reExecute in class DBStatement
- See Also
public void refreshRow() throws DBException, SQLExceptionRefreshes the current row with its most recent value in the database. Cannot be called when on a new empty row created by
newRow()
.All values are refetched subject to the transaction isolation level and cursor sensitivity. If
refreshRow
is called after callingsetColumn
, but before callingupdateRow
, then the value changes made to the row are lost.
- Throws
DBException
notExecuted - if associated statement has not been executed- Throws
DBException
noResults - if the result set is empty- Throws
DBException
rowNotInDatabase - if the current row cannot be refreshed because it has not yet been written to the database- Throws
DBException
truncated - if data truncation occurred on retrieval- Throws
SQLException
- if a database access error occurs
- See Also
public synchronized void removeDBAfterListener(DBAfterListener listener)Removes a listener to the DBAfter event set. DBAfter events occur after significant actions have been completed via the DBSelect.
- Parameters
- listener - DBAfterListener
- Overrides
- removeDBAfterListener in class DBStatement
- See Also
public synchronized void removeDBBeforeListener(DBBeforeListener listener)Removes a listener to the DBBefore event set. DBBefore events occur before significant actions have been completed via the DBSelect.
- Parameters
- listener - DBBeforeListener
- Overrides
- removeDBBeforeListener in class DBStatement
- See Also
public synchronized void removePropertyChangeListener(PropertyChangeListener listener)Removes a listener to the PropertyChange event set.
- Parameters
- listener - PropertyChangeListener
- Overrides
- removePropertyChangeListener in class DBStatement
- See Also
public synchronized void setCacheLimit(int rows) throws DBException, SQLExceptionProvides a hint for the maximum number of rows to be kept in an in-memory cache of result set rows. A value of 0 means that there is no limit on the number of rows in the cache. If you do not set cacheLimit, it will default to 0 (unlimited).
There are interactions between the values you specify for fetchSize and cacheLimit. If you specify a fetchSize greater than 1 row, and cacheLimit is not an exact multiple of fetchSize, cacheLimit is rounded up to the next multiple of fetchSize.
The actual number of rows in the cache will grow or shrink when you perform newRow() or deleteRow(). But whenever more rows are fetched from the database, the number of rows in the cache will re-adjust to the specified size.
- Parameters
- rows - the maximum number of rows to keep in the cache
- Throws
DBException
invalidRowNumber - if the condition 0 <= rows is not satisfied
- See Also
public synchronized void setCacheValueAt(Object aValue, int rowIndex, int columnIndex) throws DBException, SQLExceptionSets the value of the column at columnIndex and rowIndex in the cache. The index of the first row or column in the cache is 1.
If a String value is supplied, the value will be automatically converted to the correct datatype.
If the specified cache row was not already the current row, first applies any changes in the current row to the database, and then makes the specified row in the cache the current row. The new value supplied in this method is not set in the database until you move to another row or invoke
updateRow
.For a DBProcedureCall bean, the value is set in the current result set.
- Parameters
- aValue - the new value
- rowIndex - the row whose value is to be changed
- columnIndex - the column whose value is to be changed
- Throws
DBException
notExecuted - if statement has not been executed- Throws
DBException
readOnly - if the result set is read only- Throws
DBException
noCurrentResult - if the you are not positioned on a result set.- Throws
DBException
noResults - if the result set is empty- Throws
DBException
cacheEmpty - if there are no rows in the cache- Throws
DBException
invalidRowNumber - if requested row number is less than 1- Throws
DBException
columnNotDefined - if the column index is not defined- Throws
DBException
indexTooLarge - if the row index is too large- Throws
DBException
wrongObjectType - if the value does not match the object type of the column- Throws
DBException
truncated - if data truncation occurred on retrieval.
- See Also
public void setColumn(int columnNumber, Object aValue) throws DBException, SQLExceptionSets (in memory) the value of the column at the specified index in the current row. To set a column value to null, pass null as the value. The index of the first column is 1.
The column value is not updated in the database until you move to another row, call the
updateRow
method, or close the RowSet.For a DBProcedureCall bean, the value is set in the current row of the current result set.
The event
rowSetChanged_columnValue
is triggered by this method.
- Parameters
- columnNumber - index of the column
- aValue - value for the column
- Throws
DBException
notExecuted - if statement has not been executed- Throws
DBException
readOnly - if the result set is read only- Throws
DBException
noResults - if the result set is empty- Throws
DBException
columnNotDefined - if the column index is not defined- Throws
DBException
wrongObjectType - if the value does not match the object type of the column- Throws
DBException
truncated - if data truncation occurred on retrieval.
public void setColumn(String columnName, Object aValue) throws DBException, SQLExceptionSets (in memory) the value of the column with the specified name in the current row. To set a column value to null, pass null as the value.
The column value is not updated in the database until you move to another row, call the
updateRow
method, or close the RowSet.For a DBProcedureCall bean, the value is set in the current row of the current result set.
The event
rowSetChanged_columnValue
is triggered by this method.
- Parameters
- columnName - name of the column
- aValue - value for the column
- Throws
DBException
notExecuted - if statement has not been executed- Throws
DBException
readOnly - if the result set is read only- Throws
DBException
noResults - if the result set is empty- Throws
DBException
columnNotDefined - if the column index is not defined- Throws
DBException
wrongObjectType - if the value does not match the object type of the column- Throws
DBException
truncated - if data truncation occurred on retrieval.
public void setColumnFromString(int columnNumber, String stringValue) throws DBException, SQLExceptionSets (in memory) the value of the column at the specified index in the current row. The index of the first column is 1. If the Select has not been executed and the specified stringValue is null or has zero length, the method returns without setting the column value.
The stringValue parameter is converted to the datatype associated with the column before the value is set. To set a column value to null, pass null as the value. If the datatype is not String, you can also set a column value to null by passing a zero-length String as the value.
The column value is not updated in the database until you move to another row, call the
updateRow
method, or close the RowSet.For a DBProcedureCall bean, the value is set in the current row of the current result set.
The event
rowSetChanged_columnValue
is triggered by this method.
- Parameters
- columnNumber - index of the column
- stringValue - value for the column
- Throws
DBException
notExecuted - if the statement has not been executed- Throws
DBException
readOnly - if the result set is read only- Throws
DBException
noResults - if the result set is empty- Throws
DBException
columnNotDefined - if the column index is not defined- Throws
DBException
cannotConvert - if cannot convert to object type of column- Throws
DBException
truncated - if data truncation occurred on retrieval.
public void setColumnFromString(String columnName, String stringValue) throws DBException, SQLExceptionSets (in memory) the value of the column with the specified name in the current row. If the Select has not been executed and the specified stringValue is null or has zero length, the method returns without setting the column value.
The stringValue parameter is converted to the datatype associated with the column before the value is set. To set a column value to null, pass null as the value. If the datatype is not String, you can also set a column value to null by passing a zero-length String as the value.
The column value is not updated in the database until you move to another row, call the
updateRow
method, or close the RowSet.For a DBProcedureCall bean, the value is set in the current row of the current result set.
The event
rowSetChanged_columnValue
is triggered by this method.
- Parameters
- columnName - name of the column
- stringValue - value for the column
- Throws
DBException
notExecuted - if the statement has not been executed- Throws
DBException
readOnly - if the result set is read only- Throws
DBException
noResults - if the result set is empty- Throws
DBException
columnNotDefined - if the column index is not defined- Throws
DBException
cannotConvert - if cannot convert to object type of column- Throws
DBException
truncated - if data truncation occurred on retrieval.
public void setCompareLargeColumns(boolean compare)If true, large columns will be compared when locking the current row.
Before locking a row in the database, its values are compared with those last known by this bean to be in the database. If no row is an exact match (the row may have been deleted or updated) no lock is obtained. If positional updates and deletes are being used, this lock must be obtained before the update or delete can occur.
When this property is set, columns of types BLOB, CLOB, LONGVARBINARY, and LONGVARCHAR will not be compared. This can be a performance enhancement. However, if users of this bean will be updating columns of these types and the property is false, it is possible to overwrite updates made outside of the bean.
If you do not execute this method, the value defaults to false.
- Parameters
- compare - true compare large columns when obtaining row lock; false do not compare large columns.
- See Also
public void setDistinctTypesEnabled(boolean enabled)If true, use of user-defined distinct types is enabled for this RowSet.
If you never execute this method, the value defaults to false.
When use of user-defined distinct types is not enabled, you cannot use the DBSelect bean to update, delete, or lock a row. You can, however, retrieve data of user-defined types, and you can use the Select bean to insert rows in the database.
When use of user-defined distinct types is enabled, you can retrieve data of user defined types, as well as use the DBSelect bean to insert, update, delete, or lock rows.
Implementation of this feature makes use of the CAST specification in SQL. The database you are using must support casting if you turn this enablement on. It does no harm to turn enablement on even if your statement uses no user-defined distinct types, but the SQL we generate to update, delete, or lock a row will be more complex, making use of the CAST specification for all columns.
- Parameters
- enabled - true if use of user-defined distinct types should be enabled; false if it should not be enabled.
- See Also
public synchronized void setFetchSize(int rows) throws DBException, SQLExceptionSets the number of rows that should be fetched from the database when more rows are needed. If you do not set fetchSize, it will default to 1. Setting fetchSize to 0 is equivalent to setting it to 1. (At least one row will always be fetched.)
There are interactions between the values you specify for fetchSize and cacheLimit. If you use the cacheLimit property to limit the number of rows stored at one time in the cache, then whenever more rows are fetched, enough rows are displaced from the cache to make room for fetchSize number of new rows. If your specified cacheLimit is not an exact multiple of fetchSize, cacheLimit is treated as a hint, and rounded up to the next multiple of fetchSize.
- Parameters
- rows - the number of rows to fetch
- Throws
DBException
invalidRowNumber - if the condition 0 <= rows <= this.getMaxRows() is not satisfied- Throws
SQLException
- if a database access error occurred
- See Also
public void setLockRows(boolean lockRows) throws DBException, SQLExceptionIf true, a database lock is automatically held on a row while it is the current row. If false, a database lock is only held on a row while it is being updated in the database.
If you never execute this method, the value defaults to false.
See the
lockRow
method for a fuller discussion of what it means for a row to be locked.
- Parameters
- lockRows - true, hold database lock while a row is the current row; false hold database lock only while a row is being updated.
- Throws
DBException
noDeferralWithAutomaticLocking - if updates are being deferred
- See Also
public void setMaxFieldSize(int max) throws DBException, SQLExceptionThe maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value.
It only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. If the limit is exceeded, the excess data is silently discarded. For maximum portability use values greater than 256.
- Parameters
- max - the new max column size limit; zero means unlimited
- Throws
SQLException
if a database-access error occurs.
- See Also
public void setMaxRows(int max) throws DBException, SQLExceptionThe maxRows limit is set to limit the number of rows that any RowSet can contain. If the limit is exceeded, the excess rows are silently dropped.
- Parameters
- max - the new max rows limit; zero means unlimited
- Throws
SQLException
if a database-access error occurs.
- See Also
public void setReadOnly(boolean value) throws SQLExceptionSet the read-only property of the RowSet
Attempts to update a read-only rowset will result in an exception being thrown. RowSets are updateable by default, if updates are possible.
- Parameters
- value - true if read-only, false otherwise
- Throws
SQLException
if a database-access error occurs.- Throws
SQLException
if a database-access error occurs.
- See Also
public synchronized boolean setRow(int rowNumber) throws DBException, SQLExceptionApplies any changes in the current row to the database, and then positions to the specified row in the result set. The index of the first row is 1.
If the specified row is not in the cache, it is fetched (if possible), along with any sufficient intervening rows to fill the cache. (It would not be possible to fetch a row if, for example, it had been displaced from the cache, and the underlying RowSet did not support re-fetching displaced rows.) If the specified row cannot be reached, the method leaves the cursor on the closest row to it in the cache and returns false.
Specifying any row number less than 0 will cause an exception to be thrown.
If row locking has been requested, the new current row is locked in the database.
For a DBProcedureCall bean, the method applies to the current result set.
The event
propertyChange
is triggered by this method for the bound properties row and rowInCache. The eventsaboutToChangeRowSet_fetchRow
androwSetChanged_fetchRow
may be triggered by this method.
- Parameters
- rowNumber - index in the result set of the row; the index of the first row is 1
- Returns
- true if the position moved to the specified row; false if the specified row was not reached
- Throws
DBException
invalidRowNumber - if requested row number is less than 1- Throws
DBException
notExecuted - if associated statement has not been executed- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
DBException
rowNotFound - if the lockRows property is true and the new current row cannot be locked- Throws
SQLException
- if a database access error occurred
public synchronized boolean setRowInCache(int rowNumber) throws DBException, SQLExceptionMakes the specified row in the cache the current row in the result set. The index of the first row is 1.
The values of rowInCache and row will be the same unless you have set cacheLimit to a value other than 0 and one or more rows have been displaced from the cache. For example, if 10 rows have been displaced from the cache and the current row is 11, the value of rowInCache would be 1.
For a DBProcedureCall bean, the method applies to the current result set.
- Parameters
- row - the index of the row in the cache
- Returns
- true if the position moved to the specified row; false if the specified row was beyond the end of the result set
- Throws
DBException
invalidRowNumber - if requested row number is less than 1- Throws
DBException
notExecuted - if statement has not been executed- Throws
DBException
rowChanged - if the current row cannot be updated in the database because it has been modified by another user since it was fetched- Throws
DBException
rowNotFound - if the lockRows property true and the new current row cannot be locked- Throws
SQLException
- if a database access error occurred
- See Also
public void setUpdateDeferral(int style) throws DBException, SQLExceptionSets the style of update deferral.
The style DEFER_NOTHING means that updates, deletes, and inserts will be propagated immediately to the database. The style DEFER_WRITE_TO_DATABASE means that no changes will be propagated to the database until you call the applyUpdates() method, but all such changes will be visible in the cache. The style DEFER_WRITE_TO_DATABASE_AND_ROW_NUMBER_CHANGE means that no changes will be propagated to the database and no changes affecting row numbers will be applied to the cache until you call the applyUpdates() method. This means that deleted rows remain in the cache (flagged as deleted) and rows added via newRow() are not accessible.
If you never execute this method, the value defaults to DEFER_NOTHING.
- Parameters
- style - the style of update deferral requested.
- Throws
DBException
noDeferralWithAutomaticLocking - if the lockRows property has been set- Throws
DBException
noDeferralWithLockedRow - if the current row is locked in the database- Throws
DBException
mustApplyRowValueChanges - if values in the current row have been changed- Throws
DBException
mustApplyDeferredUpdates - if there are pending deferred updates
- See Also
public void setValidateLOBs(boolean validateLOBs)If true, LOBs will be validated before they are returned from the cache. A LOB is validated by attempting to access its data. If this fails (because, for example, a commit has occurred since the value was fetched), a new LOB is obtained and returned to you by re-fetching the column from the database.
- See Also
public void unlockRow() throws DBException, SQLExceptionUnlocks the current row. The database lock on the current row is released. If the current row is not locked, this has no effect.
- Throws
DBException
notExecuted - if the query has not been executed- Throws
DBException
noResults - if the result set is empty- Throws
DBException
noActiveConnection - if no active connection exists- Throws
DBException
readOnly - if the result set is read only- Throws
DBException
sqlException - if an SQLException occurred
- See Also
public void updateRow() throws DBException, SQLExceptionUpdates the database with the values of the current row in the result set. If the current row is a new row, it is inserted into the database. If it is an existing row, it is updated in the database.
The bean generates and executes the SQL necessary to update the current row in the database. To insure that your update affects the intended row in the database, make sure that the query used to produce the result set includes columns that uniquely identify a row.
If no row can be found in the database exactly matching the current row, an exception is thrown. Failure to find a matching row may occur if the row was changed in the database by means other than this DBSelect after being fetched.
If more than one row is found in the database, no exception is thrown. The number of rows updated depends on whether the bean performs a positioned or searched update. Whenever possible, the bean performs a positioned update, which updates the first matching row. Otherwise, the bean performs a searched update, which updates all matching rows and logs a message. You can avoid having multiple matching rows by including enough columns in the result set to uniquely identify a row.
For a DBProcedureCall bean, the method applies to the current result set.
The events
aboutToChangeRow_update
androwChanged_update
may be triggered by this method. The eventsaboutToChangeRow_insert
androwChanged_insert
may be triggered by this method.
- Throws
DBException
notExecuted - if associated statement has not been executed- Throws
DBException
noResults - if the result set is empty- Throws
DBException
noActiveConnection - if no active connection exists- Throws
DBException
readOnly - if the result set is read only- Throws
DBException
rowChanged - if the current row cannot be updated because it cannot be found in the database- Throws
SQLException
- if a database access error occurred