com.ibm.db
Class 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, Serialized Form

Constructor Summary
SelectResult()
          Constructs a new SelectResult.
SelectResult(SelectStatement aStatement)
          Constructs a new SelectResult and associates it with the specified SelectStatement.
 
Method Summary
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a listener to the PropertyChange event set.
 void addStatementResultValueChangeListener(StatementResultValueChangeListener listener)
          Adds a listener to the StatementResultValueChange event set.
 void cancelAction()
          Cancels execution of the SQL statement performing the current action.
 void close()
          Applies any changes in the current row to the database, and then closes the associated statement.
 void closeResult()
          Applies any changes in the current row to the database, and then closes the result set.
 java.util.Enumeration columnNames()
          Returns the names of the columns of the result set.
 void deleteRow()
          Deletes the current row from the result set and from the database.
 void firstRow()
          Applies any changes in the current row to the database, and then positions to the first row in the result set.
 java.lang.Object getCacheValueAt(int rowNumber, int columnNumber)
          Returns the value at the specified row and column index in the cache.
 int getColumnCount()
          Returns the number of columns in the result set.
 java.lang.String getColumnName(int columnNumber)
          Returns the name of the column at the specified index.
 java.lang.Object getColumnValue(int columnNumber)
          Returns the value of the column at the specified index in the current row.
 java.lang.Object getColumnValue(java.lang.String columnName)
          Returns the value of the column with the specified name in the current row.
 java.lang.String getColumnValueToString(int columnNumber)
          Returns the value of the column at the specified index in the current row as a String.
 java.lang.String getColumnValueToString(java.lang.String columnName)
          Returns the value of the column with the specified name in the current row as a String.
 int getCurrentRow()
          Returns the index in the result set of the current row.
 int getCurrentRowInCache()
          Returns the index in the cache of the current row.
 int getNumPacketsInCache()
          Returns the number of packets currently in the cache.
 int getNumRowsInCache()
          Returns the number of rows currently in the cache.
 boolean isEnd()
          Returns true if the currentRow is the last row in the result set and no more rows can be fetched.
 boolean isMaxRowsReached()
          Returns true if the number of rows in the result set is equal to the maximum size of the result set.
 boolean isRowLocked()
          Returns true if the current row is locked in the database.
 void lastRow()
          Applies any changes in the current row to the database, and then positions 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.
 void nextPacket()
          Fetches the next packet from the database into the result set.
 void nextRow()
          Applies any changes in the current row to the database, and then positions to the next row in the result set.
 void previousRow()
          Applies any changes in the current row to the database, and then positions to the previous row in the result set.
 void refreshColumn(int columnNumber)
          Refreshes the specified column value in the current row from the database.
 void refreshRow()
          Refreshes a row's column values with those currently in the database.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes a listener from the PropertyChange event set.
 void removeStatementResultValueChangeListener(StatementResultValueChangeListener listener)
          Removes a listener from the StatementResultValueChange event set.
 void restoreRow()
          Restores a row's column values to those last known to be in the database.
 void setColumnValue(int columnNumber, java.lang.Object aValue)
          Sets (in the result set) the value of the column at the specified index in the current row.
 void setColumnValue(java.lang.String columnName, java.lang.Object aValue)
          Sets (in the result set) the value of the column with the specified name in the current row.
 void setColumnValueFromString(int columnNumber, java.lang.String stringValue)
          Sets (in the result set) the value of the column at the specified index in the current row.
 void setColumnValueFromString(java.lang.String columnName, java.lang.String stringValue)
          Sets (in the result set) the value of the column with the specified name in the current row.
 void setCurrentRow(int rowNumber)
          Applies any changes in the current row to the database, and then positions to the specified row in the result set.
 void setStatement(SelectStatement aStatement)
          Associates a SelectStatement with this SelectResult.
 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 com.ibm.db.StatementResult
addStatementResultAfterListener, addStatementResultBeforeListener, getJDBCMetaData, getNumRows, isOpen, removeStatementResultAfterListener, removeStatementResultBeforeListener
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

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
Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.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(java.beans.PropertyChangeListener)

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(com.ibm.db.StatementResultValueChangeListener)

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
DataException - noActiveConnection - if no active connection exists
DataException - notExecuting - if no action is currently being executed
DataException - sqlException - if an SQLException occurred

close

public 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
DataException - noActiveConnection - if no active connection exists
DataException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DataException - sqlException - if an SQLException occurred

See Also:
closeResult()

closeResult

public 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
DataException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DataException - sqlException - if an SQLException occurred

Overrides:
closeResult in class StatementResult
See Also:
close()

