Where Am I? Class Hierarchy All Classes All Fields and Methods

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

Where Am I? Class Hierarchy All Classes All Fields and Methods