INTEGRATION: CWS rowsetdel (1.19.62); FILE MERGED

2006/01/19 08:26:18 fs 1.19.62.1: #i55731# extended the documentation to cover deletions of rows

1 files changed, 50 insertions, 9 deletions

diff --git a/offapi/com/sun/star/sdb/RowSet.idl b/offapi/com/sun/star/sdb/RowSet.idl
index 9c7124b512fb..7a655ae2f560 100644
--- a/offapi/com/sun/star/sdb/RowSet.idl
+++ b/offapi/com/sun/star/sdb/RowSet.idl
@@ -4,9 +4,9 @@
  *
  *  $RCSfile: RowSet.idl,v $
  *
- *  $Revision: 1.19 $
+ *  $Revision: 1.20 $
  *
- *  last change: $Author: rt $ $Date: 2005-09-08 03:23:12 $
+ *  last change: $Author: hr $ $Date: 2006-01-25 15:03:48 $
  *
  *  The Contents of this file are made available subject to
  *  the terms of GNU Lesser General Public License Version 2.1.
@@ -39,7 +39,7 @@
 #include <com/sun/star/sdbc/RowSet.idl>
 #endif
 
- module com {  module sun {  module star {  module sdbc {
+module com {  module sun {  module star {  module sdbc {
 published interface XConnection;
 };};};};
 
@@ -79,8 +79,8 @@ published interface XResultSetAccess;
     @see com::sun::star::sdb::RowChangeEvent
     </p>
 
-    <p><strong>Notifications</strong><br/>
-    A row set is able to be operated in various ways, and additionally it notifies various changes in it's
+    <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
@@ -141,7 +141,7 @@ published interface XResultSetAccess;
         <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 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 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 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 align="center">X</td><td align="center">X</td><td/><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 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 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 align="center">X</td><td/><td/><td/></tr>
 
@@ -150,7 +150,7 @@ published interface XResultSetAccess;
         <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></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/><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></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 align="center">X</td><td/><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 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 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>
@@ -166,6 +166,47 @@ published interface XResultSetAccess;
     </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
 {
@@ -196,7 +237,7 @@ published service RowSet
 
     /** 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>.</p>
+        <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>,
@@ -208,7 +249,7 @@ published service RowSet
 
     /** 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>.</p>
+        <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>