1/************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27#ifndef __com_sun_star_sdb_RowSet_idl__ 28#define __com_sun_star_sdb_RowSet_idl__ 29 30#ifndef __com_sun_star_sdbc_RowSet_idl__ 31#include <com/sun/star/sdbc/RowSet.idl> 32#endif 33 34module com { module sun { module star { module sdbc { 35published interface XConnection; 36};};};}; 37 38#ifndef __com_sun_star_sdb_ResultSet_idl__ 39#include <com/sun/star/sdb/ResultSet.idl> 40#endif 41 42#ifndef __com_sun_star_sdb_XCompletedExecution_idl__ 43#include <com/sun/star/sdb/XCompletedExecution.idl> 44#endif 45 46 module com { module sun { module star { module sdbcx { 47published interface XDeleteRows; 48};};};}; 49 50 module com { module sun { module star { module sdb { 51 52published interface XRowSetApproveBroadcaster; 53published interface XResultSetAccess; 54published interface XParametersSupplier; 55 56 57/** is a client side RowSet, which use retrieves is data based on a database table, 58 a query or a SQL command or by a rowset reader, who mustn't support SQL. 59 The connection of the rowset is typically a named DataSource or a DataAccess component 60 or a previous instanciated connection. 61 <p> 62 Depending on the 63 <type scope="com::sun::star::sdbc">ResultSetConcurrency</type> 64 , the RowSet caches all data or uses 65 an optimized way for retrieving the data, such as, refetching rows by their keys or 66 if provided, by their bookmarks. 67 </p> 68 <p> 69 In addition, it provides events for RowSet navigation and RowSet modifications 70 to approve the actions and to react on them. 71 @see com::sun::star::sdb::RowChangeAction 72 @see com::sun::star::sdb::RowChangeEvent 73 @see com::sun::star::sdb::RowsChangeEvent 74 </p> 75 76 <h3>Notifications</h3> 77 <p>A row set is able to be operated in various ways, and additionally it notifies various changes in it's 78 state. Clients of this service can rely on a fixed order of notifications, depending on how they operate 79 on the component.</br> 80 The following describes the general order of all possible notifications which you can encounter when 81 working with a row set: 82 <table> 83 <tr><td valign="top"><em>approving</em></td> 84 <td valign="top">Before anything really happens, any veto listeners are called to approve the operation 85 which is just being done. This may be either a 86 <member>XRowSetApproveListener::approveCursorMove</member> or 87 <member>XRowSetApproveListener::approveRowChange</member> call. 88 @see XRowSetApproveListener 89 </td> 90 </tr> 91 <tr><td valign="top"><em>column values</em></td> 92 <td valign="top">If the opration includes changes in the values of the columns of the row set, then these are 93 notified before anything else (except requests for approval). 94 @see ResultSet 95 @see com::sun::star::sdbcx::XColumnsSupplier 96 </td> 97 </tr> 98 <tr><td valign="top"><em>operation done</em></td> 99 <td valign="top">When the operation is done, you get a notification about this. It may be a 100 <member scope="com::sun::star::sdbc">XRowSetListener::cursorMoved</member> or a 101 <member scope="com::sun::star::sdbc">XRowSetListener::rowChanged</member> call or a 102 <member>XRowsChangeListener::rowsChanged</member> call. 103 </td> 104 </tr> 105 <tr><td valign="top"><em>row state</em></td> 106 <td valign="top">If the operation leads to a change in the state of the <member>IsModified</member> 107 and/or <member>IsNew</member> property, this is notified next (in this order). 108 </td> 109 </tr> 110 <tr><td valign="top"><em>row count</em></td> 111 <td valign="top">If the operation leads to new knowledge about the number of rows in the result set, 112 the respective changes in the <member>RowCount</member> and <member>IsRowCountFinal</member> 113 are notified last (in this order). 114 </td> 115 </tr> 116 </table> 117 </p> 118 119 <br/> 120 121 <p>The following matrix shows the notifications which apply to the different operations: 122 <table border="1" frame="all"> 123 <tr><td/><td><strong>approveCursorMove</strong></td><td><strong>approveRowChange</strong></td> 124 <td><strong>column values</strong></td> 125 <td><strong>cursorMoved</strong></td><td><strong>rowChanged</strong></td> 126 <td><strong>rowsChanged</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/><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/><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/><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/><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/><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/><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/><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/><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/><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/><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><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 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><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/><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/><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><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/><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/><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 */ 207published 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 401