/************************************************************************* * * $RCSfile: RowSet.idl,v $ * * $Revision: 1.16 $ * * last change: $Author: hr $ $Date: 2004-04-13 11:11:24 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses * * - GNU Lesser General Public License Version 2.1 * - Sun Industry Standards Source License Version 1.1 * * Sun Microsystems Inc., October, 2000 * * GNU Lesser General Public License Version 2.1 * ============================================= * Copyright 2000 by Sun Microsystems, Inc. * 901 San Antonio Road, Palo Alto, CA 94303, USA * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License version 2.1, as published by the Free Software Foundation. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, * MA 02111-1307 USA * * * Sun Industry Standards Source License Version 1.1 * ================================================= * The contents of this file are subject to the Sun Industry Standards * Source License Version 1.1 (the "License"); You may not use this file * except in compliance with the License. You may obtain a copy of the * License at http://www.openoffice.org/license.html. * * Software provided under this License is provided on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, * WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS, * MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING. * See the License for the specific provisions governing your rights and * obligations concerning the Software. * * The Initial Developer of the Original Code is: Sun Microsystems, Inc. * * Copyright: 2000 by Sun Microsystems, Inc. * * All Rights Reserved. * * Contributor(s): _______________________________________ * * ************************************************************************/ #ifndef __com_sun_star_sdb_RowSet_idl__ #define __com_sun_star_sdb_RowSet_idl__ #ifndef __com_sun_star_sdbc_RowSet_idl__ #include #endif module com { module sun { module star { module sdbc { interface XConnection; };};};}; #ifndef __com_sun_star_sdb_ResultSet_idl__ #include #endif #ifndef __com_sun_star_sdb_XCompletedExecution_idl__ #include #endif module com { module sun { module star { module sdbcx { interface XDeleteRows; };};};}; module com { module sun { module star { module sdb { interface XRowSetApproveBroadcaster; interface XResultSetAccess; /** 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 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

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 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 ResultSet @see com::sun::star::sdbcx::XColumnsSupplier
operation done When the operation is done, you get a notification about this. It may be a XRowSetListener::cursorMoved or a XRowSetListener::rowChanged 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 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 IsModifiedIsNew RowCountIsRowCountFinal
XResultSet
nextXXXXXXX
beforeFirstXXXXX
afterLastXXXXXXX
firstXXXXXXX
lastXXXXXXX
absoluteXXXXXXX
relativeXXXXXXX
previousXXXXX
refreshRowXXX
cancelRowUpdatesXX
XResultSetUpdate
insertRowXXXXXXX
updateRowXXXX
deleteRowXXXXXX
moveToInsertRowXXXX
moveToCurrentRowXXXX
XDeleteRows
deleteRowsXXXXXX
XRowLocate
moveToBookmarkXXXXX
moveRelativeToBookmarkXXXXXXX

*/ service RowSet { service com::sun::star::sdbc::RowSet; service com::sun::star::sdb::ResultSet; /** 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 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.

@see com::sun::star::sdb::InteractionHandler */ interface com::sun::star::sdb::XCompletedExecution; /** approving of actions performed on the rowset.

The support of this interface implies a sematical extension to the XResultSetUpdate interface which is supported via the 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 ResultSet.

However, note that the additional support of the XRowSetApproveBroadcaster interface results in a sematical extension: the methods XResultSetUpdate::insertRow, XResultSetUpdate::updateRow and 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 it's bookmark.

The optional support of this interface is already implied with the support of the ResultSet.

However, note that the additional support of the XRowSetApproveBroadcaster interface results in a sematical extension: the method 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), is returned.

*/ interface XResultSetAccess; /** 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 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 RowSet::EscapeProcessing is . By switching it to , you can pass backend-specific SQL statements, which are not standard SQL, to your database.

@see com::sun::star::sdb::CommandType @see com::sun::star::sdbc::RowSet::EscapeProcessing */ [property] string Command; /** is the type of the command. @see com::sun::star::sdb::CommandType */ [property] long CommandType; /** is the command which is currently used. @see com::sun::star::sdb::CommandType */ [readonly, property] string ActiveCommand; /** indicates whether all results should be discarded or not. */ [property] boolean IgnoreResult; /** additional filter for a rowset. */ [property] string Filter; /** indicates whether the filter should be applied or not, default is . */ [property] boolean ApplyFilter; /** is a additional sort order definition for a rowset. */ [property] string Order; /** indicates the privileges for insert, update, and delete. @see com::sun::star::sdbcx::Privilege */ [readonly, property] long Privileges; /** indicates that the current row is modified. */ [readonly, property] boolean IsModified; /** indicates that the current row is going to be inserted to the database. */ [readonly, property] boolean IsNew; /** contains the number of rows accessed in a the data source. */ [readonly, property] long RowCount; /** indicates that all rows of te row set have been counted. */ [readonly, property] boolean IsRowCountFinal; /** is the name of the table which should be updated, this is usually used for queries which relate to more than one table. */ [optional, property] string UpdateTableName; /** is the name of the table catalog */ [optional, property] string UpdateCatalogName; /** is the name of the table schema. */ [optional, property] string UpdateSchemaName; }; //============================================================================= }; }; }; }; /*=========================================================================== ===========================================================================*/ #endif