Class com.ibm.db.SelectResult
java.lang.Object
|
+----com.ibm.db.StatementResult
|
+----com.ibm.db.SelectResult
- public class SelectResult
- extends StatementResult
SelectResult represents a result set returned from executing an SQL Select statement.
- See Also:
- SelectStatement
Constructor Index
- SelectResult()
- Constructs a new SelectResult.
- SelectResult(SelectStatement)
- Constructs a new SelectResult and associates it with the specified
SelectStatement.
Method Index
- addPropertyChangeListener(PropertyChangeListener)
- Adds a listener to the PropertyChange event set.
- addStatementResultValueChangeListener(StatementResultValueChangeListener)
- Adds a listener to the StatementResultValueChange event set.
- cancelAction()
- Cancels execution of the SQL statement performing the current action.
- close()
- Applies any changes in the current row to the database, and then
closes the associated statement.
- closeResult()
- Applies any changes in the current row to the database, and then
closes the result set.
- columnNames()
- Returns the names of the columns of the result set.
- deleteRow()
- Deletes the current row from the result set and from the database.
- firstRow()
- Applies any changes in the current row to the database, and then positions to the
first row in the result set.
- getCacheValueAt(int, int)
- Returns the value at the specified row and column index in the cache.
- getColumnCount()
- Returns the number of columns in the result set.
- getColumnName(int)
- Returns the name of the column at the specified index.
- getColumnValue(int)
- Returns the value of the column at the specified index in the current row.
- getColumnValue(String)
- Returns the value of the column with the specified name in the current row.
- getColumnValueToString(int)
- Returns the value of the column at the specified index in the current row as a
String.
- getColumnValueToString(String)
- Returns the value of the column with the specified name in the current row as a
String.
- getCurrentRow()
- Returns the index in the result set of the current row.
- getCurrentRowInCache()
- Returns the index in the cache of the current row.
- getNumPacketsInCache()
- Returns the number of packets currently in the cache.
- getNumRowsInCache()
- Returns the number of rows currently in the cache.
- isEnd()
- Returns true if the currentRow is the last row in the result set and no
more rows can be fetched.
- isMaxRowsReached()
- Returns true if the number of rows in the result set is equal to the
maximum size of the result set.
- isRowLocked()
- Returns true if the current row is locked in the database.
- lastRow()
- Applies any changes in the current row to the database, and then positions to the
last row in the result set.
- lockRow()
- Locks the current row in the database.
- 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.
- nextPacket()
- Fetches the next packet from the database into the result set.
- nextRow()
- Applies any changes in the current row to the database, and then positions to the
next row in the result set.
- previousRow()
- Applies any changes in the current row to the database, and then positions to
the previous row in the result set.
- removePropertyChangeListener(PropertyChangeListener)
- Removes a listener from the PropertyChange event set.
- removeStatementResultValueChangeListener(StatementResultValueChangeListener)
- Removes a listener from the StatementResultValueChange event set.
- restoreRow()
- Restores a row's column values to those last known to be in the database.
- setColumnValue(int, Object)
- Sets (in the result set) the value of the column at the specified index in the
current row.
- setColumnValue(String, Object)
- Sets (in the result set) the value of the column with the specified name in the
current row.
- setColumnValueFromString(int, String)
- Sets (in the result set) the value of the column at the specified index in the
current row.
- setColumnValueFromString(String, String)
- Sets (in the result set) the value of the column with the specified name in the
current row.
- setCurrentRow(int)
- Applies any changes in the current row to the database, and then positions to
the specified row in the result set.
- setStatement(SelectStatement)
- Associates a SelectStatement with this SelectResult.
- unlockRow()
- Unlocks the current row.
- updateRow()
- Updates the database with the values of the current row in the result set.
Constructors
SelectResult
public SelectResult()
- Constructs a new SelectResult. A SelectResult must always be associated
with a SelectStatement. If you use this constructor, you must invoke
setStatement
to associate a SelectStatement with this SelectResult.
SelectResult
public SelectResult(SelectStatement aStatement)
- Constructs a new SelectResult and associates it with the specified
SelectStatement. Associates the StatementMetaData for the current
Result in the specified SelectStatement with this SelectResult.
- Parameters:
- aStatement - the associated SelectStatement
Methods
addPropertyChangeListener
public synchronized void addPropertyChangeListener(PropertyChangeListener listener)
- Adds a listener to the PropertyChange event set. PropertyChange events occur
when the bound properties, currentRow and currentRowInCache are changed.
- Parameters:
- listener - PropertyChangeListener
- See Also:
- removePropertyChangeListener
addStatementResultValueChangeListener
public void addStatementResultValueChangeListener(StatementResultValueChangeListener listener)
- Adds a listener to the StatementResultValueChange event set.
StatementResultValueChange events occur when the column values in the result set
are changed.
- Parameters:
- listener - StatementResultValueChangeListener
- See Also:
- StatementResultValueChangeListener
- removeStatementResultValueChangeListener
cancelAction
public void cancelAction() throws DataException
- Cancels execution of the SQL statement performing the current action.
In order to use this method, it must be invoked from a thread different
from the one in which the SQL statement is running.
The SQL statement could be an insert, update, or delete executing as part
of processing for updateRow() or deleteRow(), or it could be a select
executing to get a database lock on a row.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- notExecuting
- if no action is currently being executed
- Throws: DataException
- sqlException
- if an SQLException occurred
close
public synchronized void close() throws DataException
- Applies any changes in the current row to the database, and then
closes the associated statement. JDBC resources associated with the statement are
released. After the statement is closed, no more rows can be fetched into
the result set, but you can still use the SelectResult to update the database,
and you can re-execute the statement.
Even if you do not explicitly call close()
or closeResult()
,
JDBC resources are automatically freed when your SelectResult is garbage collected,
However, changes to the current row are not automatically applied in that case.
The events aboutToClose
and closed
are
triggered by this method.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- closeResult
closeResult
public synchronized void closeResult() throws DataException
- Applies any changes in the current row to the database, and then
closes the result set. JDBC resources associated with the result set are
released. After the result set is closed, no more rows can be fetched into
it, but you can still use the SelectResult to update the database.
This method is automatically called if you call the close()
method of
SelectResult or SelectStatement.
Even if you do not explicitly call close()
or closeResult()
,
JDBC resources are automatically freed when your SelectResult is garbage collected,
However, changes to the current row are not automatically applied in that case.
The events aboutToClose
and closed
are
triggered by this method.
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- sqlException
- if an SQLException occurred
- Overrides:
- closeResult in class StatementResult
- See Also:
- close
columnNames
public Enumeration columnNames() throws DataException
- Returns the names of the columns of the result set. This method invokes the
StatementMetaData.getColumnNames
to obtain the returned value.
- Returns:
- enumeration containing column names
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Overrides:
- columnNames in class StatementResult
deleteRow
public synchronized void deleteRow() throws DataException
- Deletes the current row from the result set and from the database. (If the current row
is a new one that has not yet been inserted into the database, it is just removed from
the result set.)
When you delete any row except the last in the result set, you are positioned to the
next row, and the index returned by the
getCurrentRow
method does not change.
When you delete the last row, you are positioned to the previous row,
and the index returned by the getCurrentRow
method decreases by 1.
If the current row should be locked ( isLockRows
of the associated
SelectStatement returns true), the new current row is locked in the database.
We generate and execute the SQL necessary to delete the current row from the database.
To insure that your delete 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. Also make sure to use the addTable()
method of the associated
StatementMetaData object to identify the table from which the row is to be deleted.
Otherwise we will attempt to parse your query for this information, with no guarantee
of success.
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, no exception is thrown. The number of
rows deleted depends on whether we perform a positioned or searched delete.
Whenever possible, we perform a positioned delete, which deletes the first matching
row. Otherwise, we perform a searched delete, which deletes 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 more information on when we perform positioned or searched deletes, see the
setForceSearchedUpdate()
method of SelectStatement.
The events aboutToDeleteRow
, deletedRow
, and
propertyChange
(for the currentRow and the currentRowInCache properties)
are triggered by this method.
The event cacheRowsChanged
may also be triggered.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be deleted because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property of the associated SelectStatement is true and
the new current row cannot be locked
- Throws: DataException
- sqlException
- if an SQLException occurred
- Overrides:
- deleteRow in class StatementResult
- See Also:
- setForceSearchedUpdate
firstRow
public void firstRow() throws DataException
- Applies any changes in the current row to the database, and then positions to the
first row in the result set.
If the first row in the result set has been displaced from the cache, you are
positioned to the first row still in the cache, and an exception is thrown to
indicate that the request could not be satisfied.
If the current row should be locked ( isLockRows
of the associated
SelectStatement returns true), the new current row is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache.
The event cacheRowsChanged
may be triggered by this method.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property of the associated SelectStatement is true and
the new current row cannot be locked
- Throws: DataException
- beforeCacheStart
- if the requested row is before the start of the cache
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentRow
getCacheValueAt
public Object getCacheValueAt(int rowNumber,
int columnNumber) throws DataException
- Returns the value at the specified row and column index in the cache.
The index of the first row is 1 and the index of the first column is 1. This
method allows you to access a value in the cache that is not in the current row.
- Parameters:
- rowNumber - index of the row in cache
- columnNumber - index of the column in cache
- Returns:
- value of the cell
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- beforeCacheStart
- if the requested row is before the start of the cache
- Throws: DataException
- indexTooLarge
- if the requested row is after the end of the cache
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- See Also:
- setColumnValue
getColumnCount
public int getColumnCount() throws DataException
- Returns the number of columns in the result set. This method invokes
StatementMetaData.getColumnCount
to obtain returned value.
- Returns:
- number of columns in the result set
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Overrides:
- getColumnCount in class StatementResult
getColumnName
public String getColumnName(int columnNumber) throws DataException
- Returns the name of the column at the specified index. This method invokes
StatementMetaData.getColumnName
to obtain the returned value.
The index of the first column is 1.
- Parameters:
- columnNumber - index of the column
- Returns:
- name of the column
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- Overrides:
- getColumnName in class StatementResult
getColumnValue
public Object getColumnValue(int columnNumber) throws DataException
- Returns the value of the column at the specified index in the current row.
If the column value is null, a null is returned.
The index of the first column is 1.
- Parameters:
- columnNumber - index of the column
- Returns:
- value of the column
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- Overrides:
- getColumnValue in class StatementResult
- See Also:
- getColumnValueToString
- setColumnValue
getColumnValue
public Object getColumnValue(String columnName) throws DataException
- Returns the value of the column with the specified name in the current row.
If the column value is null, a null is returned.
- Parameters:
- columnName - name of the column
- Returns:
- value of the column
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column name is not defined
- Overrides:
- getColumnValue in class StatementResult
- See Also:
- getColumnValueToString
- setColumnValue
getColumnValueToString
public String getColumnValueToString(int columnNumber) throws DataException
- 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.
- Parameters:
- columnNumber - index of the column
- Returns:
- value of the column as a String.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- Overrides:
- getColumnValueToString in class StatementResult
- See Also:
- getColumnValue
- setColumnValueFromString
getColumnValueToString
public String getColumnValueToString(String columnName) throws DataException
- 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.
- Parameters:
- columnName - name of the column
- Returns:
- value of the column as a String.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column name is not defined
- Overrides:
- getColumnValueToString in class StatementResult
- See Also:
- getColumnValue
- setColumnValueFromString
getCurrentRow
public int getCurrentRow()
- Returns the index in the result set of the current row.
Returns 0 if there is no current row.
The index of the first row is 1.
Most methods on SelectResult operate on the current row.
- Returns:
- index of the current row
- See Also:
- setCurrentRow
getCurrentRowInCache
public int getCurrentRowInCache()
- Returns the index in the cache of the current row.
Returns 0 if there is no current row.
The index of the first row in the cache is 1.
The value of currentRowInCache and currentRow will be the same unless you have
set maximumPacketsInCache to a value other than 0 and a packet has been displaced
from the cache.
For example, if a packet of 10 rows has been displaced from the cache and the
currentRow is 11, the currentRowInCache would be 1.
- Returns:
- index in the cache of the current row
getNumPacketsInCache
public int getNumPacketsInCache()
- Returns the number of packets currently in the cache.
- Returns:
- the number of packets in the cache
getNumRowsInCache
public int getNumRowsInCache()
- Returns the number of rows currently in the cache.
- Returns:
- the number of rows in cache
isEnd
public boolean isEnd()
- Returns true if the currentRow is the last row in the result set and no
more rows can be fetched. No more rows can be fetched if any of the following
conditions is true: all rows have been fetched from the database, the maxRows
limit has been reached, or the result set has been closed.
- Returns:
- true if the currentRow is the last row in the result set and no
more rows can be fetched
- See Also:
- isOpen
- isMaxRowsReached
isMaxRowsReached
public boolean isMaxRowsReached() throws DataException
- Returns true if the number of rows in the result set is equal to the
maximum size of the result set.
- Returns:
- true if the number of rows in the result set is equal to the
maximum size of the result set, otherwise false.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- See Also:
- setMaximumRows
isRowLocked
public boolean isRowLocked()
- Returns true if the current row is locked in the database.
- Returns:
- true if the current row is locked in the database
- See Also:
- lockRow
- unlockRow
lastRow
public synchronized void lastRow() throws DataException
- Applies any changes in the current row to the database, and then positions to the
last row in the result set. If more rows can be fetched from the database they
are fetched before positioning to the last row. For a discussion of when more
rows can be fetched, see the
isEnd
method.
If the current row should be locked ( isLockRows
of the associated
SelectStatement returns true), the new current row is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache.
The event cacheRowsChanged
may be triggered by this method.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property of the associated SelectStatement is true and
the new current row cannot be locked
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentRow
lockRow
public synchronized void lockRow() throws DataException
- 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, no exception is thrown.
All matching rows are locked.
To insure that only the intended row is locked, make sure that
the query used to produce the result set includes columns that uniquely identify
a row. Also make sure to use the addTable()
method of the associated
StatementMetaData object to identify the table in which the row is to be locked.
Otherwise we will attempt to parse your query for this information, with no guarantee
of success.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- rowNotFound
- if the current row cannot be locked because it cannot be found in the database
- Throws: DataException
- rowNotInDatabase
- if the current row cannot be locked in the database because it has not
yet been written to the database
- Throws: DataException
- lockNotSupported
- if the current row cannot be locked because the database does not have
function required to do so
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- unlockRow
- setLockRows
newRow
public synchronized void newRow(boolean beforeCurrent) throws DataException
- 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.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache.
The events aboutToAddNewRow
, addedNewRow
, and
cacheRowsChanged
are triggered by this method.
- Parameters:
- beforeCurrent - true, insert the new row before the current row;
false insert the new row after the current row.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- maxSize
- if the maximum number of rows in the result set has been reached
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
nextPacket
public synchronized void nextPacket() throws DataException
- Fetches the next packet from the database into the result set. If this causes
the current row to be displaced from the cache any changes in the current row
are first applied to the database, and then you are positioned to the first row
in the cache.
The event cacheRowsChanged
is triggered by this method.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- notOpen
- if the result set is not open
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property of the associated SelectStatement is true and
the new current row cannot be locked
- Throws: DataException
- sqlException
- if an SQLException occurred
nextRow
public void nextRow() throws DataException
- Applies any changes in the current row to the database, and then positions to the
next row in the result set.
If the next row has not already been fetched from the database, it is fetched, along
with any other rows in the next packet. If no more rows can be fetched, your
position does not change, and no exception is thrown.
Thus, if 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 the current row should be locked ( isLockRows
of the associated
SelectStatement returns true), the new current row is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache.
The event cacheRowsChanged
may be triggered by this method.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property of the associated SelectStatement is true and
the new current row cannot be locked
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentRow
previousRow
public void previousRow() throws DataException
- Applies any changes in the current row to the database, and then positions to
the previous row in the result set.
If you are already on the first row, your position does not change, and no exception
is thrown. Thus, if you are at the beginning of the result set, repeatedly invoking
this method has no effect.
If the previous row has been displaced from the cache, your position does not change,
and an exception is thrown to indicate that the request could not be satisfied.
If the current row should be locked ( isLockRows
of the associated
SelectStatement returns true), the new current row is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property of the associated SelectStatement is true and
the new current row cannot be locked
- Throws: DataException
- beforeCacheStart
- if the requested row is before the start of the cache
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentRow
removePropertyChangeListener
public synchronized void removePropertyChangeListener(PropertyChangeListener listener)
- Removes a listener from the PropertyChange event set. PropertyChange events occur
when the bound properties, currentRow and currentRowInCache are changed.
- Parameters:
- listener - PropertyChangeListener
- See Also:
- addPropertyChangeListener
removeStatementResultValueChangeListener
public void removeStatementResultValueChangeListener(StatementResultValueChangeListener listener)
- Removes a listener from the StatementResultValueChange event set.
StatementResultValueChange events occur when the column values in the result set
are changed.
- Parameters:
- listener - StatementResultValueChangeListener
- See Also:
- StatementResultValueChangeListener
- addStatementResultValueChangeListener
restoreRow
public void restoreRow() throws DataException
- Restores a row's column values to those last known to be in the database.
Use this method when an attempt to lock a row, insert or update a row in the database,
or delete a row from the database has failed. This can occur implicitly when
you try to move to another row. When one of these failures has occurred,
you cannot move to another row until you either correct the problem or
use this method.
If the current row was added via the newRow
method, and you
have not yet inserted it into the database, its column values are reset
to nulls. Otherwise, the current row's column values are reset
to the values originally fetched from the database or the values to
which it was last successfully updated.
If you believe the failure that occurred is correctable by changing one
or more of column values, as for example if the failure was due to
a duplicate key value in the database, you can just change the values
and try the operation again instead of using this method.
The events aboutToSetColumnValue
and columnValueSet
are
triggered by this method.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- readOnly
- if the result set is read only
- Overrides:
- restoreRow in class StatementResult
setColumnValue
public synchronized void setColumnValue(int columnNumber,
Object aValue) throws DataException
- Sets (in the result set) 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 result set.
The events aboutToSetColumnValue
and columnValueSet
are
triggered by this method.
- Parameters:
- columnNumber - index of the column
- aValue - value for the column
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- Throws: DataException
- wrongObjectType
- if the value does not match the object type of the column
- Throws: DataException
- truncated
- if data truncation occurred on retrieval.
- Overrides:
- setColumnValue in class StatementResult
- See Also:
- setColumnValueFromString
- getColumnValue
setColumnValue
public void setColumnValue(String columnName,
Object aValue) throws DataException
- Sets (in the result set) 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 result set.
The events aboutToSetColumnValue
and columnValueSet
are
triggered by this method.
- Parameters:
- columnName - name of the column
- aValue - value for the column
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column name is not defined
- Throws: DataException
- wrongObjectType
- if the value does not match the object type of the column
- Throws: DataException
- truncated
- if data truncation occurred on retrieval.
- Overrides:
- setColumnValue in class StatementResult
- See Also:
- setColumnValueFromString
- getColumnValue
setColumnValueFromString
public void setColumnValueFromString(int columnNumber,
String stringValue) throws DataException
- Sets (in the result set) the value of the column at the specified index in the
current row. The index of the first column is 1.
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 result set.
The events aboutToSetColumnValue
and columnValueSet
are
triggered by this method.
- Parameters:
- columnNumber - index of the column
- stringValue - value for the column
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- Throws: DataException
- cannotConvert
- if cannot convert to object type of column
- Throws: DataException
- truncated
- if data truncation occurred on retrieval.
- Overrides:
- setColumnValueFromString in class StatementResult
- See Also:
- setColumnValue
- getColumnValueToString
setColumnValueFromString
public void setColumnValueFromString(String columnName,
String stringValue) throws DataException
- Sets (in the result set) the value of the column with the specified name in the
current row. The index of the first column is 1.
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 result set.
The events aboutToSetColumnValue
and columnValueSet
are
triggered by this method.
- Parameters:
- columnName - name of the column
- stringValue - value for the column
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column name is not defined
- Throws: DataException
- cannotConvert
- if cannot convert to object type of column
- Throws: DataException
- truncated
- if data truncation occurred on retrieval.
- Overrides:
- setColumnValueFromString in class StatementResult
- See Also:
- setColumnValue
- getColumnValueToString
setCurrentRow
public synchronized void setCurrentRow(int rowNumber) throws DataException
- 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 has not yet been fetched, packets are fetched until the
specified row is in the cache or no more rows can be fetched.
If no more rows can be fetched, and the specified row was not reached, you are
positioned to the last row, and an exception is thrown to indicate
that the request could not be satisfied. For a discussion of when no more
rows can be fetched, see the isEnd
method.
If the specified row has been displaced from the cache, you are positioned to
the first row in the cache, and an exception is thrown to indicate
that the request could not be satisfied.
If the current row should be locked ( isLockRows
of the associated
SelectStatement returns true), the new current row is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache.
The event cacheRowsChanged
may be triggered by this method.
- Parameters:
- rowNumber - index in the result set of the row
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property of the associated SelectStatement is true and
the new current row cannot be locked
- Throws: DataException
- beforeCacheStart
- if the requested row is before the start of the cache
- Throws: DataException
- indexTooLarge
- if the requested row is after the end of the result set
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- getCurrentRow
setStatement
public void setStatement(SelectStatement aStatement)
- Associates a SelectStatement with this SelectResult. Associates the
StatementMetaData for the current result set in the specified SelectStatement
with this SelectResult.
- Parameters:
- aStatement - the associated SelectStatement
unlockRow
public void unlockRow() throws DataException
- Unlocks the current row. The database lock on the current row is released.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- lockRow
updateRow
public synchronized void updateRow() throws DataException
- 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.
We generate and execute 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. Also make sure to use the addTable()
method of the associated
StatementMetaData object to identify the table in which the row is to be updated.
Otherwise we will attempt to parse your query for this information, with no guarantee
of success.
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, no exception is thrown. The number of
rows updated depends on whether we perform a positioned or searched update.
Whenever possible, we perform a positioned update, which updates the first matching
row. Otherwise, we perform 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 more information on when we perform positioned or searched updates, see the
setForceSearchedUpdate
method of SelectStatement.
The events aboutToUpdateRow
and updatedRow
are
triggered by this method.
- Throws: DataException
- noStatement
- if no SelectStatement associated with this SelectResult
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- sqlException
- if an SQLException occurred
- Overrides:
- updateRow in class StatementResult
- See Also:
- setForceSearchedUpdate
