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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_ucb_ContentResultSet_idl__
  20 #define __com_sun_star_ucb_ContentResultSet_idl__
  21
  22 #include <com/sun/star/lang/XComponent.idl>
  23 #include <com/sun/star/beans/XPropertySet.idl>
  24 #include <com/sun/star/sdbc/XResultSet.idl>
  25 #include <com/sun/star/sdbc/XResultSetMetaDataSupplier.idl>
  26 #include <com/sun/star/sdbc/XRow.idl>
  27 #include <com/sun/star/sdbc/XCloseable.idl>
  28 #include <com/sun/star/ucb/XContentAccess.idl>
  29 #include <com/sun/star/sdbc/ResultSet.idl>
  30
  31
  32 module com { module sun { module star { module ucb {
  33
  34 /** provides access to the children of a folder content.
  35
  36     <p>It can be understand as a table containing a row for each child. The
  37     table columns may contain values of properties of the children.
  38 */
  39 published service ContentResultSet
  40 {
  41     /** must be implemented to make it possible to resolve cyclic object
  42         references ( i.e. between an implementation of
  43         com::sun::star::beans::XPropertySet
  44         - which may hold property change listeners - and
  45         com::sun::star::beans::XPropertyChangeListener
  46         - which may hold the property set ).
  47
  48         <p>This interface is required.
  49      */
  50     interface com::sun::star::lang::XComponent;
  51
  52     /** provides access to the result set meta data. Meta data are for
  53         example the number of columns of the result set, information
  54         on the data types of columns, column names, and more.
  55
  56         <p>This interface is required.
  57      */
  58     interface com::sun::star::sdbc::XResultSetMetaDataSupplier;
  59
  60     /** enables traveling through the result set members ( the contents ).
  61         This interface mainly provides a cursor for the result set.
  62
  63         <p>Note that every method of this interface implementation additionally
  64         may throw a ResultSetException ( which is derived from
  65         com::sun::star::sdbc::SQLException to be compatible
  66         to that interface ). The new exception transports another exception,
  67         which indicates the reason for the failure of the method call.
  68
  69         <p>This interface is required.
  70      */
  71     interface com::sun::star::sdbc::XResultSet;
  72
  73     /** provides access to data of the content the cursor is pointing to.
  74
  75         <p>Note that every method of this interface implementation additionally
  76         may throw a ResultSetException ( which is derived from
  77         com::sun::star::sdbc::SQLException to be compatible
  78         to that interface ). The new exception transports another exception,
  79         which indicates the reason for the failure of the method call.
  80
  81         <p>This interface is required.
  82      */
  83     interface com::sun::star::sdbc::XRow;
  84
  85     /** makes it possible to abort running activities ( i.e. to cancel
  86         retrieving data from a server ).
  87
  88         <p>Note that every method of this interface implementation additionally
  89         may throw a ResultSetException ( which is derived from
  90         com::sun::star::sdbc::SQLException to be compatible
  91         to that interface ). The new exception transports another exception,
  92         which indicates the reason for the failure of the method call.
  93
  94         <p>This interface is required.
  95      */
  96     interface com::sun::star::sdbc::XCloseable;
  97
  98     /** holds properties of the result set.
  99
 100         <p>This interface is required.
 101      */
 102     interface com::sun::star::beans::XPropertySet;
 103
 104     /** controls the travel mode of the result set cursor.
 105
 106         <p>There are two possible travel modes:
 107
 108         <p><table border=1>
 109         <tr><td>CursorTravelMode::BLOCKING</td>
 110             <td>Each travel method of the result set will not return until the
 111                 data for the new position were retrieved.</td></tr>
 112         <tr><td>CursorTravelMode::NONBLOCKING</td>
 113             <td>The implementation will throw a
 114                 <code>CursorWouldBlockException</code>, if the data for the new
 115                 position are not retrieved yet.</td></tr>
 116         </table>
 117
 118         <p>The following pseudo-code illustrates the usage of a non-blocking
 119         cursor:
 120
 121         @code{.java}
 122         bProcessedAllRows = false
 123         while ( !bProcessedAllRows )
 124         {
 125             cursor.setPropertyValue( "CursorTravelMode", BLOCKING )
 126
 127             cursor.travelSomeWhere()
 128             collectRowData()
 129
 130             cursor.setPropertyValue( "CursorTravelMode", NONBLOCKING )
 131
 132             bGoOn = true;
 133             while ( bGoOn )
 134             {
 135                 try
 136                 {
 137                     cursor.travelSomeWhere()
 138                     collectRowData()
 139                 }
 140                 catch ( CursorWouldBlockException )
 141                 {
 142                     // No more data at the moment.
 143                    bGoOn = false
 144                 }
 145             }
 146
 147             doSomethingWithCollectedRowData()
 148
 149             bProcessedAllRows = ...
 150         }
 151         @endcode
 152
 153         <p>
 154          If this property is not supported, the implementation needs to provide
 155         a blocking cursor.
 156         </p>
 157
 158         <p>
 159         The implementation initially needs to set the value of this property
 160         to CursorTravelMode::BLOCKING.
 161         </p>
 162
 163         @see CursorTravelMode
 164      */
 165     [optional, property] long CursorTravelMode;
 166
 167     /** contains the number of rows obtained (so far) from the data source. */
 168     [readonly, property] long RowCount;
 169
 170     /** indicates that all rows of the result set have been obtained. */
 171     [readonly, property] boolean IsRowCountFinal;
 172
 173     /** provides access to the content identifier and the content object
 174         itself.
 175
 176         <p>This interface is required.
 177      */
 178     interface XContentAccess;
 179
 180     /** can be implemented to provide a complete JDBC conform result set
 181         interface for the implementation of this service.
 182
 183         <p>The implementation of this service is optional.
 184      */
 185     service com::sun::star::sdbc::ResultSet;
 186 };
 187
 188
 189 }; }; }; };
 190
 191 #endif
 192
 193 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */