/*************************************************************************
 *
 *  $RCSfile: RowSet.idl,v $
 *
 *  $Revision: 1.14 $
 *
 *  last change: $Author: vg $ $Date: 2003/06/25 11:09:01 $
 *
 *  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 <com/sun/star/sdbc/RowSet.idl> 
#endif 
 
 module com {  module sun {  module star {  module sdbc { 
interface XConnection; 
};};};}; 
 
#ifndef __com_sun_star_sdb_ResultSet_idl__ 
#include <com/sun/star/sdb/ResultSet.idl> 
#endif 
 
#ifndef __com_sun_star_sdb_XCompletedExecution_idl__
#include <com/sun/star/sdb/XCompletedExecution.idl>
#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.
	<p>
	Depending on the 
	<type scope="com::sun::star::sdbc">ResultSetConcurrency</type>
	, 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.
	</p>
	<p>
	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
	</p>

	<p><strong>Notifications</strong><br/>
	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.</br>
	The following describes the general order of all possible notifications which you can encounter when
	working with a row set:
	<table>
		<tr><td valign="top"><em>approving</em></td>
			<td valign="top">Before anything really happens, any veto listeners are called to approve the operation
				which is just being done. This may be either a
				<member>XRowSetApproveListener::approveCursorMove</member> or 
				<member>XRowSetApproveListener::approveRowChange</member> call.
				@see XRowSetApproveListener
			</td>
		</tr>
		<tr><td valign="top"><em>column values</em></td>
			<td valign="top">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
			</td>
		</tr>
		<tr><td valign="top"><em>operation done</em></td>
			<td valign="top">When the operation is done, you get a notification about this. It may be a
			<member scope="com::sun::star::sdbc">XRowSetListener::cursorMoved</member> or a
			<member scope="com::sun::star::sdbc">XRowSetListener::rowChanged</member> call.
			</td>
		</tr>
		<tr><td valign="top"><em>row state</em></td>
			<td valign="top">If the operation leads to a change in the state of the <member>IsModified</member>
			and/or <member>IsNew</member> property, this is notified next (in this order).
			</td>
		</tr>
		<tr><td valign="top"><em>row count</em></td>
			<td valign="top">If the operation leads to new knowledge about the number of rows in the result set,
			the the respective changes in the <member>RowCount</member> and <member>IsRowCountFinal</member>
			are notified last (in this order).
			</td>
		</tr>
	</table>
	</p>

	<br/>

	<p>The following matrix shows the notifications which apply to the different operations:
	<table border="1" frame="all">
		<tr><td/><td><strong>approveCursorMove</strong></td><td><strong>approveRowChange</strong></td>
				<td><strong>column values</strong></td>
				<td><strong>cursorMoved</strong></td><td><strong>rowChanged</strong></td>
				<td><strong>IsModified</strong></td><td><strong>IsNew</strong></td>
				<td><strong>RowCount</strong></td><td><strong>IsRowCountFinal</strong></td>
		</tr>

		<tr><td><type scope="com::sun::star::sdbc">XResultSet</type></td><td/><td/><td/><td/><td/><td/><td/><td/></tr>

		<tr><td align="right"><em>next</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td>
		<tr><td align="right"><em>beforeFirst</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td/></tr>
		<tr><td align="right"><em>afterLast</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr>
		<tr><td align="right"><em>first</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr>
		<tr><td align="right"><em>last</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr>
		<tr><td align="right"><em>absolute</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr>
		<tr><td align="right"><em>relative</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr>
		<tr><td align="right"><em>previous</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td/></tr>
		<tr><td align="right"><em>refreshRow</em></td><td/><td/><td align="center">X</td><td/><td/><td align="center">X</td><td align="center">X</td><td/><td/></tr>
		<tr><td align="right"><em>cancelRowUpdates</em></td><td/><td/><td align="center">X</td><td/><td/><td align="center">X</td><td/><td/><td/></tr>

		<tr><td><type scope="com::sun::star::sdbc">XResultSetUpdate</type></td><td/><td/><td/><td/><td/><td/><td/><td/></tr>

		<tr><td align="right"><em>insertRow</em></td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr>
		<tr><td align="right"><em>updateRow</em></td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td/><td/></tr>
		<tr><td align="right"><em>deleteRow</em></td><td/><td align="center">X</td><td/><td/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr>
		<tr><td align="right"><em>moveToInsertRow</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td/><td align="center">X</td><td/><td/></tr>
		<tr><td align="right"><em>moveToCurrentRow</em></td><td align="center">X</td><td/><td/><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td/></tr>

		<tr><td><type scope="com::sun::star::sdbcx">XDeleteRows</type></td><td/><td/><td/><td/><td/><td/><td/><td/></tr>

		<tr><td align="right"><em>deleteRows</em></td><td/><td align="center">X</td><td/><td/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr>

		<tr><td><type scope="com::sun::star::sdbcx">XRowLocate</type></td><td/><td/><td/><td/><td/><td/><td/><td/></tr>

		<tr><td align="right"><em>moveToBookmark</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td/></tr>
		<tr><td align="right"><em>moveRelativeToBookmark</em></td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr>

		</tr>
	</table>
	</p>

 */
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.

		<p>If you want a row set to be based on a parametrized query, you will usually use
		the <type scope="com::sun::star::sdbc">XParameters</type> interface.<br/>
		However, you can also choose to let an interaction handler supply such data. For this, you may
		for instance instantiate an <type>InteractionHandler</type>, which asks the user for the
		data, or you may write your own one, which supplies the data from somewhere else.</p>

		@see com::sun::star::sdb::InteractionHandler
	*/
	interface com::sun::star::sdb::XCompletedExecution;

	/** approving of actions performed on the rowset.

        <p>The support of this interface implies a sematical extension to the <type scope="com::sun::star::sdbc">XResultSetUpdate</type>
        interface which is supported via the <type scope="com::sun::star::sdbc">ResultSet</type>.</p>

        @see XResultSetUpdate
	 */
	interface XRowSetApproveBroadcaster;
 
	/** is the interface for updating row data to the database.

        <p>The optional support of this interface is already implied with the support of the <type scope="com::sun::star::sdbc">ResultSet</type>.</p>

        <p>However, note that the additional support of the <type>XRowSetApproveBroadcaster</type> interface results
        in a sematical extension: the methods <member scope="com::sun::star::sdbc">XResultSetUpdate::insertRow</member>,
        <member scope="com::sun::star::sdbc">XResultSetUpdate::updateRow</member> and <member scope="com::sun::star::sdbc">XResultSetUpdate::deleteRow</member>
        will now throw the <type>RowSetVetoException</type> if the action which is to be performed was vetoed
        by one of the <type>XRowSetApproveListener</type>'s.</p>
	 */
    [optional] interface com::sun::star::sdbc::XResultSetUpdate;
	 
	/** is the interface for deleting more than one row, identified by it's bookmark.

        <p>The optional support of this interface is already implied with the support of the <type scope="com::sun::star::sdbcx">ResultSet</type>.</p>

        <p>However, note that the additional support of the <type>XRowSetApproveBroadcaster</type> interface results
        in a sematical extension: the method <member scope="com::sun::star::sdbc">XDeleteRows::deleteRows</member>
        will now throw the <type>RowSetVetoException</type> if the deletion was vetoed
        by one of the <type>XRowSetApproveListener</type>'s.</p>
	 */
	[optional] interface com::sun::star::sdbcx::XDeleteRows; 

    /** creates a second result set which is based on the same data.
		<p>
		The new result set is interoperable with the row set which created it, 
		e.g., you can exchange bookmarks between both sets.
		</p>
		<p>
		If the row set is not alive (i.e., it was not executed before), 
		<NULL/> 
		is returned.
		</p>
	*/
	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.
		@see com::sun::star::sdb::CommandType
	 */
	[property] string Command; 
 
	 
	/** is the type of the command.
		@see com::sun::star::sdb::CommandType
	 */
	[property] long CommandType;

	// note: the EscapeProcessing is not really optional, but we needed to declare it this way because
	// the service was already frozen
	/** specifies if the <member>Command</member> should be analyzed on the client side before sending it
		to the database server.

		<p>The default value of this property is <TRUE/>. By switching it to <FALSE/>, you can pass
		backend-specific SQL statements, which are not standard SQL, to your database.</p>

		<p>This property is evaluated if and only if <member>CommandType</member> equals <member>CommandType::COMMAND</member>.</p>
	*/
	[optional, property] boolean EscapeProcessing;
 
	 
	/** 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 <FALSE/>.
	 */
	[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 
