Language:

The Free and Open Productivity Suite
Apache OpenOffice 4.1.4 released

Developer's Guide

API

SDK

Tips 'n' Tricks

Miscellaneous


:: 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 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:

approveCursorMoveapproveRowChange column values cursorMovedrowChanged rowsChanged IsModifiedIsNew RowCountIsRowCountFinal
::com::sun::star::sdbc::XResultSet
nextXXXXXXX
beforeFirstXXXXX
afterLastXXXXXXX
firstXXXXXXX
lastXXXXXXX
absoluteXXXXXXX
relativeXXXXXXX
previousXXXXXXX
refreshRowXXX
cancelRowUpdatesXX
::com::sun::star::sdbc::XResultSetUpdate
insertRowXXXXXXXX
updateRowXXXXX
deleteRowXXXXXXX
moveToInsertRowXXXXX
moveToCurrentRowXXXX
::com::sun::star::sdbcx::XDeleteRows
deleteRowsXXXXXXX
::com::sun::star::sdbcx::XRowLocate
moveToBookmarkXXXXX
moveRelativeToBookmarkXXXXXXX

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.

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 rowset. (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 rowset.  
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 rowset.  
[ 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 te 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 rowset.

The support of this interface implies a sematical 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 sematical 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 sematical 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 rowset.
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 rowset.
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 te 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

Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache and the Apache feather logo are trademarks of The Apache Software Foundation. OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.