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