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

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