Class Hierarchy All Classes All Fields and Methods

 

Class com.ibm.db.beans.DBSelect 

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 Index
Field Description
DEFER_NOTHING  
DEFER_WRITE_TO_DATABASE  
DEFER_WRITE_TO_DATABASE_AND_ROW_NUMBER_CHANGE  
FETCH_FORWARD  
FETCH_REVERSE  

Constructor Index
Constructor Description
DBSelect() Default constructor for a DBSelect bean.

Method Index
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() 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.

 

Fields

 

DEFER_NOTHING

public static final int DEFER_NOTHING

 

DEFER_WRITE_TO_DATABASE

public static final int DEFER_WRITE_TO_DATABASE

 

DEFER_WRITE_TO_DATABASE_AND_ROW_NUMBER_CHANGE

public static final int DEFER_WRITE_TO_DATABASE_AND_ROW_NUMBER_CHANGE

 

FETCH_FORWARD

public static final int FETCH_FORWARD

 

FETCH_REVERSE

public static final int FETCH_REVERSE

 

Constructors

 

DBSelect

public DBSelect()

Default constructor for a DBSelect bean. This constructor also creates associated beans of types DBSelectMetaData, and DBParameterMetaData.

 

Methods

 

addDBAfterListener

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.

 

addDBBeforeListener

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.

 

addPropertyChangeListener

public synchronized void addPropertyChangeListener(PropertyChangeListener listener)

Adds a listener to the PropertyChange event set.

 

applyUpdates

public void applyUpdates() throws DBException, SQLException

Apply 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.)

 

areDistinctTypesEnabled

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.

 

cancelRowUpdates

public void cancelRowUpdates() throws DBException, SQLException

Cancels 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 or updateRow has already been called, then this method has no effect.

 

cancelUpdates

public void cancelUpdates() throws DBException, SQLException

Cancel 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.

 

close

public void close() throws DBException, SQLException

Releases 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, explicitly do a commit or rollback before using the close method.

 

close

public void close(int resourceLevel) throws DBException, SQLException

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.

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, explicitly do a commit or rollback before using the close method.

 

deleteRow

public void deleteRow() throws DBException, SQLException

Deletes 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 and rowChanged_delete are triggered by this method. The events aboutToChangeRowSet_deleteRow and rowSetChanged_deleteRow are also triggered by this method.

 

execute

public synchronized void execute() throws DBException, SQLException

Executes 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.

 

execute

public synchronized void execute(int position) throws DBException, SQLException

Executes 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.

 

fetchMoreRows

public boolean fetchMoreRows() throws DBException, SQLException

Fetches 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.

 

fetchMoreRows

public synchronized boolean fetchMoreRows(int direction) throws DBException, SQLException

Fetches 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.

 

findColumn

public int findColumn(String columnName) throws DBException, SQLException

Maps the given column label to its column index. The index of the first column is 1.

 

first

public synchronized boolean first() throws DBException, SQLException

Applies 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 events aboutToChangeRowSet_fetchRow and rowSetChanged_fetchRow may be triggered by this method.

 

getCacheLimit

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.

 

getCacheRowCount

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.

 

getCacheValueAt

public Object getCacheValueAt(int rowIndex,
                              int columnIndex) throws DBException, SQLException

Returns 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.

 

getColumn

public Object getColumn(int columnNumber) throws DBException, SQLException

Returns 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.

 

getColumn

public Object getColumn(String columnName) throws DBException, SQLException

Returns 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.

 

getColumnAsString

public String getColumnAsString(int columnNumber) throws DBException, SQLException

Returns 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.

 

getColumnAsString

public String getColumnAsString(String columnName) throws DBException, SQLException

Returns 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.

 

getColumnCount

public int getColumnCount() throws SQLException

Returns 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.

 

getColumnName

public String getColumnName(int columnIndex) throws DBException, SQLException

Returns 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.

 

getFetchSize

public int getFetchSize() throws SQLException

Gets 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.

 

getMaxFieldSize

public int getMaxFieldSize() throws SQLException

The 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.

 

getMaxRows

public int getMaxRows() throws SQLException

The 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.

 

getMetaData

public DBSelectMetaData getMetaData() throws SQLException

Retrieves 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.

 

getRow

public int getRow() throws SQLException

Retrieves 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.

 

getRowCount

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.

 

getRowInCache

public int getRowInCache() throws SQLException

Returns 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.

 

getUpdateDeferral

public int getUpdateDeferral()

Gets the style of update deferral in effect.

See the setUpdateDeferral method for an explanation of the possible values returned.

 

