| /************************************************************** |
| * |
| * 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 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| #ifndef __com_sun_star_sdb_RowSet_idl__ |
| #define __com_sun_star_sdb_RowSet_idl__ |
| |
| #ifndef __com_sun_star_sdbc_RowSet_idl__ |
| #include <com/sun/star/sdbc/RowSet.idl> |
| #endif |
| |
| module com { module sun { module star { module sdbc { |
| published interface XConnection; |
| };};};}; |
| |
| #ifndef __com_sun_star_sdb_ResultSet_idl__ |
| #include <com/sun/star/sdb/ResultSet.idl> |
| #endif |
| |
| #ifndef __com_sun_star_sdb_XCompletedExecution_idl__ |
| #include <com/sun/star/sdb/XCompletedExecution.idl> |
| #endif |
| |
| 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 rowset reader, who mustn't support SQL. |
| The connection of the rowset is typically a named DataSource or a DataAccess component |
| or a previous instanciated connection. |
| <p> |
| Depending on the |
| <type scope="com::sun::star::sdbc">ResultSetConcurrency</type> |
| , 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 |
| <member>XRowSetApproveListener::approveCursorMove</member> or |
| <member>XRowSetApproveListener::approveRowChange</member> call. |
| @see XRowSetApproveListener |
| </td> |
| </tr> |
| <tr><td valign="top"><em>column values</em></td> |
| <td valign="top">If the opration 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 |
| <member scope="com::sun::star::sdbc">XRowSetListener::cursorMoved</member> or a |
| <member scope="com::sun::star::sdbc">XRowSetListener::rowChanged</member> call or a |
| <member>XRowsChangeListener::rowsChanged</member> 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 <member>IsModified</member> |
| and/or <member>IsNew</member> 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 <member>RowCount</member> and <member>IsRowCountFinal</member> |
| 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><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><type scope="com::sun::star::sdbc">XResultSet</type></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 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><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> |
| <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> |
| <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> |
| <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> |
| <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> |
| <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> |
| <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> |
| <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> |
| <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> |
| |
| <tr><td><type scope="com::sun::star::sdbc">XResultSetUpdate</type></td><td/><td/><td/><td/><td/><td/><td/><td/></tr> |
| |
| <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> |
| <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> |
| <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> |
| <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> |
| <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> |
| |
| <tr><td><type scope="com::sun::star::sdbcx">XDeleteRows</type></td><td/><td/><td/><td/><td/><td/><td/><td/></tr> |
| |
| <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> |
| |
| <tr><td><type scope="com::sun::star::sdbcx">XRowLocate</type></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 align="center">X</td><td align="center">X</td><td/><td/><td align="center">X</td><td align="center">X</td><td/><td/></tr> |
| <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> |
| |
| </tr> |
| </table> |
| </p> |
| |
| <h3>Deletions</h3> |
| <p>Via <member scope="com::sun::star::sdbc">XResultSetUpdate::deleteRow</member>, you can delete the current row of a |
| <type>RowSet</type>. This deleted row then doesn't vanish immediately, but is still present, and subsequent calls to |
| <member scope="com::sun::star::sdbc">XResultSet::rowDeleted</member> will return <TRUE/>. The deleted row "vanishes" from |
| the <type>RowSet</type> as soon as the cursor is moved away from it.<br/> |
| As a consequence, the behaviour of several other methods is affected:<br/> |
| <dl> |
| <dt><member scope="com::sun::star::sdbc">XResultSet::getRow</member></dt> |
| <dd>returns the position of the cursor, which has not been changed by the deletion.</dd> |
| |
| <dt><type scope="com::sun::star::sdbc">XResultSet</type>: <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 <member>RowCount</member> |
| 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 <type>RowSet</type> afterwards |
| still is on row 15, since the deleted row vanished with the move operation.</dd> |
| |
| <dt><member scope="com::sun::star::sdbc">XResultSet::refreshRow</member></dt> |
| <dd>will throw an exception when the cursor is on a deleted row.</dd> |
| |
| <dt><type scope="com::sun::star::sdbc">XRow</type>: <code>getFoo</code></dt> |
| <dd>will return an empty value when the cursor is on a deleted row.</dd> |
| |
| <dt><member scope="com::sun::star::sdbcx">XRowLocate::getBookmark</member></dt> |
| <dd>will throw an exception when the cursor is on a deleted row.</dd> |
| |
| <dt><type scope="com::sun::star::sdbc">XRowUpdate</type>: <code>updateFoo</code></dt> |
| <dd>will throw an exception when the cursor is on a deleted row.</dd> |
| |
| <dt><member scope="com::sun::star::sdbc">XResultSetUpdate::deleteRow</member></dt> |
| <dd>will throw an exception when the cursor is on a deleted row.</dd> |
| |
| <dt><member scope="com::sun::star::sdbc">XResultSetUpdate::moveToInsertRow</member></dt> |
| <dd>will let the deleted row vanish from the result set. As a consequence, the <member>RowCount</member> |
| will decrease. Also, subsequent calls to |
| <member scope="com::sun::star::sdbc">XResultSetUpdate::moveToCurrentRow</member> 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 <type scope="com::sun::star::sdbc">XParameters</type> interface.<br/> |
| However, you can also choose to let an interaction handler supply such data. For this, you may |
| for instance instantiate an <type>InteractionHandler</type>, 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 <type scope="com::sun::star::sdbc">XParameters</type> interface.</p> |
| |
| @see com::sun::star::sdb::InteractionHandler |
| */ |
| interface com::sun::star::sdb::XCompletedExecution; |
| |
| /** approving of actions performed on the rowset. |
| |
| <p>The support of this interface implies a sematical extension to the <type scope="com::sun::star::sdbc">XResultSetUpdate</type> |
| interface which is supported via the <type scope="com::sun::star::sdbc">ResultSet</type>.</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 <type scope="com::sun::star::sdbc">ResultSet</type> service.</p> |
| |
| <p>However, note that the additional support of the <type>XRowSetApproveBroadcaster</type> interface results |
| in a sematical extension: the methods <member scope="com::sun::star::sdbc">XResultSetUpdate::insertRow</member>, |
| <member scope="com::sun::star::sdbc">XResultSetUpdate::updateRow</member> and <member scope="com::sun::star::sdbc">XResultSetUpdate::deleteRow</member> |
| will now throw the <type>RowSetVetoException</type> if the action which is to be performed was vetoed |
| by one of the <type>XRowSetApproveListener</type>'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 <type scope="com::sun::star::sdbcx">ResultSet</type> service.</p> |
| |
| <p>However, note that the additional support of the <type>XRowSetApproveBroadcaster</type> interface results |
| in a sematical extension: the method <member scope="com::sun::star::sdbcx">XDeleteRows::deleteRows</member> |
| will now throw the <type>RowSetVetoException</type> if the deletion was vetoed |
| by one of the <type>XRowSetApproveListener</type>'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 <member>Filter</member> or <member>Order</member> 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 <type scope="com::sun::star::sdbc">XParameters</type> interface inherited from |
| <type scope="com::sun::star::sdbc">RowSet</type>). 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 <member>CommandType</member> of <member>CommandType::COMMAND</member>, |
| means in case the <member>Command</member> specifies an SQL statement, the inherited |
| <member scope="com::sun::star::sdbc">RowSet::EscapeProcessing</member> |
| 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 <member scope="com::sun::star::sdbc">RowSet::EscapeProcessing</member> |
| 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 rowset. |
| */ |
| [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 rowset. |
| */ |
| [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 te 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 |