offapi/com/sun/star/ucb/ContentResultSet.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: ContentResultSet.idl,v $
  10  * $Revision: 1.13 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_ucb_ContentResultSet_idl__
  31 #define __com_sun_star_ucb_ContentResultSet_idl__
  32
  33 #ifndef __com_sun_star_lang_XComponent_idl__
  34 #include <com/sun/star/lang/XComponent.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_beans_XPropertySet_idl__
  38 #include <com/sun/star/beans/XPropertySet.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_sdbc_XResultSet_idl__
  42 #include <com/sun/star/sdbc/XResultSet.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_sdbc_XResultSetMetaDataSupplier_idl__
  46 #include <com/sun/star/sdbc/XResultSetMetaDataSupplier.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_sdbc_XRow_idl__
  50 #include <com/sun/star/sdbc/XRow.idl>
  51 #endif
  52
  53 #ifndef __com_sun_star_sdbc_XCloseable_idl__
  54 #include <com/sun/star/sdbc/XCloseable.idl>
  55 #endif
  56
  57 #ifndef __com_sun_star_ucb_XContentAccess_idl__
  58 #include <com/sun/star/ucb/XContentAccess.idl>
  59 #endif
  60
  61 #ifndef __com_sun_star_sdbc_ResultSet_idl__
  62 #include <com/sun/star/sdbc/ResultSet.idl>
  63 #endif
  64
  65 //=============================================================================
  66
  67 module com { module sun { module star { module ucb {
  68
  69 //=============================================================================
  70 /** provides access to the children of a folder content.
  71
  72     <p>It can be understand as a table containing a row for     each child. The
  73     table columns may contain values of properties of the children.
  74 */
  75 published service ContentResultSet
  76 {
  77     //-------------------------------------------------------------------------
  78     /** must be implemented to make it possible to resolve cyclic object
  79         references ( i.e. between an implementation of
  80         <type scope="com::sun::star::beans">XPropertySet</type>
  81         - which may     hold property change listeners - and
  82         <type scope="com::sun::star::beans">XPropertyChangeListener</type>
  83         - which may hold the property set ).
  84
  85         <p>This interface is required.
  86      */
  87     interface com::sun::star::lang::XComponent;
  88
  89     /** provides access to the result set meta data. Meta data are for
  90         example the number of columns of the result set, information
  91         on the data types of columns, column names, and more.
  92
  93         <p>This interface is required.
  94      */
  95     interface com::sun::star::sdbc::XResultSetMetaDataSupplier;
  96
  97     //-------------------------------------------------------------------------
  98     /** enables travelling through the result set members ( the contents ).
  99         This interface mainly provides a cursor for the result set.
 100
 101         <p>Note that every method of this interface implementation additionally
 102         may throw a     <type>ResultSetException</type> ( which is derived from
 103         <type scope="com::sun::star::sdbc">SQLException</type> to be compatible
 104         to that interface ). The new exception transports another exception,
 105         which indicates the reason for the failure of the method call.
 106
 107         <p>This interface is required.
 108      */
 109     interface com::sun::star::sdbc::XResultSet;
 110
 111     //-------------------------------------------------------------------------
 112     /** provides access to data of the content the cursor is pointing to.
 113
 114         <p>Note that every method of this interface implementation additionally
 115         may throw a     <type>ResultSetException</type> ( which is derived from
 116         <type scope="com::sun::star::sdbc">SQLException</type> to be compatible
 117         to that interface ). The new exception transports another exception,
 118         which indicates the reason for the failure of the method call.
 119
 120         <p>This interface is required.
 121      */
 122     interface com::sun::star::sdbc::XRow;
 123
 124     //-------------------------------------------------------------------------
 125     /** makes it possible to abort running activities ( i.e. to cancel
 126         retrieving data from a server ).
 127
 128         <p>Note that every method of this interface implementation additionally
 129         may throw a     <type>ResultSetException</type> ( which is derived from
 130         <type scope="com::sun::star::sdbc">SQLException</type> to be compatible
 131         to that interface ). The new exception transports another exception,
 132         which indicates the reason for the failure of the method call.
 133
 134         <p>This interface is required.
 135      */
 136     interface com::sun::star::sdbc::XCloseable;
 137
 138     //-------------------------------------------------------------------------
 139     /** holds properties of the resultset.
 140
 141         <p>This interface is required.
 142      */
 143     interface com::sun::star::beans::XPropertySet;
 144
 145     //-------------------------------------------------------------------------
 146     /** controls the travel mode of the resultset cursor.
 147
 148         <p>There are two possible travel modes:
 149
 150         <p><table border=1>
 151         <tr><td><member>CursorTravelMode::BLOCKING</member></td>
 152             <td>Each travel method of the resultset will not return until the
 153                 data for the new position were retrieved.</td></tr>
 154         <tr><td><member>CursorTravelMode::NONBLOCKING</member></td>
 155             <td>The implementation will throw a
 156                 <code>CursorWouldBlockException</code>, if the data for the new
 157                 position are not retrieved yet.</td></tr>
 158         </table>
 159
 160         <p>The following pseudo-code illustrates the usage of a non-blocking
 161         cursor:
 162
 163         <p><pre>
 164         bProcessedAllRows = false
 165         while ( !bProcessedAllRows )
 166         {
 167             cursor.setPropertyValue( "CursorTravelMode", BLOCKING )
 168
 169             cursor.travelSomeWhere()
 170             collectRowData()
 171
 172             cursor.setPropertyValue( "CursorTravelMode", NONBLOCKING )
 173
 174             bGoOn = true;
 175             while ( bGoOn )
 176             {
 177                 try
 178                 {
 179                     cursor.travelSomeWhere()
 180                     collectRowData()
 181                 }
 182                 catch ( CursorWouldBlockException )
 183                 {
 184                     // No more data at the moment.
 185                    bGoOn = false
 186                 }
 187             }
 188
 189             doSomethingWithCollectedRowData()
 190
 191             bProcessedAllRows = ...
 192         }
 193         </pre>
 194
 195         <p>
 196          If this property is not supported, the implementation needs to provide
 197         a blocking cursor.
 198         </p>
 199
 200         <p>
 201         The implementation initially needs to set the value of this property
 202         to <member>CursorTravelMode::BLOCKING</member>.
 203         </p>
 204
 205         @see CursorTravelMode
 206      */
 207     [optional, property] long CursorTravelMode;
 208
 209     /** contains the number of rows obtained (so far) from the data source. */
 210     [readonly, property] long RowCount;
 211
 212     /** indicates that all rows of te resultset have been obtained. */
 213     [readonly, property] boolean IsRowCountFinal;
 214
 215     //-------------------------------------------------------------------------
 216     /** provides access to the content identifier and the content object
 217         itself.
 218
 219         <p>This interface is required.
 220      */
 221     interface XContentAccess;
 222
 223     //-------------------------------------------------------------------------
 224     /** can be implemented to provide a complete JDBC conform result set
 225         interface for the implementation of this service.
 226
 227         <p>The implememtation of this service is optional.
 228      */
 229     service com::sun::star::sdbc::ResultSet;
 230 };
 231
 232 //=============================================================================
 233
 234 }; }; }; };
 235
 236 #endif