hasMoreRows

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.

 

hasMoreRows

public boolean hasMoreRows(int direction) throws DBException, SQLException

Indicates 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.

 

isCompareLargeColumns

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.

 

isFirst

public boolean isFirst() throws SQLException

Indicates whether the first row of the result set is the current row.

For a DBProcedureCall bean, the method applies to the current result set.

 

isLast

public boolean isLast() throws SQLException

Indicates whether the last row of the result set is the current row.

For a DBProcedureCall bean, the method applies to the current result set.

 

isLockRows

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.

 

isOpen

public boolean isOpen() throws SQLException

Returns 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, the close 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.

 

isOpen

public boolean isOpen(int resourceLevel) throws DBException, SQLException

Returns 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.

 

isReadOnly

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.

 

isValidateLOBs

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.

 

last

public synchronized boolean last() throws DBException, SQLException

Applies 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 events aboutToChangeRowSet_fetchRow and rowSetChanged_fetchRow may be triggered by this method.

 

lockRow

public synchronized void lockRow() throws DBException, SQLException

Locks 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.

 

newRow

public void newRow(boolean beforeCurrent) throws DBException, SQLException

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. 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 the updateRow 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 events aboutToChangeRowSet_newRow and rowSetChanged_newRow are triggered by this method.

 

next

public synchronized boolean next() throws DBException, SQLException

Applies 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 events aboutToChangeRowSet_fetchRow and rowSetChanged_fetchRow may be triggered by this method.

 

onRow

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, but onRow() will tell you that you are not actually positioned to it.

For a DBProcedureCall bean, the method applies to the current result set.

 

previous

public synchronized boolean previous() throws DBException, SQLException

Applies 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 events aboutToChangeRowSet_fetchRow and rowSetChanged_fetchRow may be triggered by this method.

 

reExecute

public synchronized void reExecute() throws DBException, SQLException

Re-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.

 

refreshRow

public void refreshRow() throws DBException, SQLException

Refreshes 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 calling setColumn, but before calling updateRow, then the value changes made to the row are lost.

 

removeDBAfterListener

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.

 

removeDBBeforeListener

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.

 

removePropertyChangeListener

public synchronized void removePropertyChangeListener(PropertyChangeListener listener)

Removes a listener to the PropertyChange event set.

 

setCacheLimit

public synchronized void setCacheLimit(int rows) throws DBException, SQLException

Provides 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.

 

setCacheValueAt

public synchronized void setCacheValueAt(Object aValue,
                                         int rowIndex,
                                         int columnIndex) throws DBException, SQLException

Sets 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.

 

setColumn

public void setColumn(int columnNumber,
                      Object aValue) throws DBException, SQLException

Sets (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.

 

setColumn

public void setColumn(String columnName,
                      Object aValue) throws DBException, SQLException

Sets (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.

 

setColumnFromString

public void setColumnFromString(int columnNumber,
                                String stringValue) throws DBException, SQLException

Sets (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.

 

setColumnFromString

public void setColumnFromString(String columnName,
                                String stringValue) throws DBException, SQLException

Sets (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.

 

setCompareLargeColumns

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.

 

setDistinctTypesEnabled

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.

 

setFetchSize

public synchronized void setFetchSize(int rows) throws DBException, SQLException

Sets 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.

 

setLockRows

public void setLockRows(boolean lockRows) throws DBException, SQLException

If 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.

 

setMaxFieldSize

public void setMaxFieldSize(int max) throws DBException, SQLException

The 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.

 

setMaxRows

public void setMaxRows(int max) throws DBException, SQLException

The 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.

 

setReadOnly

public void setReadOnly(boolean value) throws SQLException

Set 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.

 

setRow

public synchronized boolean setRow(int rowNumber) throws DBException, SQLException

Applies 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 events aboutToChangeRowSet_fetchRow and rowSetChanged_fetchRow may be triggered by this method.

 

setRowInCache

public synchronized boolean setRowInCache(int rowNumber) throws DBException, SQLException

Makes 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.

 

setUpdateDeferral

public void setUpdateDeferral(int style) throws DBException, SQLException

Sets 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.

 

setValidateLOBs

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.

 

unlockRow

public void unlockRow() throws DBException, SQLException

Unlocks the current row. The database lock on the current row is released. If the current row is not locked, this has no effect.

 

updateRow

public void updateRow() throws DBException, SQLException

Updates 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 and rowChanged_update may be triggered by this method. The events aboutToChangeRow_insert and rowChanged_insert may be triggered by this method.

Class Hierarchy All Classes All Fields and Methods