xref: /trunk/main/offapi/com/sun/star/sdbc/XResultSet.idl (revision d1766043) 
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