Depending on the com::sun::star::sdbc::ResultSetConcurrency , the RowSet caches all data or uses an optimized way for retrieving the data, such as, refetching rows by their keys or if provided, by their bookmarks.
In addition, it provides events for RowSet navigation and RowSet modifications to approve the actions and to react on them. @see com::sun::star::sdb::RowChangeAction @see com::sun::star::sdb::RowChangeEvent @see com::sun::star::sdb::RowsChangeEvent
A row set is able to be operated in various ways, and additionally it notifies various changes in its
state. Clients of this service can rely on a fixed order of notifications, depending on how they operate
on the component.
The following describes the general order of all possible notifications which you can encounter when
working with a row set:
| approving | Before anything really happens, any veto listeners are called to approve the operation which is just being done. This may be either a XRowSetApproveListener::approveCursorMove() or XRowSetApproveListener::approveRowChange() call. @see XRowSetApproveListener |
| column values | If the operation includes changes in the values of the columns of the row set, then these are notified before anything else (except requests for approval). @see ResultSet @see com::sun::star::sdbcx::XColumnsSupplier |
| operation done | When the operation is done, you get a notification about this. It may be a com::sun::star::sdbc::XRowSetListener::cursorMoved() or a com::sun::star::sdbc::XRowSetListener::rowChanged() call or a XRowsChangeListener::rowsChanged() call. |
| row state | If the operation leads to a change in the state of the #IsModified and/or #IsNew property, this is notified next (in this order). |
| row count | If the operation leads to new knowledge about the number of rows in the result set, the respective changes in the #RowCount and #IsRowCountFinal are notified last (in this order). |
The following matrix shows the notifications which apply to the different operations:
| approveCursorMove | approveRowChange | column values | cursorMoved | rowChanged | rowsChanged | IsModified | IsNew | RowCount | IsRowCountFinal | |
| com::sun::star::sdbc::XResultSet | ||||||||||
| next | X | X | X | X | X | X | X | |||
| beforeFirst | X | X | X | X | X | |||||
| afterLast | X | X | X | X | X | X | X | |||
| first | X | X | X | X | X | X | X | |||
| last | X | X | X | X | X | X | X | |||
| absolute | X | X | X | X | X | X | X | |||
| relative | X | X | X | X | X | X | X | |||
| previous | X | X | X | X | X | X | X | |||
| refreshRow | X | X | X | |||||||
| cancelRowUpdates | X | X | ||||||||
| com::sun::star::sdbc::XResultSetUpdate | ||||||||||
| insertRow | X | X | X | X | X | X | X | X | ||
| updateRow | X | X | X | X | X | |||||
| deleteRow | X | X | X | X | X | X | X | |||
| moveToInsertRow | X | X | X | X | X | |||||
| moveToCurrentRow | X | X | X | X | ||||||
| com::sun::star::sdbcx::XDeleteRows | ||||||||||
| deleteRows | X | X | X | X | X | X | X | |||
| com::sun::star::sdbcx::XRowLocate | ||||||||||
| moveToBookmark | X | X | X | X | X | |||||
| moveRelativeToBookmark | X | X | X | X | X | X | X |
Via com::sun::star::sdbc::XResultSetUpdate::deleteRow(), you can delete the current row of a
RowSet. This deleted row then doesn't vanish immediately, but is still present, and subsequent calls to
com::sun::star::sdbc::XResultSet::rowDeleted() will return `TRUE`. The deleted row "vanishes" from
the RowSet as soon as the cursor is moved away from it.
As a consequence, the behavior of several other methods is affected:
next, first, last, absolute,
relative, previous, beforeFirst, afterLastnext call: When you delete row, say,
15, followed by next, then your RowSet afterwards
still is on row 15, since the deleted row vanished with the move operation.getFooupdateFooIf you want a row set to be based on a parametrized query, you will usually use
the com::sun::star::sdbc::XParameters interface.
However, you can also choose to let an interaction handler supply such data. For this, you may
for instance instantiate an InteractionHandler, which asks the user for the
data, or you may write your own one, which supplies the data from somewhere else.
The default implementation will only ask for parameters which aren't set before through the com::sun::star::sdbc::XParameters interface.
The support of this interface implies a semantical extension to the com::sun::star::sdbc::XResultSetUpdate interface which is supported via the com::sun::star::sdbc::ResultSet.
@see XResultSetUpdate */ interface XRowSetApproveBroadcaster; /** is the interface for updating row data to the database.The optional support of this interface is already implied with the support of the com::sun::star::sdbc::ResultSet service.
However, note that the additional support of the XRowSetApproveBroadcaster interface results in a semantical extension: the methods com::sun::star::sdbc::XResultSetUpdate::insertRow(), com::sun::star::sdbc::XResultSetUpdate::updateRow() and com::sun::star::sdbc::XResultSetUpdate::deleteRow() will now throw the RowSetVetoException if the action which is to be performed was vetoed by one of the XRowSetApproveListener's.
*/ [optional] interface com::sun::star::sdbc::XResultSetUpdate; /** is the interface for deleting more than one row, identified by its bookmark.The optional support of this interface is already implied with the support of the com::sun::star::sdbcx::ResultSet service.
However, note that the additional support of the XRowSetApproveBroadcaster interface results in a semantical extension: the method com::sun::star::sdbcx::XDeleteRows::deleteRows() will now throw the RowSetVetoException if the deletion was vetoed by one of the XRowSetApproveListener's.
*/ [optional] interface com::sun::star::sdbcx::XDeleteRows; /** creates a second result set which is based on the same data.The new result set is interoperable with the row set which created it, e.g., you can exchange bookmarks between both sets.
If the row set is not alive (i.e., it was not executed before), `NULL` is returned.
*/ interface XResultSetAccess; /** gives access to the parameters contained in the SQL statement represented by the component.If your RowSet is bound to an SQL command or query which contains parameters, or has
a #Filter or #Order which contains parameters, then those can be accessed
using the XParametersSupplier interface.
The returned container contains parameter objects which do allow write access to the parameters (which is equivalent to using the com::sun::star::sdbc::XParameters interface inherited from com::sun::star::sdbc::RowSet). Additionally, they provide information about the parameters, such as their name (if they have one), their type, and the like.
*/ [optional] interface XParametersSupplier; /** is the connection generated by a DataSource or by a URL. It could also be set from outside. When set from outside the RowSet is not responsible for the closing of the connection. */ [property] com::sun::star::sdbc::XConnection ActiveConnection; /** is the name of the datasource to use, this could be a named datasource or the URL of a data access component. */ [property] string DataSourceName; /** is the command which should be executed, the type of command depends on the CommandType.In case of a #CommandType of CommandType::COMMAND,
means in case the #Command specifies an SQL statement, the inherited
com::sun::star::sdbc::RowSet::EscapeProcessing
becomes relevant:
It then can be to used to specify whether the SQL statement should be analyzed on the
client side before sending it to the database server.
The default value for com::sun::star::sdbc::RowSet::EscapeProcessing
is `TRUE`. By switching it to `FALSE`, you can pass backend-specific SQL statements,
which are not standard SQL, to your database.