:: com :: sun :: star :: sdb ::

Description

is a client side RowSet, which use retrieves is data based on a database table, a query or a SQL command or by a rowset reader, who mustn't support SQL. The connection of the rowset is typically a named DataSource or a DataAccess component or a previous instanciated connection.

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 also

RowChangeAction, RowChangeEvent, ResultSet

See also

RowsChangeEvent

Notifications

A row set is able to be operated in various ways, and additionally it notifies various changes in it's 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 also XRowSetApproveListener
column values	If the opration includes changes in the values of the columns of the row set, then these are notified before anything else (except requests for approval). See also ::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

Deletions

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 behaviour of several other methods is affected:

::com::sun::star::sdbc::XResultSet::getRow

returns the position of the cursor, which has not been changed by the deletion.

::com::sun::star::sdbc::XResultSet: next, first, last, absolute, relative, previous, beforeFirst, afterLast

will let the deleted row vanish from the result set. As a consequence, the RowCount will decrease when you do such a move operation after deleting a row.
A special case to note is the next 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.

::com::sun::star::sdbc::XResultSet::refreshRow

will throw an exception when the cursor is on a deleted row.

::com::sun::star::sdbc::XRow: getFoo

will return an empty value when the cursor is on a deleted row.

::com::sun::star::sdbcx::XRowLocate::getBookmark

will throw an exception when the cursor is on a deleted row.

::com::sun::star::sdbc::XRowUpdate: updateFoo

will throw an exception when the cursor is on a deleted row.

::com::sun::star::sdbc::XResultSetUpdate::deleteRow

will throw an exception when the cursor is on a deleted row.

::com::sun::star::sdbc::XResultSetUpdate::moveToInsertRow

will let the deleted row vanish from the result set. As a consequence, the RowCount will decrease. Also, subsequent calls to ::com::sun::star::sdbc::XResultSetUpdate::moveToCurrentRow will not be able to move back to the deleted row (since it vanished), but only to the row after the deleted row.