summaryrefslogtreecommitdiffstats
path: root/offapi/com/sun/star/sdb/RowSet.idl
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 09:06:44 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 09:06:44 +0000
commited5640d8b587fbcfed7dd7967f3de04b37a76f26 (patch)
tree7a5f7c6c9d02226d7471cb3cc8fbbf631b415303 /offapi/com/sun/star/sdb/RowSet.idl
parentInitial commit. (diff)
downloadlibreoffice-ed5640d8b587fbcfed7dd7967f3de04b37a76f26.tar.xz
libreoffice-ed5640d8b587fbcfed7dd7967f3de04b37a76f26.zip
Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'offapi/com/sun/star/sdb/RowSet.idl')
-rw-r--r--offapi/com/sun/star/sdb/RowSet.idl385
1 files changed, 385 insertions, 0 deletions
diff --git a/offapi/com/sun/star/sdb/RowSet.idl b/offapi/com/sun/star/sdb/RowSet.idl
new file mode 100644
index 000000000..69ecef300
--- /dev/null
+++ b/offapi/com/sun/star/sdb/RowSet.idl
@@ -0,0 +1,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 its
+ 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 an 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 its 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 an 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 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: */