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_ucb_ContentResultSet_idl__
24#define __com_sun_star_ucb_ContentResultSet_idl__
25
26#ifndef __com_sun_star_lang_XComponent_idl__
27#include <com/sun/star/lang/XComponent.idl>
28#endif
29
30#ifndef __com_sun_star_beans_XPropertySet_idl__
31#include <com/sun/star/beans/XPropertySet.idl>
32#endif
33
34#ifndef __com_sun_star_sdbc_XResultSet_idl__
35#include <com/sun/star/sdbc/XResultSet.idl>
36#endif
37
38#ifndef __com_sun_star_sdbc_XResultSetMetaDataSupplier_idl__
39#include <com/sun/star/sdbc/XResultSetMetaDataSupplier.idl>
40#endif
41
42#ifndef __com_sun_star_sdbc_XRow_idl__
43#include <com/sun/star/sdbc/XRow.idl>
44#endif
45
46#ifndef __com_sun_star_sdbc_XCloseable_idl__
47#include <com/sun/star/sdbc/XCloseable.idl>
48#endif
49
50#ifndef __com_sun_star_ucb_XContentAccess_idl__
51#include <com/sun/star/ucb/XContentAccess.idl>
52#endif
53
54#ifndef __com_sun_star_sdbc_ResultSet_idl__
55#include <com/sun/star/sdbc/ResultSet.idl>
56#endif
57
58//=============================================================================
59
60module com { module sun { module star { module ucb {
61
62//=============================================================================
63/** provides access to the children of a folder content.
64
65    <p>It can be understand as a table containing a row for	each child. The
66	table columns may contain values of properties of the children.
67*/
68published service ContentResultSet
69{
70	//-------------------------------------------------------------------------
71	/** must be implemented to make it possible to resolve cyclic object
72	    references ( i.e. between an implementation of
73		<type scope="com::sun::star::beans">XPropertySet</type>
74		- which may	hold property change listeners - and
75		<type scope="com::sun::star::beans">XPropertyChangeListener</type>
76		- which may hold the property set ).
77
78		<p>This interface is required.
79	 */
80	interface com::sun::star::lang::XComponent;
81
82	/** provides access to the result set meta data. Meta data are for
83	    example the number of columns of the result set, information
84		on the data types of columns, column names, and more.
85
86		<p>This interface is required.
87	 */
88	interface com::sun::star::sdbc::XResultSetMetaDataSupplier;
89
90	//-------------------------------------------------------------------------
91	/** enables travelling through the result set members ( the contents ).
92		This interface mainly provides a cursor for the result set.
93
94		<p>Note that every method of this interface implementation additionally
95		may throw a	<type>ResultSetException</type> ( which is derived from
96		<type scope="com::sun::star::sdbc">SQLException</type> to be compatible
97		to that interface ). The new exception transports another exception,
98		which indicates the reason for the failure of the method call.
99
100		<p>This interface is required.
101	 */
102	interface com::sun::star::sdbc::XResultSet;
103
104	//-------------------------------------------------------------------------
105	/**	provides access to data of the content the cursor is pointing to.
106
107		<p>Note that every method of this interface implementation additionally
108		may throw a	<type>ResultSetException</type> ( which is derived from
109		<type scope="com::sun::star::sdbc">SQLException</type> to be compatible
110		to that interface ). The new exception transports another exception,
111		which indicates the reason for the failure of the method call.
112
113		<p>This interface is required.
114	 */
115	interface com::sun::star::sdbc::XRow;
116
117	//-------------------------------------------------------------------------
118	/** makes it possible to abort running activities ( i.e. to cancel
119	    retrieving data from a server ).
120
121		<p>Note that every method of this interface implementation additionally
122		may throw a	<type>ResultSetException</type> ( which is derived from
123		<type scope="com::sun::star::sdbc">SQLException</type> to be compatible
124		to that interface ). The new exception transports another exception,
125		which indicates the reason for the failure of the method call.
126
127		<p>This interface is required.
128	 */
129	interface com::sun::star::sdbc::XCloseable;
130
131	//-------------------------------------------------------------------------
132	/** holds properties of the resultset.
133
134		<p>This interface is required.
135	 */
136	interface com::sun::star::beans::XPropertySet;
137
138	//-------------------------------------------------------------------------
139	/** controls the travel mode of the resultset cursor.
140
141		<p>There are two possible travel modes:
142
143		<p><table border=1>
144		<tr><td><member>CursorTravelMode::BLOCKING</member></td>
145			<td>Each travel method of the resultset will not return until the
146			    data for the new position were retrieved.</td></tr>
147		<tr><td><member>CursorTravelMode::NONBLOCKING</member></td>
148			<td>The implementation will throw a
149				<code>CursorWouldBlockException</code>, if the data for the new
150				position are not retrieved yet.</td></tr>
151		</table>
152
153		<p>The following pseudo-code illustrates the usage of a non-blocking
154		cursor:
155
156		<p><pre>
157    	bProcessedAllRows = false
158    	while ( !bProcessedAllRows )
159    	{
160        	cursor.setPropertyValue( "CursorTravelMode", BLOCKING )
161
162        	cursor.travelSomeWhere()
163        	collectRowData()
164
165        	cursor.setPropertyValue( "CursorTravelMode", NONBLOCKING )
166
167        	bGoOn = true;
168        	while ( bGoOn )
169        	{
170            	try
171            	{
172                	cursor.travelSomeWhere()
173                	collectRowData()
174            	}
175            	catch ( CursorWouldBlockException )
176            	{
177                	// No more data at the moment.
178               	bGoOn = false
179            	}
180        	}
181
182        	doSomethingWithCollectedRowData()
183
184        	bProcessedAllRows = ...
185    	}
186		</pre>
187
188		<p>
189	 	If this property is not supported, the implementation needs to provide
190		a blocking cursor.
191		</p>
192
193		<p>
194		The implementation initially needs to set the value of this property
195		to <member>CursorTravelMode::BLOCKING</member>.
196		</p>
197
198		@see CursorTravelMode
199	 */
200	[optional, property] long CursorTravelMode;
201
202	/** contains the number of rows obtained (so far) from the data source. */
203	[readonly, property] long RowCount;
204
205	/** indicates that all rows of te resultset have been obtained. */
206	[readonly, property] boolean IsRowCountFinal;
207
208	//-------------------------------------------------------------------------
209	/**	provides access to the content identifier and the content object
210		itself.
211
212		<p>This interface is required.
213	 */
214	interface XContentAccess;
215
216	//-------------------------------------------------------------------------
217	/** can be implemented to provide a complete JDBC conform result set
218		interface for the implementation of this service.
219
220		<p>The implememtation of this service is optional.
221	 */
222	service com::sun::star::sdbc::ResultSet;
223};
224
225//=============================================================================
226
227}; }; }; };
228
229#endif
230