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