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_sdbcx_XRowLocate_idl__
24#define __com_sun_star_sdbcx_XRowLocate_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 sdbcx {
35
36
37/** is used to identify rows within a result set and to find rows by a bookmark.
38
39
40	<p>
41	Bookmarks are only valid in the scope of the current result set and
42	are not interchangeable between result sets. A bookmark could be a complex data
43	structure, so it could not be compared in a safe way. Because of that, a provider
44	has to implement the compare method for bookmarks.
45	</p>
46 */
47published interface XRowLocate: com::sun::star::uno::XInterface
48{
49
50	/** returns the bookmark of the current row of a result set.
51		@returns
52			the current bookmark
53		@throws com::sun::star::sdbc::SQLException
54			if a database access error occurs.
55	 */
56	any getBookmark() raises (com::sun::star::sdbc::SQLException);
57	//-------------------------------------------------------------------------
58
59	/** moves the cursor to the row identified by an valid bookmark.
60
61		<p>
62		If the bookmark could not be located, a result set will be positioned
63		after the last record.
64		<br/>
65		If the bookmark is invalid, or not generated by the current result set, then
66		the behaviour is not defined, even an abnormal termination is possible.
67		</p>
68		@param bookmark
69			the bookmark where to move
70		@returns
71			<TRUE/> if successful
72		@throws com::sun::star::sdbc::SQLException
73			if a database access error occurs.
74	 */
75	boolean moveToBookmark([in]any bookmark) raises (com::sun::star::sdbc::SQLException);
76    //-------------------------------------------------------------------------
77
78	/** moves the cursor a relative number of rows, either positive or negative
79		starting at a given bookmark position.
80
81
82		<p>
83		If the bookmark could not be located, a result set will be positioned
84		after the last record.
85		<br/>
86		If the bookmark is invalid, or not generated by the current result set, then
87		the behaviour is not defined, even an abnormal termination is possible.
88		</p>
89		@param bookmark
90			the bookmark where to move
91		@param rows
92			count of rows move relative to the bookmark
93		@returns
94			<TRUE/> if successful
95		@throws com::sun::star::sdbc::SQLException
96			if a database access error occurs.
97	 */
98	boolean moveRelativeToBookmark([in]any bookmark, [in]long rows)
99		raises (com::sun::star::sdbc::SQLException);
100	//-------------------------------------------------------------------------
101
102	/** compares two bookmarks and returns an indication of their relative values.
103
104		<p>
105		The bookmarks must apply to the same ResultSet. You cannot reliably
106		compare bookmarks from different ResultSets, even if they were created from
107		the same source or statement.
108		<br/>
109		A bookmark that is not valid, or incorrectly formed, will cause an exception.
110		</p>
111		@param first
112			the first bookmark
113		@param second
114			the second bookmark
115		@returns
116			a value of <type scope="com::sun::star::sdbcx">CompareBookmark</type>
117		@throws com::sun::star::sdbc::SQLException
118			if a database access error occurs.
119
120		@see com::sun::star::sdbcx::CompareBookmark
121
122	 */
123	long compareBookmarks([in]any first, [in]any second)
124		raises (com::sun::star::sdbc::SQLException);
125    //-------------------------------------------------------------------------
126
127	/** determines whether the bookmarks of a result set are ordered or not.
128		@returns
129			<TRUE/> if so
130		@throws com::sun::star::sdbc::SQLException
131			if a database access error occurs.
132		@see com::sun::star::sdbcx::CompareBookmark
133	 */
134	boolean hasOrderedBookmarks() raises (com::sun::star::sdbc::SQLException);
135    //-------------------------------------------------------------------------
136
137	/** returns the hash value for a specified bookmark.
138		@param bookmark
139			the bookmark to hash
140		@returns
141			the hashed value
142		@throws com::sun::star::sdbc::SQLException
143			if a database access error occurs.
144	 */
145	long hashBookmark([in]any bookmark) raises (com::sun::star::sdbc::SQLException);
146};
147
148//=============================================================================
149
150}; }; }; };
151
152/*===========================================================================
153===========================================================================*/
154#endif
155