summaryrefslogtreecommitdiff
path: root/offapi/com/sun/star/sdb/RowSet.idl
blob: f6b343f49ef09bcb98961755fcf2c2ae39be0f5d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   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 .
 */
#ifndef __com_sun_star_sdb_RowSet_idl__
#define __com_sun_star_sdb_RowSet_idl__

#include <com/sun/star/sdbc/RowSet.idl>

module com {  module sun {  module star {  module sdbc {
published interface XConnection;
};};};};
#include <com/sun/star/sdb/ResultSet.idl>
#include <com/sun/star/sdb/XCompletedExecution.idl>

 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 row set reader, who mustn't support SQL.
    The connection of the row set is typically a named DataSource or a DataAccess component
    or a previous instantiated connection.
    <p>
    Depending on the
    com::sun::star::sdbc::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.
    </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
                XRowSetApproveListener::approveCursorMove() or
                XRowSetApproveListener::approveRowChange() call.
                @see XRowSetApproveListener
            </td>
        </tr>
        <tr><td valign="top"><em>column values</em></td>
            <td valign="top">If the operation 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
            com::sun::star::sdbc::XRowSetListener::cursorMoved() or a
            com::sun::star::sdbc::XRowSetListener::rowChanged() call or a
            XRowsChangeListener::rowsChanged() 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 #IsModified
            and/or #IsNew 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 #RowCount and #IsRowCountFinal
            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><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>com::sun::star::sdbc::XResultSet</td><td></td><td></td><td></td><td></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><td align="center">X</td><td align="center">X</td><td></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><td align="center">X</td><td align="center">X</td><td></td><td></td><td align="center">X</td><td align="center">X</td><td></td><td></td></tr>
        <tr><td align="right"><em>afterLast</em></td><td align="center">X</td><td></td><td align="center">X</td><td align="center">X</td><td></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><td align="center">X</td><td align="center">X</td><td></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><td align="center">X</td><td align="center">X</td><td></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><td align="center">X</td><td align="center">X</td><td></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><td align="center">X</td><td align="center">X</td><td></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><td align="center">X</td><td align="center">X</td><td></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></td><td align="center">X</td><td></td><td></td><td></td><td align="center">X</td><td align="center">X</td><td></td><td></td></tr>
        <tr><td align="right"><em>cancelRowUpdates</em></td><td></td><td></td><td align="center">X</td><td></td><td></td><td></td><td align="center">X</td><td></td><td></td><td></td></tr>

        <tr><td>com::sun::star::sdbc::XResultSetUpdate</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>

        <tr><td align="right"><em>insertRow</em></td><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><td align="center">X</td><td align="center">X</td></tr>
        <tr><td align="right"><em>updateRow</em></td><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></td><td></td><td></td></tr>
        <tr><td align="right"><em>deleteRow</em></td><td></td><td align="center">X</td><td></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><td align="center">X</td><td align="center">X</td><td></td><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></td><td align="center">X</td><td></td><td></td><td align="center">X</td><td align="center">X</td><td></td><td></td></tr>

        <tr><td>com::sun::star::sdbcx::XDeleteRows</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>

        <tr><td align="right"><em>deleteRows</em></td><td></td><td align="center">X</td><td></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>com::sun::star::sdbcx::XRowLocate</td><td></td><td></td><td></td><td></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><td align="center">X</td><td align="center">X</td><td></td><td></td><td align="center">X</td><td align="center">X</td><td></td><td></td></tr>
        <tr><td align="right"><em>moveRelativeToBookmark</em></td><td align="center">X</td><td></td><td align="center">X</td><td align="center">X</td><td></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 com::sun::star::sdbc::XResultSetUpdate::deleteRow(), you can delete the current row of a
    RowSet. This deleted row then doesn't vanish immediately, but is still present, and subsequent calls to
    com::sun::star::sdbc::XResultSet::rowDeleted() will return `TRUE`. The deleted row "vanishes" from
    the RowSet as soon as the cursor is moved away from it.<br>
    As a consequence, the behavior of several other methods is affected:<br>
    <dl>
        <dt>com::sun::star::sdbc::XResultSet::getRow()</dt>
        <dd>returns the position of the cursor, which has not been changed by the deletion.</dd>

        <dt>com::sun::star::sdbc::XResultSet: <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 #RowCount
            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 RowSet afterwards
            still is on row 15, since the deleted row vanished with the move operation.</dd>

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

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

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

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

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

        <dt>com::sun::star::sdbc::XResultSetUpdate::moveToInsertRow()</dt>
        <dd>will let the deleted row vanish from the result set. As a consequence, the #RowCount
            will decrease. Also, subsequent calls to
            com::sun::star::sdbc::XResultSetUpdate::moveToCurrentRow() 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 com::sun::star::sdbc::XParameters interface.<br>
        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.
        The default implementation will only ask for parameters which aren't set before through the com::sun::star::sdbc::XParameters interface.</p>

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

    /** approving of actions performed on the row set.

        <p>The support of this interface implies a semantical extension to the com::sun::star::sdbc::XResultSetUpdate
        interface which is supported via the com::sun::star::sdbc::ResultSet.</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 com::sun::star::sdbc::ResultSet service.</p>

        <p>However, note that the additional support of the XRowSetApproveBroadcaster interface results
        in a semantical extension: the methods com::sun::star::sdbc::XResultSetUpdate::insertRow(),
        com::sun::star::sdbc::XResultSetUpdate::updateRow() and com::sun::star::sdbc::XResultSetUpdate::deleteRow()
        will now throw the RowSetVetoException if the action which is to be performed was vetoed
        by one of the XRowSetApproveListener'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 com::sun::star::sdbcx::ResultSet service.</p>

        <p>However, note that the additional support of the XRowSetApproveBroadcaster interface results
        in a semantical extension: the method com::sun::star::sdbcx::XDeleteRows::deleteRows()
        will now throw the RowSetVetoException if the deletion was vetoed
        by one of the XRowSetApproveListener'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 #Filter or #Order 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 com::sun::star::sdbc::XParameters interface inherited from
        com::sun::star::sdbc::RowSet). 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 #CommandType of CommandType::COMMAND,
        means in case the #Command specifies an SQL statement, the inherited
        com::sun::star::sdbc::RowSet::EscapeProcessing
        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 com::sun::star::sdbc::RowSet::EscapeProcessing
        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 row set.
     */
    [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 row set.
     */
    [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 the 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

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */