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