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