columnNames

public java.util.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 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.

The bean generates and executes 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 the bean 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 the bean performs a positioned or searched delete. Whenever possible, the bean performs 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 the bean 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
DataException - notExecuted - if associated statement has not been executed
DataException - noActiveConnection - if no active connection exists
DataException - readOnly - if the result set is read only
DataException - noResults - if the result set is empty
DataException - rowChanged - if the current row cannot be deleted because it cannot be found in the database
DataException - rowNotFound - if the lockRows property of the associated SelectStatement is true and the new current row cannot be locked
DataException - truncated - if data truncation occurred on retrieval
DataException - sqlException - if an SQLException occurred

Overrides:
deleteRow in class StatementResult
See Also:
SelectStatement.setForceSearchedUpdate(boolean)

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 can only position to it if your SelectResult is read-only and you are using a JDBC 2.0 driver. Otherwise, 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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DataException - rowNotFound - if the lockRows property of the associated SelectStatement is true and the new current row cannot be locked
DataException - beforeCacheStart - if the requested row is before the start of the cache
DataException - sqlException - if an SQLException occurred
See Also:
setCurrentRow(int)

getCacheValueAt

public java.lang.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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - beforeCacheStart - if the requested row is before the start of the cache
DataException - indexTooLarge - if the requested row is after the end of the cache
java.lang.IndexOutOfBoundsException - noSuchColumn - if the column index is not defined

See Also:
setColumnValue(int, java.lang.Object)

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 java.lang.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
java.lang.IndexOutOfBoundsException - noSuchColumn - if the column index is not defined
Overrides:
getColumnName in class StatementResult

getColumnValue

public java.lang.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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
java.lang.IndexOutOfBoundsException - noSuchColumn - if the column index is not defined

Overrides:
getColumnValue in class StatementResult
See Also:
getColumnValueToString(int), setColumnValue(int, java.lang.Object)

getColumnValue

