Overview | Module | Use | Devguide | Index

Services' Summary | Interfaces' Summary | Properties' Summary | Services' Details | Interfaces' Details | Properties' Details

:: com :: sun :: star :: sdb ::
service RowSet
  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 row set reader, who mustn't support SQL. The connection of the row set is typically a named DataSource or a DataAccess component or a previous instantiated 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 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 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 behavior 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.

Developers Guide
  Forms - Forms as Row Sets
  Database - The RowSet Service
  Database - Example: Querying the Bibliography Database

Included Services - Summary
::com::sun::star::sdbc::RowSet | (referenced entity's summary:) is a client side ResultSet, which combines the characteristics of a ::com::sun::star::sdbc::Statement and a ::com::sun::star::sdbc::ResultSet.
ResultSet | (referenced entity's summary:) extends the ::com::sun::star::sdbcx::ResultSet by a more sophisticated access to the result sets data.

Exported Interfaces - Summary
XCompletedExecution | can be used to allow an interaction handler to supply missing data during a execute process. (details)
XRowSetApproveBroadcaster | approving of actions performed on the row set. (details)
::com::sun::star::sdbc::XResultSetUpdate | is the interface for updating row data to the database. (details)
::com::sun::star::sdbcx::XDeleteRows | is the interface for deleting more than one row, identified by it's bookmark. (details)
XResultSetAccess | creates a second result set which is based on the same data. (details)
XParametersSupplier | gives access to the parameters contained in the SQL statement represented by the component. (details)

Properties' Summary
::com::sun::star::sdbc::XConnection ActiveConnection | 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.
string DataSourceName | is the name of the datasource to use, this could be a named datasource or the URL of a data access component.
string Command | is the command which should be executed, the type of command depends on the CommandType.
long CommandType | is the type of the command.
[ readonly ] string ActiveCommand | is the command which is currently used.
boolean IgnoreResult | indicates whether all results should be discarded or not.
string Filter | additional filter for a row set.
boolean ApplyFilter | indicates whether the filter should be applied or not, default is false.
string HavingClause | [ OPTIONAL ] additional having clause for the row set
string GroupBy | [ OPTIONAL ] additional group by for the row set
string Order | is a additional sort order definition for a row set.
[ readonly ] long Privileges | indicates the privileges for insert, update, and delete.
[ readonly ] boolean IsModified | indicates that the current row is modified.
[ readonly ] boolean IsNew | indicates that the current row is going to be inserted to the database.
[ readonly ] long RowCount | contains the number of rows accessed in a the data source.
[ readonly ] boolean IsRowCountFinal | indicates that all rows of the row set have been counted.
string UpdateTableName | [ OPTIONAL ] is the name of the table which should be updated, this is usually used for queries which relate to more than one table.
string UpdateCatalogName | [ OPTIONAL ] is the name of the table catalog
string UpdateSchemaName | [ OPTIONAL ] is the name of the table schema.

Included Services - Details
::com::sun::star::sdbc::RowSet
(referenced entity's summary:) is a client side ResultSet, which combines the characteristics of a ::com::sun::star::sdbc::Statement and a ::com::sun::star::sdbc::ResultSet.
ResultSet
(referenced entity's summary:) extends the ::com::sun::star::sdbcx::ResultSet by a more sophisticated access to the result sets data.

Exported Interfaces - Details
XCompletedExecution
Description can be used to allow an interaction handler to supply missing data during a execute process. If 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. See also InteractionHandler
XRowSetApproveBroadcaster
Description approving of actions performed on the row set. 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 also XResultSetUpdate
::com::sun::star::sdbc::XResultSetUpdate
Usage Restrictions optional Description 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.
::com::sun::star::sdbcx::XDeleteRows
Usage Restrictions optional Description is the interface for deleting more than one row, identified by it's 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.
XResultSetAccess
Description 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.
XParametersSupplier
Usage Restrictions optional Description 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.

Properties' Details
ActiveConnection
::com::sun::star::sdbc::XConnection ActiveConnection; Description 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.
DataSourceName
string DataSourceName; Description is the name of the datasource to use, this could be a named datasource or the URL of a data access component.
Command
string Command; Description 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. See also CommandType, ::com::sun::star::sdbc::RowSet::EscapeProcessing
CommandType
long CommandType; Description is the type of the command. See also CommandType
ActiveCommand
[ readonly ] string ActiveCommand; Description is the command which is currently used. See also CommandType
IgnoreResult
boolean IgnoreResult; Description indicates whether all results should be discarded or not.
Filter
string Filter; Description additional filter for a row set.
ApplyFilter
boolean ApplyFilter; Description indicates whether the filter should be applied or not, default is false.
HavingClause
string HavingClause; Usage Restrictions optional Description additional having clause for the row set
GroupBy
string GroupBy; Usage Restrictions optional Description additional group by for the row set
Order
string Order; Description is a additional sort order definition for a row set.
Privileges
[ readonly ] long Privileges; Description indicates the privileges for insert, update, and delete. See also ::com::sun::star::sdbcx::Privilege
IsModified
[ readonly ] boolean IsModified; Description indicates that the current row is modified.
IsNew
[ readonly ] boolean IsNew; Description indicates that the current row is going to be inserted to the database.
RowCount
[ readonly ] long RowCount; Description contains the number of rows accessed in a the data source.
IsRowCountFinal
[ readonly ] boolean IsRowCountFinal; Description indicates that all rows of the row set have been counted.
UpdateTableName
string UpdateTableName; Usage Restrictions optional Description is the name of the table which should be updated, this is usually used for queries which relate to more than one table.
UpdateCatalogName
string UpdateCatalogName; Usage Restrictions optional Description is the name of the table catalog
UpdateSchemaName
string UpdateSchemaName; Usage Restrictions optional Description is the name of the table schema.

Top of Page

Copyright © 2000, 2013 LibreOffice contributors and/or their affiliates. All rights reserved.

LibreOffice was created by The Document Foundation, based on OpenOffice.org, which is Copyright 2000, 2010 Oracle and/or its affiliates.

The Document Foundation acknowledges all community members, please find more info at our website.

Privacy Policy | Impressum (Legal Info) | Copyright information: The source code of LibreOffice is licensed under the GNU Lesser General Public License (LGPLv3). "LibreOffice" and "The Document Foundation" are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy.