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

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