public java.lang.Object getColumnValue(java.lang.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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
java.lang.IndexOutOfBoundsException - noSuchColumn - if the column name is not defined

Overrides:
getColumnValue in class StatementResult
See Also:
getColumnValueToString(int), setColumnValue(int, java.lang.Object)

getColumnValueToString

public java.lang.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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
java.lang.IndexOutOfBoundsException - noSuchColumn - if the column index is not defined

Overrides:
getColumnValueToString in class StatementResult
See Also:
getColumnValue(int), setColumnValueFromString(int, java.lang.String)

getColumnValueToString

public java.lang.String getColumnValueToString(java.lang.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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
java.lang.IndexOutOfBoundsException - noSuchColumn - if the column name is not defined

Overrides:
getColumnValueToString in class StatementResult
See Also:
getColumnValue(int), setColumnValueFromString(int, java.lang.String)

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(int)

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:
SelectStatement.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:
SelectStatement.setMaximumRows(int)

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 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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DataException - rowNotFound - if the lockRows property of the associated SelectStatement is true and the new current row cannot be locked
DataException - sqlException - if an SQLException occurred

See Also:
setCurrentRow(int)

lockRow

public 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, the bean generates and executes 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 the bean will attempt to parse your query for this information, with no guarantee of success.

Throws:
DataException - noStatement - if no SelectStatement associated with this SelectResult
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - noActiveConnection - if no active connection exists
DataException - readOnly - if the result set is read only
DataException - rowNotFound - if the current row cannot be locked because it cannot be found in the database
DataException - rowNotInDatabase - if the current row cannot be locked in the database because it has not yet been written to the database
DataException - lockNotSupported - if the current row cannot be locked because the database does not have function required to do so
DataException - truncated - if data truncation occurred on retrieval
DataException - sqlException - if an SQLException occurred
See Also:
unlockRow(), SelectStatement.setLockRows(boolean)

newRow

public 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
DataException - notExecuted - if associated statement has not been executed
DataException - readOnly - if the result set is read only
DataException - maxSize - if the maximum number of rows in the result set has been reached
DataException - rowChanged - if the current row cannot be updated because it cannot be found in the database

nextPacket

public 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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - notOpen - if the result set is not open
DataException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DataException - rowNotFound - if the lockRows property of the associated SelectStatement is true and the new current row cannot be locked
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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DataException - rowNotFound - if the lockRows property of the associated SelectStatement is true and the new current row cannot be locked
DataException - sqlException - if an SQLException occurred
See Also:
setCurrentRow(int)

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 in the result set has been displaced from the cache, you can only position to it if your SelectResult is read-only and you are using a JDBC 2.0 driver. Otherwise, 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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DataException - rowNotFound - if the lockRows property of the associated SelectStatement is true and the new current row cannot be locked
DataException - beforeCacheStart - if the requested row is before the start of the cache
DataException - sqlException - if an SQLException occurred

See Also:
setCurrentRow(int)

refreshColumn

public void refreshColumn(int columnNumber)
                   throws DataException
Refreshes the specified column value in the current row from the database.
Parameters:
columnNumber - index of the column to refresh
Throws:
DataException - noStatement - if no SelectStatement associated with this SelectResult
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - rowNotInDatabase - if the current row cannot be refreshed because it has not yet been written to the database
DataException - truncated - if data truncation occurred on retrieval
DataException - sqlException - if an SQLException occurred

refreshRow

public void refreshRow()
                throws DataException
Refreshes a row's column values with those currently in the database.
Throws:
DataException - noStatement - if no SelectStatement associated with this SelectResult
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - rowNotInDatabase - if the current row cannot be refreshed because it has not yet been written to the database
DataException - truncated - if data truncation occurred on retrieval
DataException - sqlException - if an SQLException occurred

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.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(java.beans.PropertyChangeListener)

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(com.ibm.db.StatementResultValueChangeListener)

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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - readOnly - if the result set is read only
Overrides:
restoreRow in class StatementResult

setColumnValue

public void setColumnValue(int columnNumber,
                           java.lang.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
DataException - notExecuted - if associated statement has not been executed
DataException - readOnly - if the result set is read only
DataException - noResults - if the result set is empty
java.lang.IndexOutOfBoundsException - noSuchColumn - if the column index is not defined
DataException - wrongObjectType - if the value does not match the object type of the column
DataException - truncated - if data truncation occurred on retrieval.

Overrides:
setColumnValue in class StatementResult
See Also:
setColumnValueFromString(int, java.lang.String), getColumnValue(int)

setColumnValue

public void setColumnValue(java.lang.String columnName,
                           java.lang.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
DataException - notExecuted - if associated statement has not been executed
DataException - readOnly - if the result set is read only
DataException - noResults - if the result set is empty
java.lang.IndexOutOfBoundsException - noSuchColumn - if the column name is not defined
DataException - wrongObjectType - if the value does not match the object type of the column
DataException - truncated - if data truncation occurred on retrieval.

Overrides:
setColumnValue in class StatementResult
See Also:
setColumnValueFromString(int, java.lang.String), getColumnValue(int)

setColumnValueFromString

public void setColumnValueFromString(int columnNumber,
                                     java.lang.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
DataException - notExecuted - if associated statement has not been executed
DataException - readOnly - if the result set is read only
DataException - noResults - if the result set is empty
java.lang.IndexOutOfBoundsException - noSuchColumn - if the column index is not defined
DataException - cannotConvert - if cannot convert to object type of column
DataException - truncated - if data truncation occurred on retrieval.

Overrides:
setColumnValueFromString in class StatementResult
See Also:
setColumnValue(int, java.lang.Object), getColumnValueToString(int)

setColumnValueFromString

public void setColumnValueFromString(java.lang.String columnName,
                                     java.lang.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
DataException - notExecuted - if associated statement has not been executed
DataException - readOnly - if the result set is read only
DataException - noResults - if the result set is empty
java.lang.IndexOutOfBoundsException - noSuchColumn - if the column name is not defined
DataException - cannotConvert - if cannot convert to object type of column
DataException - truncated - if data truncation occurred on retrieval.

Overrides:
setColumnValueFromString in class StatementResult
See Also:
setColumnValue(int, java.lang.Object), getColumnValueToString(int)

setCurrentRow

public 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 can only position to it if your SelectResult is read-only and you are using a JDBC 2.0 driver. Otherwise, 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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DataException - rowNotFound - if the lockRows property of the associated SelectStatement is true and the new current row cannot be locked
DataException - beforeCacheStart - if the requested row is before the start of the cache
DataException - indexTooLarge - if the requested row is after the end of the result set
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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - noActiveConnection - if no active connection exists
DataException - readOnly - if the result set is read only
DataException - sqlException - if an SQLException occurred
See Also:
lockRow()

updateRow

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

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. 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 the bean 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 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 more information on when the bean performs 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
DataException - notExecuted - if associated statement has not been executed
DataException - noResults - if the result set is empty
DataException - noActiveConnection - if no active connection exists
DataException - readOnly - if the result set is read only
DataException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DataException - sqlException - if an SQLException occurred

Overrides:
updateRow in class StatementResult
See Also:
SelectStatement.setForceSearchedUpdate(boolean)