offapi/com/sun/star/sdbc/XResultSet.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27 #ifndef __com_sun_star_sdbc_XResultSet_idl__
  28 #define __com_sun_star_sdbc_XResultSet_idl__
  29
  30 #ifndef __com_sun_star_uno_XInterface_idl__
  31 #include <com/sun/star/uno/XInterface.idl>
  32 #endif
  33
  34 #ifndef __com_sun_star_sdbc_SQLException_idl__
  35 #include <com/sun/star/sdbc/SQLException.idl>
  36 #endif
  37
  38  module com {  module sun {  module star {  module sdbc {
  39
  40  published interface XStatement;
  41
  42
  43 /** provides the navigation on a table of data.  A
  44     <type scope="com::sun::star::sdbc">ResultSet</type>
  45     object is usually generated by executing a
  46     <type scope="com::sun::star::sdbc">Statement</type>
  47     .
  48
  49
  50     <p>
  51     A ResultSet maintains a cursor pointing to its current row of
  52     data. Initially the cursor is positioned before the first row.
  53     The 'next' method moves the cursor to the next row.
  54     </p>
  55  */
  56 published interface XResultSet: com::sun::star::uno::XInterface
  57 {
  58     //-------------------------------------------------------------------------
  59
  60     /** moves the cursor down one row from its current position.
  61
  62
  63         <p>
  64         A ResultSet cursor is initially positioned before the first row; the
  65         first call to next makes the first row the current row; the
  66         second call makes the second row the current row, and so on.
  67         </p>
  68         <p>If an input stream is open for the current row, a call
  69         to the method
  70         <code>next</code>
  71         will implicitly close it.
  72         The ResultSet's warning chain is cleared when a new row is read.
  73         </p>
  74         @returns
  75          <TRUE/> if successful
  76         @throws SQLException
  77             if a database access error occurs.
  78      */
  79     boolean next() raises (SQLException);
  80     //-------------------------------------------------------------------------
  81
  82     /** indicates whether the cursor is before the first row in the result
  83         set.
  84         @returns
  85          <TRUE/> if so
  86         @throws SQLException
  87             if a database access error occurs.
  88      */
  89     boolean isBeforeFirst() raises (SQLException);
  90     //-------------------------------------------------------------------------
  91
  92     /** indicates whether the cursor is after the last row in the result
  93         set.
  94         @returns
  95          <TRUE/> if so
  96         @throws SQLException
  97             if a database access error occurs.
  98      */
  99     boolean isAfterLast() raises (SQLException);
 100     //-------------------------------------------------------------------------
 101
 102     /** indicates whether the cursor is on the first row of the result set.
 103         @returns
 104          <TRUE/> if so
 105         @throws SQLException
 106             if a database access error occurs.
 107      */
 108     boolean isFirst() raises (SQLException);
 109     //-------------------------------------------------------------------------
 110
 111     /** indicates whether the cursor is on the last row of the result set.
 112
 113
 114         <p>
 115         <B>
 116         Note:
 117         </B>
 118         Calling the method
 119         <code>isAtLast</code>
 120         may be expensive because the SDBC driver might need to fetch ahead one row in order
 121         to determine whether the current row is the last row in the result set.
 122         </p>
 123         @returns
 124          <TRUE/> if so
 125         @throws SQLException
 126             if a database access error occurs.
 127      */
 128     boolean isLast() raises (SQLException);
 129     //-------------------------------------------------------------------------
 130
 131     /** moves the cursor to the front of the result set, just before the
 132         first row. Has no effect if the result set contains no rows.
 133         @throws SQLException
 134             if a database access error occurs.
 135      */
 136     void beforeFirst() raises (SQLException);
 137     //-------------------------------------------------------------------------
 138
 139     /** moves the cursor to the end of the result set, just after the last
 140         row. Has no effect if the result set contains no rows.
 141         @throws SQLException
 142             if a database access error occurs.
 143      */
 144     void afterLast() raises (SQLException);
 145     //-------------------------------------------------------------------------
 146
 147     /** moves the cursor to the first row in the result set.
 148         @returns
 149          <TRUE/> if successful
 150         @throws SQLException
 151             if a database access error occurs.
 152      */
 153     boolean first() raises (SQLException);
 154     //-------------------------------------------------------------------------
 155
 156     /** moves the cursor to the last row in the result set.
 157         @returns
 158          <TRUE/> if successful
 159         @throws SQLException
 160             if a database access error occurs.
 161      */
 162     boolean last() raises (SQLException);
 163     //-------------------------------------------------------------------------
 164
 165     /** retrieves the current row number. The first row is number 1, the
 166         second number 2, and so on.
 167         @returns
 168          the current position
 169         @throws SQLException
 170             if a database access error occurs.
 171      */
 172     long getRow() raises (SQLException);
 173     //-------------------------------------------------------------------------
 174
 175     /** moves the cursor to the given row number in the result set.
 176
 177
 178         <p>
 179         If the row number is positive, the cursor moves to
 180         the given row number with respect to the
 181         beginning of the result set. The first row is row 1, the second
 182         is row 2, and so on.
 183         </p>
 184         <p>
 185         If the given row number is negative, the cursor moves to
 186         an absolute row position with respect to
 187         the end of the result set. For example, calling
 188         <code>absolute(-1)</code>
 189         positions the
 190         cursor on the last row,
 191         <code>absolute(-2)</code>
 192         indicates the next-to-last row, and so on.
 193         </p>
 194         <p>
 195         An attempt to position the cursor beyond the first/last row in
 196         the result set leaves the cursor before/after the first/last
 197         row, respectively.
 198         </p>
 199         <p>
 200         Note: Calling
 201         <code>absolute(1)</code>
 202         is the same
 203         as calling
 204         <member scope="com::sun::star::sdbc">XResultSet::first()</member>
 205         .
 206         Calling <code>moveToPosition(-1)</code> is the same as calling
 207         <code>moveToLast()</code>.
 208         </p>
 209      */
 210     boolean absolute([in] long row ) raises (SQLException);
 211     //-------------------------------------------------------------------------
 212
 213     /** moves the cursor a relative number of rows, either positive or negative.
 214
 215
 216         <p>
 217         Attempting to move beyond the first/last row in the result set
 218         positions the cursor before/after
 219         the first/last row. Calling
 220         <code>relative(0)</code>
 221         is valid, but does not change the cursor position.
 222         </p>
 223         <p>
 224         Note: Calling
 225         <code>relative(1)</code>
 226         is different from calling
 227         <member scope="com::sun::star::sdbc">XResultSet::next()</member>
 228         because is makes sense to call
 229         <code>next()</code>
 230         when there is no current row, for example, when the cursor is positioned before
 231         the first row or after the last row of the result set.
 232         </p>
 233         @param rows
 234             how many rows should be moved relative to the current row
 235         @returns
 236          <TRUE/> if successful
 237         @throws SQLException
 238             if a database access error occurs.
 239      */
 240     boolean relative([in]long rows) raises (SQLException);
 241     //-------------------------------------------------------------------------
 242
 243     /** moves the cursor to the previous row in the result set.
 244
 245
 246         <p>
 247         Note:
 248         <code>previous()</code>
 249         is not the same as
 250         <code>relative(-1)</code>
 251         because it makes sense to call
 252         <code>previous()</code>
 253         when there is no current row.
 254         </p>
 255         @returns
 256             <TRUE/> if successful
 257         @throws SQLException
 258             if a database access error occurs.
 259      */
 260     boolean previous() raises (SQLException);
 261     //-------------------------------------------------------------------------
 262
 263     /** refreshes the current row with its most recent value in
 264         the database. Cannot be called when on the insert row.
 265         The
 266         <code>refreshRow</code>
 267         method provides a way for an application to
 268         explicitly tell the SDBC driver to refetch a row(s) from the
 269         database. An application may want to call
 270         <code>refreshRow</code>
 271         when caching or prefetching is being done by the SDBC driver to
 272         fetch the latest value of a row from the database. The SDBC driver
 273         may actually refresh multiple rows at once if the fetch size is
 274         greater than one.
 275         All values are refetched subject to the transaction isolation
 276         level and cursor sensitivity. If
 277         <code>refreshRow</code>
 278         is called after calling
 279         <code>updateXXX</code>
 280         , but before calling
 281         <member scope="com::sun::star::sdbc">XResultSet::updateRow()</member>
 282         , then the updates made to the row are lost.
 283         Calling the method
 284         <code>refreshRow</code>
 285         frequently will likely slow performance.
 286         @throws SQLException
 287             if a database access error occurs.
 288      */
 289     void refreshRow() raises (SQLException);
 290     //-------------------------------------------------------------------------
 291
 292     /** indicates whether the current row has been updated. The value returned
 293         depends on whether or not the result set can detect updates.
 294         @returns
 295             <TRUE/> if successful
 296         @throws SQLException
 297             if a database access error occurs.
 298      */
 299     boolean rowUpdated() raises (SQLException);
 300     //-------------------------------------------------------------------------
 301
 302     /** indicates whether the current row has had an insertion.  The value returned
 303         depends on whether or not the result set can detect visible inserts.
 304         @returns
 305             <TRUE/> if successful
 306         @throws SQLException
 307             if a database access error occurs.
 308      */
 309     boolean rowInserted() raises (SQLException);
 310     //-------------------------------------------------------------------------
 311
 312     /** indicates whether a row has been deleted.  A deleted row may leave
 313         a visible "hole" in a result set.  This method can be used to
 314         detect holes in a result set.  The value returned depends on whether
 315         or not the result set can detect deletions.
 316         @returns
 317             <TRUE/> if successful
 318         @throws SQLException
 319             if a database access error occurs.
 320      */
 321     boolean rowDeleted() raises (SQLException);
 322     //-------------------------------------------------------------------------
 323
 324     /** returns the Statement that produced this
 325         <type scope="com::sun::star::sdbc">ResultSet</type>
 326         object. If the result set was generated some other way, such as by an
 327         <type scope="com::sun::star::sdbc">XDatabaseMetaData</type>
 328         method, this method returns
 329         <NULL/>
 330         .
 331         @returns
 332             the statement object
 333         @throws SQLException
 334             if a database access error occurs.
 335      */
 336     com::sun::star::uno::XInterface getStatement() raises (SQLException);
 337 };
 338
 339 //=============================================================================
 340
 341 }; }; }; };
 342
 343 /*===========================================================================
 344 ===========================================================================*/
 345 #endif