offapi/com/sun/star/sdb/RowSet.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: RowSet.idl,v $
  10  * $Revision: 1.23 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_sdb_RowSet_idl__
  31 #define __com_sun_star_sdb_RowSet_idl__
  32
  33 #ifndef __com_sun_star_sdbc_RowSet_idl__
  34 #include <com/sun/star/sdbc/RowSet.idl>
  35 #endif
  36
  37 module com {  module sun {  module star {  module sdbc {
  38 published interface XConnection;
  39 };};};};
  40
  41 #ifndef __com_sun_star_sdb_ResultSet_idl__
  42 #include <com/sun/star/sdb/ResultSet.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_sdb_XCompletedExecution_idl__
  46 #include <com/sun/star/sdb/XCompletedExecution.idl>
  47 #endif
  48
  49  module com {  module sun {  module star {  module sdbcx {
  50 published interface XDeleteRows;
  51 };};};};
  52
  53  module com {  module sun {  module star {  module sdb {
  54
  55 published interface XRowSetApproveBroadcaster;
  56 published interface XResultSetAccess;
  57 published interface XParametersSupplier;
  58
  59
  60 /** is a client side RowSet, which use retrieves is data based on a database table,
  61     a query or a SQL command or by a rowset reader, who mustn't support SQL.
  62     The connection of the rowset is typically a named DataSource or a DataAccess component
  63     or a previous instanciated connection.
  64     <p>
  65     Depending on the
  66     <type scope="com::sun::star::sdbc">ResultSetConcurrency</type>
  67     , the RowSet caches all data or uses
  68     an optimized way for retrieving the data, such as, refetching rows by their keys or
  69     if provided, by their bookmarks.
  70     </p>
  71     <p>
  72     In addition, it provides events for RowSet navigation and RowSet modifications
  73     to approve the actions and to react on them.
  74     @see com::sun::star::sdb::RowChangeAction
  75     @see com::sun::star::sdb::RowChangeEvent
  76     </p>
  77
  78     <h3>Notifications</h3>
  79     <p>A row set is able to be operated in various ways, and additionally it notifies various changes in it's
  80     state. Clients of this service can rely on a fixed order of notifications, depending on how they operate
  81     on the component.</br>
  82     The following describes the general order of all possible notifications which you can encounter when
  83     working with a row set:
  84     <table>
  85         <tr><td valign="top"><em>approving</em></td>
  86             <td valign="top">Before anything really happens, any veto listeners are called to approve the operation
  87                 which is just being done. This may be either a
  88                 <member>XRowSetApproveListener::approveCursorMove</member> or
  89                 <member>XRowSetApproveListener::approveRowChange</member> call.
  90                 @see XRowSetApproveListener
  91             </td>
  92         </tr>
  93         <tr><td valign="top"><em>column values</em></td>
  94             <td valign="top">If the opration includes changes in the values of the columns of the row set, then these are
  95             notified before anything else (except requests for approval).
  96             @see ResultSet
  97             @see com::sun::star::sdbcx::XColumnsSupplier
  98             </td>
  99         </tr>
 100         <tr><td valign="top"><em>operation done</em></td>
 101             <td valign="top">When the operation is done, you get a notification about this. It may be a
 102             <member scope="com::sun::star::sdbc">XRowSetListener::cursorMoved</member> or a
 103             <member scope="com::sun::star::sdbc">XRowSetListener::rowChanged</member> call.
 104             </td>
 105         </tr>
 106         <tr><td valign="top"><em>row state</em></td>
 107             <td valign="top">If the operation leads to a change in the state of the <member>IsModified</member>
 108             and/or <member>IsNew</member> property, this is notified next (in this order).
 109             </td>
 110         </tr>
 111         <tr><td valign="top"><em>row count</em></td>
 112             <td valign="top">If the operation leads to new knowledge about the number of rows in the result set,
 113             the respective changes in the <member>RowCount</member> and <member>IsRowCountFinal</member>
 114             are notified last (in this order).
 115             </td>
 116         </tr>
 117     </table>
 118     </p>
 119
 120     <br/>
 121
 122     <p>The following matrix shows the notifications which apply to the different operations:
 123     <table border="1" frame="all">
 124         <tr><td/><td><strong>approveCursorMove</strong></td><td><strong>approveRowChange</strong></td>
 125                 <td><strong>column values</strong></td>
 126                 <td><strong>cursorMoved</strong></td><td><strong>rowChanged</strong></td>
 127                 <td><strong>IsModified</strong></td><td><strong>IsNew</strong></td>
 128                 <td><strong>RowCount</strong></td><td><strong>IsRowCountFinal</strong></td>
 129         </tr>
 130
 131         <tr><td><type scope="com::sun::star::sdbc">XResultSet</type></td><td/><td/><td/><td/><td/><td/><td/><td/></tr>
 132
 133         <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>
 134         <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>
 135         <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>
 136         <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>
 137         <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>
 138         <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>
 139         <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>
 140         <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 align="center">X</td><td align="center">X</td></tr>
 141         <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>
 142         <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>
 143
 144         <tr><td><type scope="com::sun::star::sdbc">XResultSetUpdate</type></td><td/><td/><td/><td/><td/><td/><td/><td/></tr>
 145
 146         <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>
 147         <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>
 148         <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>
 149         <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 align="center">X</td></tr>
 150         <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>
 151
 152         <tr><td><type scope="com::sun::star::sdbcx">XDeleteRows</type></td><td/><td/><td/><td/><td/><td/><td/><td/></tr>
 153
 154         <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>
 155
 156         <tr><td><type scope="com::sun::star::sdbcx">XRowLocate</type></td><td/><td/><td/><td/><td/><td/><td/><td/></tr>
 157
 158         <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>
 159         <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>
 160
 161         </tr>
 162     </table>
 163     </p>
 164
 165     <h3>Deletions</h3>
 166     <p>Via <member scope="com::sun::star::sdbc">XResultSetUpdate::deleteRow</member>, you can delete the current row of a
 167     <type>RowSet</type>. This deleted row then doesn't vanish immediately, but is still present, and subsequent calls to
 168     <member scope="com::sun::star::sdbc">XResultSet::rowDeleted</member> will return <TRUE/>. The deleted row "vanishes" from
 169     the <type>RowSet</type> as soon as the cursor is moved away from it.<br/>
 170     As a consequence, the behaviour of several other methods is affected:<br/>
 171     <dl>
 172         <dt><member scope="com::sun::star::sdbc">XResultSet::getRow</member></dt>
 173         <dd>returns the position of the cursor, which has not been changed by the deletion.</dd>
 174
 175         <dt><type scope="com::sun::star::sdbc">XResultSet</type>: <code>next</code>, <code>first</code>, <code>last</code>, <code>absolute</code>,
 176             <code>relative</code>, <code>previous</code>, <code>beforeFirst</code>, <code>afterLast</code></dt>
 177         <dd>will let the deleted row vanish from the result set. As a consequence, the <member>RowCount</member>
 178             will decrease when you do such a move operation after deleting a row.<br/>
 179             A special case to note is the <code>next<code> call: When you delete row, say,
 180             <code>15</code>, followed by <code>next</code>, then your <type>RowSet</type> afterwards
 181             still is on row 15, since the deleted row vanished with the move operation.</dd>
 182
 183         <dt><member scope="com::sun::star::sdbc">XResultSet::refreshRow</member></dt>
 184         <dd>will throw an exception when the cursor is on a deleted row.</dd>
 185
 186         <dt><type scope="com::sun::star::sdbc">XRow</type>: <code>getFoo</code></dt>
 187         <dd>will return an empty value when the cursor is on a deleted row.</dd>
 188
 189         <dt><member scope="com::sun::star::sdbcx">XRowLocate::getBookmark</member></dt>
 190         <dd>will throw an exception when the cursor is on a deleted row.</dd>
 191
 192         <dt><type scope="com::sun::star::sdbc">XRowUpdate</type>: <code>updateFoo</code></dt>
 193         <dd>will throw an exception when the cursor is on a deleted row.</dd>
 194
 195         <dt><member scope="com::sun::star::sdbc">XResultSetUpdate::deleteRow</member></dt>
 196         <dd>will throw an exception when the cursor is on a deleted row.</dd>
 197
 198         <dt><member scope="com::sun::star::sdbc">XResultSetUpdate::moveToInsertRow</member></dt>
 199         <dd>will let the deleted row vanish from the result set. As a consequence, the <member>RowCount</member>
 200             will decrease. Also, subsequent calls to
 201             <member scope="com::sun::star::sdbc">XResultSetUpdate::moveToCurrentRow</member> will not
 202             be able to move back to the deleted row (since it vanished), but only to the
 203             row after the deleted row.</dd>
 204     </dl>
 205     </p>
 206  */
 207 published service RowSet
 208 {
 209     service com::sun::star::sdbc::RowSet;
 210
 211     service com::sun::star::sdb::ResultSet;
 212
 213     /** can be used to allow an interaction handler to supply missing data during a execute process.
 214
 215         <p>If you want a row set to be based on a parametrized query, you will usually use
 216         the <type scope="com::sun::star::sdbc">XParameters</type> interface.<br/>
 217         However, you can also choose to let an interaction handler supply such data. For this, you may
 218         for instance instantiate an <type>InteractionHandler</type>, which asks the user for the
 219         data, or you may write your own one, which supplies the data from somewhere else.
 220         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>
 221
 222         @see com::sun::star::sdb::InteractionHandler
 223     */
 224     interface com::sun::star::sdb::XCompletedExecution;
 225
 226     /** approving of actions performed on the rowset.
 227
 228         <p>The support of this interface implies a sematical extension to the <type scope="com::sun::star::sdbc">XResultSetUpdate</type>
 229         interface which is supported via the <type scope="com::sun::star::sdbc">ResultSet</type>.</p>
 230
 231         @see XResultSetUpdate
 232      */
 233     interface XRowSetApproveBroadcaster;
 234
 235     /** is the interface for updating row data to the database.
 236
 237         <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>
 238
 239         <p>However, note that the additional support of the <type>XRowSetApproveBroadcaster</type> interface results
 240         in a sematical extension: the methods <member scope="com::sun::star::sdbc">XResultSetUpdate::insertRow</member>,
 241         <member scope="com::sun::star::sdbc">XResultSetUpdate::updateRow</member> and <member scope="com::sun::star::sdbc">XResultSetUpdate::deleteRow</member>
 242         will now throw the <type>RowSetVetoException</type> if the action which is to be performed was vetoed
 243         by one of the <type>XRowSetApproveListener</type>'s.</p>
 244      */
 245     [optional] interface com::sun::star::sdbc::XResultSetUpdate;
 246
 247     /** is the interface for deleting more than one row, identified by it's bookmark.
 248
 249         <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>
 250
 251         <p>However, note that the additional support of the <type>XRowSetApproveBroadcaster</type> interface results
 252         in a sematical extension: the method <member scope="com::sun::star::sdbcx">XDeleteRows::deleteRows</member>
 253         will now throw the <type>RowSetVetoException</type> if the deletion was vetoed
 254         by one of the <type>XRowSetApproveListener</type>'s.</p>
 255      */
 256     [optional] interface com::sun::star::sdbcx::XDeleteRows;
 257
 258     /** creates a second result set which is based on the same data.
 259         <p>
 260         The new result set is interoperable with the row set which created it,
 261         e.g., you can exchange bookmarks between both sets.
 262         </p>
 263         <p>
 264         If the row set is not alive (i.e., it was not executed before),
 265         <NULL/>
 266         is returned.
 267         </p>
 268     */
 269     interface XResultSetAccess;
 270
 271     /** gives access to the parameters contained in the SQL statement represented by the component.
 272
 273         <p>If your <code>RowSet</code> is bound to an SQL command or query which contains parameters, or has
 274         a <member>Filter</member> or <member>Order</member> which contains parameters, then those can be accessed
 275         using the <code>XParametersSupplier</code> interface.</p>
 276
 277         <p>The returned container contains parameter objects which do allow write access to the parameters (which
 278         is equivalent to using the <type scope="com::sun::star::sdbc">XParameters</type> interface inherited from
 279         <type scope="com::sun::star::sdbc">RowSet</type>). Additionally, they provide information about the parameters,
 280         such as their name (if they have one), their type, and the like.</p>
 281     */
 282     [optional] interface XParametersSupplier;
 283
 284     /** is the connection generated by a DataSource or by a URL. It could
 285         also be set from outside. When set from outside the RowSet is not responsible for the closing of the connection.
 286      */
 287     [property] com::sun::star::sdbc::XConnection ActiveConnection;
 288
 289
 290     /** is the name of the datasource to use, this could be a named datasource
 291         or the URL of a data access component.
 292      */
 293     [property] string DataSourceName;
 294
 295
 296     /** is the command which should be executed, the type of command depends
 297         on the CommandType.
 298
 299         <p>In case of a <member>CommandType</member> of <member>CommandType::COMMAND</member>,
 300         means in case the <member>Command</member> specifies an SQL statement, the inherited
 301         <member scope="com::sun::star::sdbc">RowSet::EscapeProcessing</member>
 302         becomes relevant:<br/>
 303         It then can be to used to specify whether the SQL statement should be analyzed on the
 304         client side before sending it to the database server.<br/>
 305         The default value for <member scope="com::sun::star::sdbc">RowSet::EscapeProcessing</member>
 306         is <TRUE/>. By switching it to <FALSE/>, you can pass backend-specific SQL statements,
 307         which are not standard SQL, to your database.</p>
 308
 309         @see com::sun::star::sdb::CommandType
 310         @see com::sun::star::sdbc::RowSet::EscapeProcessing
 311      */
 312     [property] string Command;
 313
 314     /** is the type of the command.
 315         @see com::sun::star::sdb::CommandType
 316      */
 317     [property] long CommandType;
 318
 319     /** is the command which is currently used.
 320         @see com::sun::star::sdb::CommandType
 321      */
 322     [readonly, property] string ActiveCommand;
 323
 324
 325     /** indicates whether all results should be discarded or not.
 326      */
 327     [property] boolean IgnoreResult;
 328
 329
 330     /** additional filter for a rowset.
 331      */
 332     [property] string Filter;
 333
 334
 335     /** indicates whether the filter should be applied or not,
 336         default is <FALSE/>.
 337      */
 338     [property] boolean ApplyFilter;
 339
 340     /** additional having clause for the row set
 341      */
 342     [optional,property] string HavingClause;
 343
 344     /** additional group by for the row set
 345      */
 346     [optional,property] string GroupBy;
 347
 348     /** is a additional sort order definition for a rowset.
 349      */
 350     [property] string Order;
 351
 352
 353     /** indicates the privileges for insert, update, and delete.
 354         @see com::sun::star::sdbcx::Privilege
 355      */
 356     [readonly, property] long Privileges;
 357
 358
 359     /** indicates that the current row is modified.
 360      */
 361     [readonly, property] boolean IsModified;
 362
 363
 364     /** indicates that the current row is going to be inserted to the database.
 365      */
 366     [readonly, property] boolean IsNew;
 367
 368
 369     /** contains the number of rows accessed in a the data source.
 370      */
 371     [readonly, property] long RowCount;
 372
 373
 374     /** indicates that all rows of te row set have been counted.
 375      */
 376     [readonly, property] boolean IsRowCountFinal;
 377
 378
 379     /** is the name of the table which should be updated, this is usually used
 380         for queries which relate to more than one table.
 381      */
 382     [optional, property] string UpdateTableName;
 383
 384     /** is the name of the table catalog
 385      */
 386     [optional, property] string UpdateCatalogName;
 387
 388
 389     /** is the name of the table schema.
 390      */
 391     [optional, property] string UpdateSchemaName;
 392 };
 393
 394 //=============================================================================
 395
 396 }; }; }; };
 397
 398 /*===========================================================================
 399 ===========================================================================*/
 400 #endif