include/ucbhelper/resultset.hxx

   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
  20 #ifndef INCLUDED_UCBHELPER_RESULTSET_HXX
  21 #define INCLUDED_UCBHELPER_RESULTSET_HXX
  22
  23 #include <com/sun/star/lang/XServiceInfo.hpp>
  24 #include <com/sun/star/lang/XComponent.hpp>
  25 #include <com/sun/star/ucb/XContentAccess.hpp>
  26 #include <com/sun/star/sdbc/XResultSet.hpp>
  27 #include <com/sun/star/sdbc/XResultSetMetaDataSupplier.hpp>
  28 #include <com/sun/star/sdbc/XRow.hpp>
  29 #include <com/sun/star/sdbc/XCloseable.hpp>
  30 #include <com/sun/star/beans/XPropertySet.hpp>
  31
  32 #include <rtl/ref.hxx>
  33 #include <salhelper/simplereferenceobject.hxx>
  34 #include <cppuhelper/implbase.hxx>
  35 #include <ucbhelper/ucbhelperdllapi.h>
  36 #include <memory>
  37 #include <mutex>
  38
  39 namespace com::sun::star::uno { class XComponentContext; }
  40 namespace com::sun::star::ucb { class XCommandEnvironment; }
  41
  42 namespace ucbhelper {
  43
  44
  45 inline constexpr OUString RESULTSET_SERVICE_NAME = u"com.sun.star.ucb.ContentResultSet"_ustr;
  46
  47
  48 class ResultSetDataSupplier;
  49 struct ResultSet_Impl;
  50
  51 /**
  52  * This is an implementation of the service com.sun.star.ucb.ContentResultSet.
  53  * It can be used to implement the method XDynamicResultSet::getStaticResultSet,
  54  * which needs to be implemented for instance to implement the command "open"
  55  * at folder objects. This class uses a user supplied ResultSetDataSupplier
  56  * object to request data on demand.
  57  *
  58  * @see ResultSetDataSupplier
  59  */
  60 class SAL_DLLPUBLIC_RTTI ResultSet final :
  61                 public cppu::WeakImplHelper<
  62                     css::lang::XServiceInfo,
  63                     css::lang::XComponent,
  64                     css::ucb::XContentAccess,
  65                     css::sdbc::XResultSet,
  66                     css::sdbc::XResultSetMetaDataSupplier,
  67                     css::sdbc::XRow,
  68                     css::sdbc::XCloseable,
  69                     css::beans::XPropertySet>
  70 {
  71     std::unique_ptr<ResultSet_Impl> m_pImpl;
  72
  73 public:
  74     /**
  75       * Construction.
  76       *
  77       * @param rxSMgr is a Service Manager.
  78       * @param rProperties is a sequence of properties for that the resultset
  79       *        shall be able to obtain the values.
  80       * @param rDataSupplier is a supplier for the resultset data.
  81       */
  82     UCBHELPER_DLLPUBLIC ResultSet(
  83             const css::uno::Reference< css::uno::XComponentContext >& rxContext,
  84             const css::uno::Sequence< css::beans::Property >& rProperties,
  85             const rtl::Reference< ResultSetDataSupplier >& rDataSupplier );
  86     /**
  87       * Construction.
  88       *
  89       * @param rxSMgr is a Service Manager.
  90       * @param rProperties is a sequence of properties for that the resultset
  91       *        shall be able to obtain the values.
  92       * @param rDataSupplier is a supplier for the resultset data.
  93       * @param rxEnv is the environment for interactions, progress propagation,
  94       *        ...
  95       */
  96     UCBHELPER_DLLPUBLIC ResultSet(
  97             const css::uno::Reference< css::uno::XComponentContext >& rxContext,
  98             const css::uno::Sequence< css::beans::Property >& rProperties,
  99             const rtl::Reference< ResultSetDataSupplier >& rDataSupplier,
 100             const css::uno::Reference< css::ucb::XCommandEnvironment >& rxEnv );
 101     virtual ~ResultSet() override;
 102
 103     // XServiceInfo
 104     virtual OUString SAL_CALL getImplementationName() override;
 105     virtual sal_Bool SAL_CALL supportsService( const OUString& ServiceName ) override;
 106     virtual css::uno::Sequence< OUString > SAL_CALL getSupportedServiceNames() override;
 107
 108     // XComponent
 109     virtual void SAL_CALL
 110     dispose() override;
 111     virtual void SAL_CALL
 112     addEventListener( const css::uno::Reference< css::lang::XEventListener >& Listener ) override;
 113     virtual void SAL_CALL
 114     removeEventListener( const css::uno::Reference< css::lang::XEventListener >& Listener ) override;
 115
 116     // XContentAccess
 117     virtual OUString SAL_CALL
 118     queryContentIdentifierString() override;
 119     virtual css::uno::Reference< css::ucb::XContentIdentifier > SAL_CALL
 120     queryContentIdentifier() override;
 121     virtual css::uno::Reference< css::ucb::XContent > SAL_CALL
 122     queryContent() override;
 123
 124     // XResultSetMetaDataSupplier
 125     virtual css::uno::Reference< css::sdbc::XResultSetMetaData > SAL_CALL
 126     getMetaData() override;
 127
 128     // XResultSet
 129     virtual sal_Bool SAL_CALL
 130     next() override;
 131     virtual sal_Bool SAL_CALL
 132     isBeforeFirst() override;
 133     virtual sal_Bool SAL_CALL
 134     isAfterLast() override;
 135     virtual sal_Bool SAL_CALL
 136     isFirst() override;
 137     virtual sal_Bool SAL_CALL
 138     isLast() override;
 139     virtual void SAL_CALL
 140     beforeFirst() override;
 141     virtual void SAL_CALL
 142     afterLast() override;
 143     virtual sal_Bool SAL_CALL
 144     first() override;
 145     virtual sal_Bool SAL_CALL
 146     last() override;
 147     virtual sal_Int32 SAL_CALL
 148     getRow() override;
 149     virtual sal_Bool SAL_CALL
 150     absolute( sal_Int32 row ) override;
 151     virtual sal_Bool SAL_CALL
 152     relative( sal_Int32 rows ) override;
 153     virtual sal_Bool SAL_CALL
 154     previous() override;
 155     virtual void SAL_CALL
 156     refreshRow() override;
 157     virtual sal_Bool SAL_CALL
 158     rowUpdated() override;
 159     virtual sal_Bool SAL_CALL
 160     rowInserted() override;
 161     virtual sal_Bool SAL_CALL
 162     rowDeleted() override;
 163     virtual css::uno::Reference< css::uno::XInterface > SAL_CALL
 164     getStatement() override;
 165
 166     // XRow
 167     virtual sal_Bool SAL_CALL
 168     wasNull() override;
 169     virtual OUString SAL_CALL
 170     getString( sal_Int32 columnIndex ) override;
 171     virtual sal_Bool SAL_CALL
 172     getBoolean( sal_Int32 columnIndex ) override;
 173     virtual sal_Int8 SAL_CALL
 174     getByte( sal_Int32 columnIndex ) override;
 175     virtual sal_Int16 SAL_CALL
 176     getShort( sal_Int32 columnIndex ) override;
 177     virtual sal_Int32 SAL_CALL
 178     getInt( sal_Int32 columnIndex ) override;
 179     virtual sal_Int64 SAL_CALL
 180     getLong( sal_Int32 columnIndex ) override;
 181     virtual float SAL_CALL
 182     getFloat( sal_Int32 columnIndex ) override;
 183     virtual double SAL_CALL
 184     getDouble( sal_Int32 columnIndex ) override;
 185     virtual css::uno::Sequence< sal_Int8 > SAL_CALL
 186     getBytes( sal_Int32 columnIndex ) override;
 187     virtual css::util::Date SAL_CALL
 188     getDate( sal_Int32 columnIndex ) override;
 189     virtual css::util::Time SAL_CALL
 190     getTime( sal_Int32 columnIndex ) override;
 191     virtual css::util::DateTime SAL_CALL
 192     getTimestamp( sal_Int32 columnIndex ) override;
 193     virtual css::uno::Reference<
 194                 css::io::XInputStream > SAL_CALL
 195     getBinaryStream( sal_Int32 columnIndex ) override;
 196     virtual css::uno::Reference<
 197                 css::io::XInputStream > SAL_CALL
 198     getCharacterStream( sal_Int32 columnIndex ) override;
 199     virtual css::uno::Any SAL_CALL
 200     getObject( sal_Int32 columnIndex,
 201                const css::uno::Reference< css::container::XNameAccess >& typeMap ) override;
 202     virtual css::uno::Reference< css::sdbc::XRef > SAL_CALL
 203     getRef( sal_Int32 columnIndex ) override;
 204     virtual css::uno::Reference<
 205                 css::sdbc::XBlob > SAL_CALL
 206     getBlob( sal_Int32 columnIndex ) override;
 207     virtual css::uno::Reference< css::sdbc::XClob > SAL_CALL
 208     getClob( sal_Int32 columnIndex ) override;
 209     virtual css::uno::Reference< css::sdbc::XArray > SAL_CALL
 210     getArray( sal_Int32 columnIndex ) override;
 211
 212     // XCloseable
 213     virtual void SAL_CALL
 214     close() override;
 215
 216     // XPropertySet
 217     virtual css::uno::Reference< css::beans::XPropertySetInfo > SAL_CALL
 218     getPropertySetInfo() override;
 219     virtual void SAL_CALL
 220     setPropertyValue( const OUString& aPropertyName,
 221                       const css::uno::Any& aValue ) override;
 222     virtual css::uno::Any SAL_CALL
 223     getPropertyValue( const OUString& PropertyName ) override;
 224     virtual void SAL_CALL
 225     addPropertyChangeListener( const OUString& aPropertyName,
 226                                const css::uno::Reference< css::beans::XPropertyChangeListener >& xListener ) override;
 227     virtual void SAL_CALL
 228     removePropertyChangeListener( const OUString& aPropertyName,
 229                                   const css::uno::Reference< css::beans::XPropertyChangeListener >& aListener ) override;
 230     virtual void SAL_CALL
 231     addVetoableChangeListener( const OUString& PropertyName,
 232                                const css::uno::Reference< css::beans::XVetoableChangeListener >& aListener ) override;
 233     virtual void SAL_CALL
 234     removeVetoableChangeListener( const OUString& PropertyName,
 235                                   const css::uno::Reference< css::beans::XVetoableChangeListener >& aListener ) override;
 236
 237
 238     // Non-interface methods.
 239
 240
 241     /**
 242       * This method propagates property value changes to all registered
 243       * listeners.
 244       *
 245       * @param rEvt is a property change event.
 246       */
 247     void propertyChanged(std::unique_lock<std::mutex>& rGuard,
 248                 const css::beans::PropertyChangeEvent& rEvt ) const;
 249
 250     /**
 251       * This method should be called by the data supplier for the result set
 252       * to indicate that there were new data obtained from the data source.
 253       *
 254       * @param nOld is the old count of rows; must be non-negative.
 255       * @param nnew is the new count of rows; must be non-negative.
 256       */
 257     UCBHELPER_DLLPUBLIC void rowCountChanged( std::unique_lock<std::mutex>& rResultSetGuard, sal_uInt32 nOld, sal_uInt32 nNew );
 258
 259     /**
 260       * This method should be called by the data supplier for the result set
 261       * to indicate that there were all rows obtained from the data source.
 262       */
 263     UCBHELPER_DLLPUBLIC void rowCountFinal(std::unique_lock<std::mutex>& rResultSetGuard);
 264
 265     /**
 266       * This method returns a sequence containing all properties ( not the
 267       * values! ) of the result set.
 268       *
 269       * @return a sequence of properties.
 270       */
 271     UCBHELPER_DLLPUBLIC const css::uno::Sequence< css::beans::Property >&
 272     getProperties() const;
 273
 274     /**
 275       * This method returns the environment to use for interactions, progress
 276       * propagation, ... It can by empty.
 277       *
 278       * @return an environment or an empty reference.
 279       */
 280     UCBHELPER_DLLPUBLIC const css::uno::Reference< css::ucb::XCommandEnvironment >&
 281     getEnvironment() const;
 282 };
 283
 284
 285 /**
 286  * This is the base class for an object that supplies data to a result set
 287  *
 288  * @see ResultSet
 289  */
 290 class ResultSetDataSupplier : public salhelper::SimpleReferenceObject
 291 {
 292     friend class ResultSet;
 293
 294     // No ref, otherwise we get a cyclic reference between supplier and set!
 295     // Will be set from ResultSet ctor.
 296     ResultSet* m_pResultSet;
 297
 298 public:
 299     ResultSetDataSupplier() : m_pResultSet( nullptr ) {}
 300
 301     /**
 302      * This method returns the resultset this supplier belongs to.
 303      *
 304      * @return the resultset for that the supplier supplies data.
 305      */
 306     ResultSet* getResultSet() const { return m_pResultSet; }
 307
 308     /**
 309      * This method returns the identifier string of the content at the
 310      * specified index.
 311      *
 312      * @param nIndex is the zero-based index within the logical data array
 313      *               of the supplier; must be non-negative.
 314      * @return the content's identifier string.
 315      */
 316     virtual OUString queryContentIdentifierString( std::unique_lock<std::mutex>& rResultSetGuard, sal_uInt32 nIndex ) = 0;
 317
 318     /**
 319      * This method returns the identifier of the content at the specified index.
 320      *
 321      * @param nIndex is the zero-based index within the logical data array
 322      *               of the supplier; must be non-negative.
 323      * @return the content's identifier.
 324      */
 325     virtual css::uno::Reference< css::ucb::XContentIdentifier >
 326     queryContentIdentifier( std::unique_lock<std::mutex>& rResultSetGuard, sal_uInt32 nIndex ) = 0;
 327
 328     /**
 329      * This method returns the content at the specified index.
 330      *
 331      * @param nIndex is the zero-based index within the logical data array
 332      *               of the supplier; must be non-negative.
 333      * @return the content.
 334      */
 335     virtual css::uno::Reference< css::ucb::XContent >
 336     queryContent( std::unique_lock<std::mutex>& rResultSetGuard, sal_uInt32 nIndex ) = 0;
 337
 338     /**
 339      * This method returns whether there is a content at the specified index.
 340      *
 341      * @param nIndex is the zero-based index within the logical data array
 342      *               of the supplier; must be non-negative.
 343      * @return true, if there is a content at the given index.
 344      */
 345     virtual bool getResult( std::unique_lock<std::mutex>& rResultSetGuard, sal_uInt32 nIndex ) = 0;
 346
 347     /**
 348      * This method returns the total count of objects in the logical data array
 349      * of the supplier. The implementation of this method may be very
 350      * "expensive", because it can be necessary to obtain all data in order
 351      * to determine the count. Therefore the ResultSet implementation calls
 352      * it very seldom.
 353      *
 354      * @return the total count of objects; will always be non-negative.
 355      */
 356     virtual sal_uInt32 totalCount(std::unique_lock<std::mutex>& rResultSetGuard) = 0;
 357
 358     /**
 359      * This method returns the count of objects obtained so far. There is no
 360      * for the implementation to obtain all objects at once. It can obtain
 361      * all data on demand.
 362      *
 363      * The implementation should call m_pResultSet->rowCountChanged(...)
 364      * every time it has inserted a new entry in its logical result array.
 365      *
 366      * @return the count of objects obtained so far; will always be
 367      * non-negative.
 368      */
 369     virtual sal_uInt32 currentCount() = 0;
 370
 371     /**
 372      * This method returns whether the value returned by currentCount() is
 373      * "final". This is the case, if that there was all data obtained by the
 374      * supplier and the current count won't increase any more.
 375      *
 376      * The implementation should call m_pResultSet->rowCountFinal(...) if
 377      * it has inserted all entries in its logical result array.
 378      *
 379      * @return true, if the value returned by currentCount() won't change
 380                anymore.
 381      */
 382     virtual bool isCountFinal() = 0;
 383
 384     /**
 385      * This method returns an object for accessing the property values at
 386      * the specified index. The implementation may use the helper class
 387      * ucb::PropertyValueSet to provide the return value.
 388      *
 389      * @param nIndex is the zero-based index within the logical data array
 390      *               of the supplier.
 391      * @return the object for accessing the property values.
 392      */
 393     virtual css::uno::Reference< css::sdbc::XRow >
 394     queryPropertyValues( std::unique_lock<std::mutex>& rResultSetGuard, sal_uInt32 nIndex  ) = 0;
 395
 396     /**
 397      * This method is called to instruct the supplier to release the (possibly
 398      * present) property values at the given index.
 399      *
 400      * @param nIndex is the zero-based index within the logical data array
 401      *               of the supplier.
 402      */
 403     virtual void releasePropertyValues( sal_uInt32 nIndex ) = 0;
 404
 405     /**
 406      * This method will be called by the resultset implementation in order
 407      * to instruct the data supplier to release all resources it has
 408      * allocated so far. In case the supplier is collecting data
 409      * asynchronously, that process must be stopped.
 410      */
 411     virtual void close() = 0;
 412
 413     /**
 414      * This method will be called by the resultset implementation in order
 415      * check, whether an error has occurred while collecting data. The
 416      * implementation of this method must throw an exception in that case.
 417      *
 418      * Note: An exception thrown to indicate an error must always be thrown
 419      * by the thread that created the data supplier. If the supplier collects
 420      * data asynchronously ( i.e. in a separate thread ) and an error
 421      * occurs, throwing of the appropriate exception must be deferred
 422      * until validate() is called by the ResultSet implementation from
 423      * inside the main thread.
 424      * In case data are obtained synchronously, the ResultSetException can
 425      * be thrown directly.
 426      *
 427      * @exception ResultSetException thrown, if an error has occurred
 428      */
 429     virtual void validate() = 0;
 430 };
 431
 432 }
 433
 434 #endif /* ! INCLUDED_UCBHELPER_RESULTSET_HXX */
 435
 436 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */