|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.db.StatementResult | +--com.ibm.db.SelectResult
SelectResult represents a result set returned from executing an SQL Select statement.
SelectStatement
, Serialized FormConstructor 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 |
public SelectResult()
setStatement
to associate a SelectStatement with this SelectResult.public SelectResult(SelectStatement aStatement)
aStatement
- the associated SelectStatementMethod Detail |
public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
listener
- PropertyChangeListener
removePropertyChangeListener(java.beans.PropertyChangeListener)
public void addStatementResultValueChangeListener(StatementResultValueChangeListener listener)
listener
- StatementResultValueChangeListenerStatementResultValueChangeListener
,
removeStatementResultValueChangeListener(com.ibm.db.StatementResultValueChangeListener)
public void cancelAction() throws DataException
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.
public void close() throws DataException
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.
closeResult()
public void closeResult() throws DataException
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.
close()
public java.util.Enumeration columnNames() throws DataException
StatementMetaData.getColumnNames
to obtain the returned value.public void deleteRow() throws DataException
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.
SelectStatement.setForceSearchedUpdate(boolean)
public void firstRow() throws DataException
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.
setCurrentRow(int)
public java.lang.Object getCacheValueAt(int rowNumber, int columnNumber) throws DataException
rowNumber
- index of the row in cachecolumnNumber
- index of the column in cachesetColumnValue(int, java.lang.Object)
public int getColumnCount() throws DataException
StatementMetaData.getColumnCount
to obtain returned value.public java.lang.String getColumnName(int columnNumber) throws DataException
StatementMetaData.getColumnName
to obtain the returned value.
The index of the first column is 1.columnNumber
- index of the columnpublic java.lang.Object getColumnValue(int columnNumber) throws DataException
columnNumber
- index of the columngetColumnValueToString(int)
,
setColumnValue(int, java.lang.Object)
public java.lang.Object getColumnValue(java.lang.String columnName) throws DataException
columnName
- name of the columngetColumnValueToString(int)
,
setColumnValue(int, java.lang.Object)
public java.lang.String getColumnValueToString(int columnNumber) throws DataException
columnNumber
- index of the columngetColumnValue(int)
,
setColumnValueFromString(int, java.lang.String)
public java.lang.String getColumnValueToString(java.lang.String columnName) throws DataException
columnName
- name of the columngetColumnValue(int)
,
setColumnValueFromString(int, java.lang.String)
public int getCurrentRow()
Most methods on SelectResult operate on the current row.
setCurrentRow(int)
public int getCurrentRowInCache()
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.
public int getNumPacketsInCache()
public int getNumRowsInCache()
public boolean isEnd()
SelectStatement.isOpen()
,
isMaxRowsReached()
public boolean isMaxRowsReached() throws DataException
SelectStatement.setMaximumRows(int)
public boolean isRowLocked()
lockRow()
,
unlockRow()
public void lastRow() throws DataException
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.
setCurrentRow(int)
public void lockRow() throws DataException
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.
unlockRow()
,
SelectStatement.setLockRows(boolean)
public void newRow(boolean beforeCurrent) throws DataException
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.
beforeCurrent
- true, insert the new row before the current row;
false insert the new row after the current row.
public void nextPacket() throws DataException
The event cacheRowsChanged
is triggered by this method.
public void nextRow() throws DataException
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.
setCurrentRow(int)
public void previousRow() throws DataException
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.
setCurrentRow(int)
public void refreshColumn(int columnNumber) throws DataException
columnNumber
- index of the column to refreshpublic void refreshRow() throws DataException
public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
listener
- PropertyChangeListener
addPropertyChangeListener(java.beans.PropertyChangeListener)
public void removeStatementResultValueChangeListener(StatementResultValueChangeListener listener)
listener
- StatementResultValueChangeListener
StatementResultValueChangeListener
,
addStatementResultValueChangeListener(com.ibm.db.StatementResultValueChangeListener)
public void restoreRow() throws DataException
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.
public void setColumnValue(int columnNumber, java.lang.Object aValue) throws DataException
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.
columnNumber
- index of the columnaValue
- value for the column
setColumnValueFromString(int, java.lang.String)
,
getColumnValue(int)
public void setColumnValue(java.lang.String columnName, java.lang.Object aValue) throws DataException
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.
columnName
- name of the columnaValue
- value for the column
setColumnValueFromString(int, java.lang.String)
,
getColumnValue(int)
public void setColumnValueFromString(int columnNumber, java.lang.String stringValue) throws DataException
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.
columnNumber
- index of the columnstringValue
- value for the column
setColumnValue(int, java.lang.Object)
,
getColumnValueToString(int)
public void setColumnValueFromString(java.lang.String columnName, java.lang.String stringValue) throws DataException
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.
columnName
- name of the columnstringValue
- value for the column
setColumnValue(int, java.lang.Object)
,
getColumnValueToString(int)
public void setCurrentRow(int rowNumber) throws DataException
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.
rowNumber
- index in the result set of the row
getCurrentRow()
public void setStatement(SelectStatement aStatement)
aStatement
- the associated SelectStatementpublic void unlockRow() throws DataException
lockRow()
public void updateRow() throws DataException
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.
SelectStatement.setForceSearchedUpdate(boolean)
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |