|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.db.beans.DBStatement | +--com.ibm.db.beans.DBSelect
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 Summary | |
---|---|
static int |
DEFER_NOTHING
|
static int |
DEFER_WRITE_TO_DATABASE
|
static int |
DEFER_WRITE_TO_DATABASE_AND_ROW_NUMBER_CHANGE
|
static int |
FETCH_FORWARD
|
static int |
FETCH_REVERSE
|
Fields inherited from class com.ibm.db.beans.DBStatement |
---|
LEVEL_CONNECTION, LEVEL_RESULTSET, LEVEL_STATEMENT, TRANSACTION_DEFAULT |
Constructor Summary | |
---|---|
DBSelect()
Default constructor for a DBSelect bean. |
Method Summary | |
---|---|
void |
addDBAfterListener(com.ibm.db.beans.DBAfterListener listener)
Adds a listener to the DBAfter event set. |
void |
addDBBeforeListener(com.ibm.db.beans.DBBeforeListener listener)
Adds a listener to the DBBefore event set. |
void |
addPropertyChangeListener(java.beans.PropertyChangeListener listener)
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 resourceLevel)
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 position)
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 direction)
Fetches more rows from the database into the row cache. |
int |
findColumn(java.lang.String columnName)
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. |
java.lang.Object |
getCacheValueAt(int rowIndex,
int columnIndex)
Returns the value at rowIndex and columnIndex in the cache. |
java.lang.Object |
getColumn(int columnNumber)
Returns the value of the column at the specified index in the current row. |
java.lang.Object |
getColumn(java.lang.String columnName)
Returns the value of the column with the specified name in the current row. |
java.lang.String |
getColumnAsString(int columnNumber)
Returns the value of the column at the specified index in the current row as a String. |
java.lang.String |
getColumnAsString(java.lang.String columnName)
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. |
java.lang.String |
getColumnName(int columnIndex)
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. |
com.ibm.db.beans.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 |
getScrollType()
Returns the type of scrollable result set specified. |
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 direction)
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 resourceLevel)
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 beforeCurrent)
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(com.ibm.db.beans.DBAfterListener listener)
Removes a listener to the DBAfter event set. |
void |
removeDBBeforeListener(com.ibm.db.beans.DBBeforeListener listener)
Removes a listener to the DBBefore event set. |
void |
removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Removes a listener to the PropertyChange event set. |
void |
setCacheLimit(int rows)
Provides a hint for the maximum number of rows to be kept in an in-memory cache of result set rows. |
void |
setCacheValueAt(java.lang.Object aValue,
int rowIndex,
int columnIndex)
Sets the value of the column at columnIndex and rowIndex in the cache. |
void |
setColumn(int columnNumber,
java.lang.Object aValue)
Sets (in memory) the value of the column at the specified index in the current row. |
void |
setColumn(java.lang.String columnName,
java.lang.Object aValue)
Sets (in memory) the value of the column with the specified name in the current row. |
void |
setColumnFromString(int columnNumber,
java.lang.String stringValue)
Sets (in memory) the value of the column at the specified index in the current row. |
void |
setColumnFromString(java.lang.String columnName,
java.lang.String stringValue)
Sets (in memory) the value of the column with the specified name in the current row. |
void |
setCompareLargeColumns(boolean compare)
If true, large columns will be compared when locking the current row. |
void |
setDistinctTypesEnabled(boolean enabled)
If true, use of user-defined distinct types is enabled for this RowSet. |
void |
setFetchSize(int rows)
Sets the number of rows that should be fetched from the database when more rows are needed. |
void |
setLockRows(boolean lockRows)
If true, a database lock is automatically held on a row while it is the current row. |
void |
setMaxFieldSize(int max)
The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value. |
void |
setMaxRows(int max)
The maxRows limit is set to limit the number of rows that any RowSet can contain. |
void |
setReadOnly(boolean value)
Set the read-only property of the RowSet. |
boolean |
setRow(int rowNumber)
Applies any changes in the current row to the database, and then positions to the specified row in the result set. |
boolean |
setRowInCache(int rowNumber)
Makes the specified row in the cache the current row in the result set. |
void |
setScrollType(int scrollType)
The scrollType specifies the type of scrollable result set that should be obtained. |
void |
setUpdateDeferral(int style)
Sets the style of update deferral. |
void |
setValidateLOBs(boolean validateLOBs)
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. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final int FETCH_FORWARD
public static final int FETCH_REVERSE
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
Constructor Detail |
public DBSelect()
Method Detail |
public void addDBAfterListener(com.ibm.db.beans.DBAfterListener listener)
addDBAfterListener
in class DBStatement
listener
- DBAfterListenerDBAfterListener
,
removeDBAfterListener(com.ibm.db.beans.DBAfterListener)
public void addDBBeforeListener(com.ibm.db.beans.DBBeforeListener listener)
addDBBeforeListener
in class DBStatement
listener
- DBBeforeListenerDBBeforeListener
,
removeDBBeforeListener(com.ibm.db.beans.DBBeforeListener)
public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
addPropertyChangeListener
in class DBStatement
listener
- PropertyChangeListenerremovePropertyChangeListener(java.beans.PropertyChangeListener)
public void applyUpdates() throws DBException, java.sql.SQLException
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.)
DBException
- readOnly
- if the result set is read only
java.sql.SQLException
- - if a database access error occurredcancelUpdates()
,
setUpdateDeferral(int)
public boolean areDistinctTypesEnabled()
setDistinctTypesEnabled
method for a fuller
discussion of what it means for use of user-defined distinct types to be enabled.
setDistinctTypesEnabled(boolean)
public void cancelRowUpdates() throws DBException, java.sql.SQLException
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.
DBException
- notExecuted
- if associated statement has not been executed
DBException
- noResults
- if the result set is empty
DBException
- readOnly
- if the result set is read only
java.sql.SQLException
setColumn(int, java.lang.Object)
,
updateRow()
public void cancelUpdates() throws DBException, java.sql.SQLException
You will be positioned to the same row before and after cancelUpdates, except that its row number may be adjusted.
DBException
- readOnly
- if the result set is read only
java.sql.SQLException
applyUpdates()
,
setUpdateDeferral(int)
public void close() throws DBException, java.sql.SQLException
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.
close
in class DBStatement
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
java.sql.SQLException
- if a database access error occursclose(int)
,
isOpen(int)
public void close(int resourceLevel) throws DBException, java.sql.SQLException
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.
close
in class DBStatement
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.
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
java.sql.SQLException
- if a database access error occursclose()
,
isOpen(int)
public void deleteRow() throws DBException, java.sql.SQLException
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.
DBException
- notExecuted
- if associated statement has not been executed
DBException
- noActiveConnection
- if no active connection exists
DBException
- readOnly
- if the result set is read only
DBException
- noResults
- if the result set is empty
DBException
- rowChanged
- if the current row cannot be deleted because it cannot be found in the database
DBException
- rowNotFound
- if the lockRows property of the associated SelectStatement is true and
the new current row cannot be locked
DBException
- truncated
- if data truncation occurred on retrieval
java.sql.SQLException
- - if a database access error occurspublic void execute() throws DBException, java.sql.SQLException
execute
in class DBStatement
DBException
- badUidPwd
- if incorrect username or password specified
DBException
- noSQL
- if the SQL statement is null
DBException
- notSelect
- if SQL statement is not a SELECT statement
DBException
- noTransactions
- if database does not support transactions and autoCommit set to false
java.sql.SQLException
- - if a database access error occurredexecute(int)
,
reExecute()
public void execute(int position) throws DBException, java.sql.SQLException
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.
position
- row number that should be both the current row and the first
row in the cache after execution
DBException
- badUidPwd
- if incorrect username or password specified
DBException
- noSQL
- if the SQL statement is null
DBException
- notSelect
- if SQL statement is not a SELECT statement
DBException
- noTransactions
- if database does not support transactions and autoCommit set to false
java.sql.SQLException
- - if a database access error occurredexecute()
public boolean fetchMoreRows() throws DBException, java.sql.SQLException
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.
DBException
- notExecuted
- if the query has not been executed
DBException
- notOpen
- if the result set is not open
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
DBException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
java.sql.SQLException
- - if a database access error occurredfetchMoreRows(int)
,
hasMoreRows()
public boolean fetchMoreRows(int direction) throws DBException, java.sql.SQLException
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.
direction
- the direction in which to fetch; valid values are
FETCH_FORWARD and FETCH_REVERSE.
DBException
- notExecuted
- if the query has not been executed
DBException
- notOpen
- if the result set is not open
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
DBException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
java.sql.SQLException
- - if a database access error occurredfetchMoreRows()
,
hasMoreRows(int)
public int findColumn(java.lang.String columnName) throws DBException, java.sql.SQLException
columnName
- the label of the column
DBException
- columnNotDefined
- the column with the specified label is not defined
java.sql.SQLException
public boolean first() throws DBException, java.sql.SQLException
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.
DBException
- notExecuted
- if the query has not been executed
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
DBException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
java.sql.SQLException
- - if a database access error occuredsetRow(int)
public int getCacheLimit()
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.
setCacheLimit(int)
,
getFetchSize()
public int getCacheRowCount()
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.
getRowCount()
,
getColumnCount()
public java.lang.Object getCacheValueAt(int rowIndex, int columnIndex) throws DBException, java.sql.SQLException
For a DBProcedureCall bean, the value is from the current result set.
rowIndex
- the row number in the cachecolumnIndex
- the column number in the cache
DBException
- notExecuted
- if statement has not been executed
DBException
- noCurrentResult
- if the you are not positioned on a result set.
DBException
- noResults
- if the result set is empty
DBException
- cacheEmpty
- if there are no rows in the cache
DBException
- invalidRowNumber
- if requested row number is less than 1
DBException
- columnNotDefined
- if the column index is not defined
DBException
- indexTooLarge
- if the row index is too large
java.sql.SQLException
setCacheValueAt(java.lang.Object, int, int)
public java.lang.Object getColumn(int columnNumber) throws DBException, java.sql.SQLException
For a DBProcedureCall bean, the value is from the current row of the current result set.
columnNumber
- index of the column
DBException
- notExecuted
- if associated statement has not been executed
DBException
- noResults
- if the result set is empty
DBException
- columnNotDefined
- if the column index is not defined
java.sql.SQLException
setColumn(int, Object)
,
getColumn(String)
,
getColumnAsString(int)
,
getColumnAsString(String)
public java.lang.Object getColumn(java.lang.String columnName) throws DBException, java.sql.SQLException
For a DBProcedureCall bean, the value is from the current row of the current result set.
columnName
- name of the column
DBException
- notExecuted
- if associated statement has not been executed
DBException
- noResults
- if the result set is empty
DBException
- columnNotDefined
- if the column index is not defined
java.sql.SQLException
setColumn(String, Object)
,
getColumn(int)
,
getColumnAsString(int)
,
getColumnAsString(String)
public java.lang.String getColumnAsString(int columnNumber) throws DBException, java.sql.SQLException
For a DBProcedureCall bean, the value is from the current row of the current result set.
columnNumber
- index of the column
DBException
- notExecuted
- if associated statement has not been executed
DBException
- noResults
- if the result set is empty
DBException
- columnNotDefined
- if the column index is not defined
java.sql.SQLException
setColumnFromString(int, String)
,
getColumnAsString(String)
,
getColumn(int)
,
getColumn(String)
public java.lang.String getColumnAsString(java.lang.String columnName) throws DBException, java.sql.SQLException
For a DBProcedureCall bean, the value is from the current row of the current result set.
columnName
- name of the column
DBException
- notExecuted
- if associated statement has not been executed
DBException
- noResults
- if the result set is empty
DBException
- columnNotDefined
- if the column index is not defined
java.sql.SQLException
setColumnFromString(String, String)
,
getColumnAsString(int)
,
getColumn(int)
,
getColumn(String)
public int getColumnCount() throws java.sql.SQLException
For a DBProcedureCall bean, the method applies to the current result set.
java.sql.SQLException
getRowCount()
,
getCacheRowCount()
public java.lang.String getColumnName(int columnIndex) throws DBException, java.sql.SQLException
For a DBProcedureCall bean, the method applies to the current result set.
columnIndex
- the index of column
DBException
- columnNotDefined
- if column not defined in the meta data.
java.sql.SQLException
public int getFetchSize() throws java.sql.SQLException
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.
java.sql.SQLException
setFetchSize(int)
,
getCacheLimit()
public int getMaxFieldSize() throws java.sql.SQLException
java.sql.SQLException
- if a database-access error occurs.setMaxFieldSize(int)
public int getMaxRows() throws java.sql.SQLException
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.
java.sql.SQLException
- if a database-access error occurs.setMaxRows(int)
public com.ibm.db.beans.DBSelectMetaData getMetaData() throws java.sql.SQLException
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.
java.sql.SQLException
DBProcedureCall.getMetaData(int)
,
DBStatement.getParameterMetaData()
public int getRow() throws java.sql.SQLException
For a DBProcedureCall bean, the method applies to the current result set.
java.sql.SQLException
- if a database access error occurssetRow(int)
public int getRowCount()
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.
getCacheRowCount()
,
getColumnCount()
public int getRowInCache() throws java.sql.SQLException
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.
java.sql.SQLException
setRowInCache(int)
public int getUpdateDeferral()
See the setUpdateDeferral
method for an explanation of the
possible values returned.
setUpdateDeferral(int)
public boolean hasMoreRows()
For a DBProcedureCall bean, the method applies to the current result set.
fetchMoreRows()
public boolean hasMoreRows(int direction) throws DBException, java.sql.SQLException
For a DBProcedureCall bean, the method applies to the current result set.
direction
- valid values are FETCH_FORWARD and FETCH_REVERSE.
DBException
java.sql.SQLException
fetchMoreRows(int)
public boolean isCompareLargeColumns()
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.
setCompareLargeColumns(boolean)
public boolean isFirst() throws java.sql.SQLException
For a DBProcedureCall bean, the method applies to the current result set.
java.sql.SQLException
- if a database access error occursfirst()
public boolean isLast() throws java.sql.SQLException
For a DBProcedureCall bean, the method applies to the current result set.
java.sql.SQLException
- if a database access error occurslast()
public boolean isLockRows()
See the lockRow
method for a fuller
discussion of what it means for a row to be locked.
setLockRows(boolean)
,
lockRow()
public boolean isOpen() throws java.sql.SQLException
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
in class DBStatement
java.sql.SQLException
isOpen(int)
,
close()
public boolean isOpen(int resourceLevel) throws DBException, java.sql.SQLException
For a DBProcedureCall bean, if the resourceLevel is LEVEL_RESULTSET, the method applies to the current result set.
isOpen
in class DBStatement
resourceLevel
- A resource level: LEVEL_CONNECTION,
LEVEL_STATEMENT, or LEVEL_RESULTSET.
DBException
- invalidResourceLevel
- if the resource level is not valid
java.sql.SQLException
- if a database-access error occurs.isOpen()
,
close(int)
public boolean isReadOnly()
Attempts to update a read-only rowset will result in an exception being thrown. RowSets are updateable by default, if updates are possible.
setReadOnly(boolean)
public boolean isValidateLOBs()
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.
setValidateLOBs(boolean)
public boolean last() throws DBException, java.sql.SQLException
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.
java.sql.SQLException
- if a database access error occurs or the result set is
empty
DBException
- notExecuted
- if the query has not been executed
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
DBException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
java.sql.SQLException
- - if a database access error occuredsetRow(int)
public void lockRow() throws DBException, java.sql.SQLException
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.
DBException
- notExecuted
- if the query has not been executed
DBException
- noResults
- if the result set is empty
DBException
- noActiveConnection
- if no active connection exists
DBException
- readOnly
- if the result set is read only
DBException
- multipleRowsFound
- if the current row cannot be locked because it cannot be uniquely identified
in the database
DBException
- rowNotFound
- if the current row cannot be locked because it cannot be found in the database
DBException
- rowNotInDatabase
- if the current row cannot be locked in the database because it has not
yet been written to the database
DBException
- lockNotSupported
- if the current row cannot be locked because the database does not have
function required to do so
DBException
- truncated
- if data truncation occurred on retrieval
java.sql.SQLException
- - if a database access error occurredunlockRow()
,
setLockRows(boolean)
public void newRow(boolean beforeCurrent) throws DBException, java.sql.SQLException
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.
beforeCurrent
- true, add the new row before the current row;
false add the new row after the current row.
DBException
- notExecuted
- if associated statement has not been executed
DBException
- readOnly
- if the result set is read only
DBException
- maxSize
- if the maximum number of rows in the result set has been reached
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
java.sql.SQLException
- - if a database access error occurredpublic boolean next() throws DBException, java.sql.SQLException
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.
DBException
- notExecuted
- if the query has not been executed
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
DBException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
java.sql.SQLException
- - if a database access error occurredsetRow(int)
public boolean onRow()
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.
public boolean previous() throws DBException, java.sql.SQLException
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.
DBException
- notExecuted
- if the query has not been executed
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
DBException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
java.sql.SQLException
- - if a database access error occurredsetRow(int)
public void reExecute() throws DBException, java.sql.SQLException
execute
method.
reExecute
in class DBStatement
DBException
- noActiveConnection
- if no active connection exists
DBException
- notOpen
- if the statement is not open
java.sql.SQLException
- - if a database access error occurredexecute()
,
execute(int)
,
refreshRow()
public void refreshRow() throws DBException, java.sql.SQLException
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.
DBException
- notExecuted
- if associated statement has not been executed
DBException
- noResults
- if the result set is empty
DBException
- rowNotInDatabase
- if the current row cannot be refreshed because it has not
yet been written to the database
DBException
- truncated
- if data truncation occurred on retrieval
java.sql.SQLException
- - if a database access error occursreExecute()
public void removeDBAfterListener(com.ibm.db.beans.DBAfterListener listener)
removeDBAfterListener
in class DBStatement
listener
- DBAfterListenerDBAfterListener
,
addDBAfterListener(com.ibm.db.beans.DBAfterListener)
public void removeDBBeforeListener(com.ibm.db.beans.DBBeforeListener listener)
removeDBBeforeListener
in class DBStatement
listener
- DBBeforeListenerDBBeforeListener
,
addDBBeforeListener(com.ibm.db.beans.DBBeforeListener)
public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
removePropertyChangeListener
in class DBStatement
listener
- PropertyChangeListeneraddPropertyChangeListener(java.beans.PropertyChangeListener)
public void setCacheLimit(int rows) throws DBException, java.sql.SQLException
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.
rows
- the maximum number of rows to keep in the cache
DBException
- invalidRowNumber
- if the condition 0 <= rows is not satisfied
java.sql.SQLException
getCacheLimit()
,
setFetchSize(int)
public void setCacheValueAt(java.lang.Object aValue, int rowIndex, int columnIndex) throws DBException, java.sql.SQLException
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.
aValue
- the new valuerowIndex
- the row whose value is to be changedcolumnIndex
- the column whose value is to be changed
DBException
- notExecuted
- if statement has not been executed
DBException
- readOnly
- if the result set is read only
DBException
- noCurrentResult
- if the you are not positioned on a result set.
DBException
- noResults
- if the result set is empty
DBException
- cacheEmpty
- if there are no rows in the cache
DBException
- invalidRowNumber
- if requested row number is less than 1
DBException
- columnNotDefined
- if the column index is not defined
DBException
- indexTooLarge
- if the row index is too large
DBException
- wrongObjectType
- if the value does not match the object type of the column
DBException
- truncated
- if data truncation occurred on retrieval.
java.sql.SQLException
getCacheValueAt(int, int)
public void setColumn(int columnNumber, java.lang.Object aValue) throws DBException, java.sql.SQLException
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.
columnNumber
- index of the columnaValue
- value for the column
DBException
- notExecuted
- if statement has not been executed
DBException
- readOnly
- if the result set is read only
DBException
- noResults
- if the result set is empty
DBException
- columnNotDefined
- if the column index is not defined
DBException
- wrongObjectType
- if the value does not match the object type of the column
DBException
- truncated
- if data truncation occurred on retrieval.
java.sql.SQLException
getColumn(int)
,
setColumn(String, Object)
,
setColumnFromString(int, String)
,
setColumnFromString(String, String)
public void setColumn(java.lang.String columnName, java.lang.Object aValue) throws DBException, java.sql.SQLException
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.
columnName
- name of the columnaValue
- value for the column
DBException
- notExecuted
- if statement has not been executed
DBException
- readOnly
- if the result set is read only
DBException
- noResults
- if the result set is empty
DBException
- columnNotDefined
- if the column index is not defined
DBException
- wrongObjectType
- if the value does not match the object type of the column
DBException
- truncated
- if data truncation occurred on retrieval.
java.sql.SQLException
getColumn(String)
,
setColumn(int, Object)
,
setColumnFromString(int, String)
,
setColumnFromString(String, String)
public void setColumnFromString(int columnNumber, java.lang.String stringValue) throws DBException, java.sql.SQLException
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.
columnNumber
- index of the columnstringValue
- value for the column
DBException
- notExecuted
- if the statement has not been executed
DBException
- readOnly
- if the result set is read only
DBException
- noResults
- if the result set is empty
DBException
- columnNotDefined
- if the column index is not defined
DBException
- cannotConvert
- if cannot convert to object type of column
DBException
- truncated
- if data truncation occurred on retrieval.
java.sql.SQLException
getColumnAsString(int)
,
setColumnFromString(String, String)
,
setColumn(int, Object)
,
setColumn(String, Object)
public void setColumnFromString(java.lang.String columnName, java.lang.String stringValue) throws DBException, java.sql.SQLException
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.
columnName
- name of the columnstringValue
- value for the column
DBException
- notExecuted
- if the statement has not been executed
DBException
- readOnly
- if the result set is read only
DBException
- noResults
- if the result set is empty
DBException
- columnNotDefined
- if the column index is not defined
DBException
- cannotConvert
- if cannot convert to object type of column
DBException
- truncated
- if data truncation occurred on retrieval.
java.sql.SQLException
getColumnAsString(String)
,
setColumnFromString(int, String)
,
setColumn(int, Object)
,
setColumn(String, Object)
public void setCompareLargeColumns(boolean compare)
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.
compare
- true compare large columns when obtaining
row lock; false do not compare large columns.isCompareLargeColumns()
public void setDistinctTypesEnabled(boolean enabled)
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.
enabled
- true if use of user-defined distinct types should be enabled;
false if it should not be enabled.areDistinctTypesEnabled()
public void setFetchSize(int rows) throws DBException, java.sql.SQLException
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.
rows
- the number of rows to fetch
DBException
- invalidRowNumber
- if the condition 0 <= rows <= this.getMaxRows() is not satisfied
java.sql.SQLException
- - if a database access error occurredgetFetchSize()
,
setCacheLimit(int)
public void setLockRows(boolean lockRows) throws DBException, java.sql.SQLException
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.
lockRows
- true, hold database lock while a row is the current row;
false hold database lock only while a row is being updated.
DBException
- noDeferralWithAutomaticLocking
- if updates are being deferred
java.sql.SQLException
isLockRows()
,
lockRow()
public void setMaxFieldSize(int max) throws DBException, java.sql.SQLException
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.
max
- the new max column size limit; zero means unlimited
java.sql.SQLException
- if a database-access error occurs.
DBException
getMaxFieldSize()
public void setMaxRows(int max) throws DBException, java.sql.SQLException
max
- the new max rows limit; zero means unlimited
java.sql.SQLException
- if a database-access error occurs.
DBException
getMaxRows()
public void setReadOnly(boolean value) throws java.sql.SQLException
Attempts to update a read-only rowset will result in an exception being thrown. RowSets are updateable by default, if updates are possible.
value
- true if read-only, false otherwise
java.sql.SQLException
- if a database-access error occurs.
java.sql.SQLException
- if a database-access error occurs.isReadOnly()
public boolean setRow(int rowNumber) throws DBException, java.sql.SQLException
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.
rowNumber
- index in the result set of the row; the index of the first row
is 1
DBException
- invalidRowNumber
- if requested row number is less than 1
DBException
- notExecuted
- if associated statement has not been executed
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
DBException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
java.sql.SQLException
- - if a database access error occurred
getRow()
,
first()
,
next()
,
previous()
,
last()
public boolean setRowInCache(int rowNumber) throws DBException, java.sql.SQLException
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.
DBException
- invalidRowNumber
- if requested row number is less than 1
DBException
- notExecuted
- if statement has not been executed
DBException
- rowChanged
- if the current row cannot be updated in the database because it has been
modified by another user since it was fetched
DBException
- rowNotFound
- if the lockRows property true and the new current row cannot be locked
java.sql.SQLException
- - if a database access error occurredsetRow(int)
,
getRowInCache()
public void setUpdateDeferral(int style) throws DBException, java.sql.SQLException
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.
style
- the style of update deferral requested.
DBException
- noDeferralWithAutomaticLocking
- if the lockRows property has been set
DBException
- noDeferralWithLockedRow
- if the current row is locked in the database
DBException
- mustApplyRowValueChanges
- if values in the current row have been changed
DBException
- mustApplyDeferredUpdates
- if there are pending deferred updates
java.sql.SQLException
getUpdateDeferral()
public void setValidateLOBs(boolean validateLOBs)
isValidateLOBs()
public void unlockRow() throws DBException, java.sql.SQLException
DBException
- notExecuted
- if the query has not been executed
DBException
- noResults
- if the result set is empty
DBException
- noActiveConnection
- if no active connection exists
DBException
- readOnly
- if the result set is read only
DBException
- sqlException
- if an SQLException occurred
java.sql.SQLException
lockRow()
public void updateRow() throws DBException, java.sql.SQLException
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.
DBException
- notExecuted
- if associated statement has not been executed
DBException
- noResults
- if the result set is empty
DBException
- noActiveConnection
- if no active connection exists
DBException
- readOnly
- if the result set is read only
DBException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
java.sql.SQLException
- - if a database access error occurredpublic void setScrollType(int scrollType) throws DBException
isReadOnly()
returns true), then a
scrollable result set is obtained. The type of scrollable result set obtained,
is determined by the value of scrollType. Allowable values are
ResultSet.TYPE_SCROLL_INSENSITIVE and ResultSet.TYPE_SCROLL_SENSITIVE.
The default is ResultSet.TYPE_SCROLL_INSENSITIVE.
scrollType
- the type of scrollable result set to obtain.
DBException
- invalidScrollType
- if an invalid value is specified.getScrollType()
public int getScrollType()
setScrollType(int)
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |