xref: /trunk/main/offapi/com/sun/star/sdb/RowSet.idl (revision d1766043)

/**************************************************************
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/


#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 {
published 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 {
published interface XDeleteRows;
};};};};

 module com {  module sun {  module star {  module sdb {

published interface XRowSetApproveBroadcaster;
published interface XResultSetAccess;
published interface XParametersSupplier;


/** 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
    @see com::sun::star::sdb::RowsChangeEvent
	</p>

	<h3>Notifications</h3>
    <p>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 or a
            <member>XRowsChangeListener::rowsChanged</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 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>rowsChanged</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/><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/><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/><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/><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/><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/><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/><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/><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>refreshRow</em></td><td/><td/><td align="center">X</td><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/><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><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 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><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/><td align="center">X</td><td align="center">X</td></tr>
		<tr><td align="right"><em>moveToCurrentRow</em></td><td align="center">X</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><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><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/><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/><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr>

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

    <h3>Deletions</h3>
    <p>Via <member scope="com::sun::star::sdbc">XResultSetUpdate::deleteRow</member>, you can delete the current row of a
    <type>RowSet</type>. This deleted row then doesn't vanish immediately, but is still present, and subsequent calls to
    <member scope="com::sun::star::sdbc">XResultSet::rowDeleted</member> will return <TRUE/>. The deleted row "vanishes" from
    the <type>RowSet</type> as soon as the cursor is moved away from it.<br/>
    As a consequence, the behaviour of several other methods is affected:<br/>
	<dl>
        <dt><member scope="com::sun::star::sdbc">XResultSet::getRow</member></dt>
        <dd>returns the position of the cursor, which has not been changed by the deletion.</dd>

        <dt><type scope="com::sun::star::sdbc">XResultSet</type>: <code>next</code>, <code>first</code>, <code>last</code>, <code>absolute</code>,
            <code>relative</code>, <code>previous</code>, <code>beforeFirst</code>, <code>afterLast</code></dt>
        <dd>will let the deleted row vanish from the result set. As a consequence, the <member>RowCount</member>
            will decrease when you do such a move operation after deleting a row.<br/>
            A special case to note is the <code>next<code> call: When you delete row, say,
            <code>15</code>, followed by <code>next</code>, then your <type>RowSet</type> afterwards
            still is on row 15, since the deleted row vanished with the move operation.</dd>

        <dt><member scope="com::sun::star::sdbc">XResultSet::refreshRow</member></dt>
        <dd>will throw an exception when the cursor is on a deleted row.</dd>

        <dt><type scope="com::sun::star::sdbc">XRow</type>: <code>getFoo</code></dt>
        <dd>will return an empty value when the cursor is on a deleted row.</dd>

        <dt><member scope="com::sun::star::sdbcx">XRowLocate::getBookmark</member></dt>
        <dd>will throw an exception when the cursor is on a deleted row.</dd>

        <dt><type scope="com::sun::star::sdbc">XRowUpdate</type>: <code>updateFoo</code></dt>
        <dd>will throw an exception when the cursor is on a deleted row.</dd>

        <dt><member scope="com::sun::star::sdbc">XResultSetUpdate::deleteRow</member></dt>
        <dd>will throw an exception when the cursor is on a deleted row.</dd>

        <dt><member scope="com::sun::star::sdbc">XResultSetUpdate::moveToInsertRow</member></dt>
        <dd>will let the deleted row vanish from the result set. As a consequence, the <member>RowCount</member>
            will decrease. Also, subsequent calls to
            <member scope="com::sun::star::sdbc">XResultSetUpdate::moveToCurrentRow</member> will not
            be able to move back to the deleted row (since it vanished), but only to the
            row after the deleted row.</dd>
    </dl>
    </p>
 */
published 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.
        The default implementation will only ask for parameters which aren't set before through the <type scope="com::sun::star::sdbc">XParameters</type> interface.</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> service.</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> service.</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::sdbcx">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;

    /** gives access to the parameters contained in the SQL statement represented by the component.

        <p>If your <code>RowSet</code> is bound to an SQL command or query which contains parameters, or has
        a <member>Filter</member> or <member>Order</member> which contains parameters, then those can be accessed
        using the <code>XParametersSupplier</code> interface.</p>

        <p>The returned container contains parameter objects which do allow write access to the parameters (which
        is equivalent to using the <type scope="com::sun::star::sdbc">XParameters</type> interface inherited from
        <type scope="com::sun::star::sdbc">RowSet</type>). Additionally, they provide information about the parameters,
        such as their name (if they have one), their type, and the like.</p>
    */
    [optional] interface XParametersSupplier;

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

        <p>In case of a <member>CommandType</member> of <member>CommandType::COMMAND</member>,
        means in case the <member>Command</member> specifies an SQL statement, the inherited
        <member scope="com::sun::star::sdbc">RowSet::EscapeProcessing</member>
        becomes relevant:<br/>
        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.<br/>
        The default value for <member scope="com::sun::star::sdbc">RowSet::EscapeProcessing</member>
        is <TRUE/>. By switching it to <FALSE/>, you can pass backend-specific SQL statements,
        which are not standard SQL, to your database.</p>

		@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 <FALSE/>.
	 */
	[property] boolean ApplyFilter;

	/** additional having clause for the row set
	 */
	[optional,property] string HavingClause;

	/** additional group by for the row set
	 */
	[optional,property] string GroupBy;

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