configmgr/source/treecache/cachecontroller.hxx

   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: cachecontroller.hxx,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
  31 #ifndef CONFIGMGR_BACKEND_CACHECONTROLLER_HXX
  32 #define CONFIGMGR_BACKEND_CACHECONTROLLER_HXX
  33
  34 #include "sal/config.h"
  35
  36 #include "salhelper/simplereferenceobject.hxx"
  37
  38 #include "utility.hxx"
  39 #include "mergeddataprovider.hxx"
  40 #include "cacheaccess.hxx"
  41 #include "cachemulticaster.hxx"
  42 #include "requestoptions.hxx"
  43 #include "autoreferencemap.hxx"
  44 #include <com/sun/star/uno/XComponentContext.hpp>
  45
  46 namespace configmgr
  47 {
  48 // ---------------------------------------------------------------------------
  49     class OTreeDisposeScheduler;
  50     class OCacheWriteScheduler;
  51 // ---------------------------------------------------------------------------
  52     namespace backend
  53     {
  54 // ---------------------------------------------------------------------------
  55
  56     /** manages a shared data cache for configuration data
  57         trying to ensure consistency with a backend
  58         and provides access to the data for clients
  59     */
  60     class CacheController:
  61             public salhelper::SimpleReferenceObject,
  62             public ITemplateDataProvider, public INodeDataListener
  63     {
  64     public:
  65         /** ctor
  66         */
  67         explicit
  68         CacheController(rtl::Reference< backend::IMergedDataProvider > const & _xBackend,
  69                         const uno::Reference<uno::XComponentContext>& xContext);
  70
  71         // disposing the cache before destroying
  72         void dispose() SAL_THROW((com::sun::star::uno::RuntimeException));
  73
  74         /** locates data of a component in the cache.
  75
  76             <p> If the data isn't in the cache it is loaded from the backend. </p>
  77
  78             @param _aRequest
  79                 identifies the component to be loaded.
  80
  81             @returns
  82                 data that can be used to locate the loaded data in the cache.
  83
  84             @throws com::sun::star::uno::Exception
  85                 if loading the data fails.
  86                 The exact exception being thrown may depend on the underlying backend.
  87         */
  88         sharable::TreeFragment * loadComponent(ComponentRequest const & _aRequest)
  89             SAL_THROW((com::sun::star::uno::Exception));
  90
  91         /** releases data of a component from the cache.
  92
  93             <p> Should be called when a client is done with a component.
  94                 Each calls to <method>loadComponent</method> should
  95                 be balanced by exactly one call to <method>freeComponent</method>.
  96             </p>
  97
  98             @param _aRequest
  99                 identifies a component previously loaded via <method>loadComponent</method>.
 100
 101             @returns
 102                 data that can be used to locate the loaded data in the cache.
 103         */
 104         void freeComponent(ComponentRequest const & _aRequest)
 105             SAL_THROW(());
 106
 107         /** refreshes data of an existing component from the backend
 108
 109             <p> If the data is in the cache already, it is refreshed from the
 110                 backend and the change are notified to all registered listeners.
 111             </p>
 112             <p> If the data isn't in the cache nothing is done and
 113                 a NULL location is returned.
 114             </p>
 115
 116             <p>Note: the caller <strong>must not</strong> hold any lock on the cache line affected.</p>
 117
 118             @param _aRequest
 119                 identifies the component to be refreshed.
 120
 121             @returns
 122                 data that can be used to locate the refreshed data in the cache.
 123
 124                 <p>If there is no data to refresh a NULL location is returned.</p>
 125
 126             @throws com::sun::star::uno::Exception
 127                 if loading the data fails.
 128                 The exact exception being thrown may depend on the underlying backend.
 129         */
 130         sharable::TreeFragment * refreshComponent(ComponentRequest const & _aRequest)
 131             SAL_THROW((com::sun::star::uno::Exception));
 132          /** refreshes data of all existing components from the backend
 133
 134             <p> If the data is in the cache already, it is refreshed from the
 135                 backend and the change are notified to all registered listeners.
 136             </p>
 137             <p> If the data isn't in the cache nothing is done and
 138                 a NULL location is returned.
 139             </p>
 140
 141             <p>Note: the caller <strong>must not</strong> hold any lock on the cache line affected.</p>
 142
 143              @throws com::sun::star::uno::Exception
 144                 if loading the data fails.
 145                 The exact exception being thrown may depend on the underlying backend.
 146         */
 147         void refreshAllComponents()
 148             SAL_THROW((com::sun::star::uno::Exception));
 149
 150         /** flushes data of all pending updates from cache to the backend(s)
 151                 @throws com::sun::star::uno::Exception
 152                 if flushing the data fails.
 153                 The exact exception being thrown may depend on the underlying backend.
 154         */
 155         void flushPendingUpdates() SAL_THROW((com::sun::star::uno::Exception));
 156
 157         /** locates a template in the cache.
 158
 159             <p> If the data isn't in the cache it is loaded from the backend. </p>
 160
 161             <p>Note: the caller <strong>must not</strong> hold any lock on the cache line affected.</p>
 162
 163             @param _aRequest
 164                 identifies the template to be loaded.
 165
 166             @returns
 167                 data that can be used to locate the template data in the cache.
 168
 169             @throws com::sun::star::uno::Exception
 170                 if loading the template data fails.
 171                 The exact exception being thrown may depend on the underlying backend.
 172         */
 173         sharable::TreeFragment * loadTemplate(TemplateRequest const & _aRequest)
 174             SAL_THROW((com::sun::star::uno::Exception));
 175
 176         /** saves changes to the backend and notifies them to registered listeners.
 177
 178             <p> Must be called after the changes have been applied to the cache
 179                 and before any subsequent changes to the same component.
 180             </p>
 181
 182             <p> Notifications are guaranteed to be delivered
 183                 before any subsequent changes to the same component are possible.
 184             </p>
 185
 186             <p> Note: the caller <strong>must</strong> hold a read lock (but no write lock)
 187                 on the cache line affected during the call.</p>
 188
 189             @param _anUpdate
 190                 identifies the node that changed and describes the changes.
 191
 192             @throws com::sun::star::uno::Exception
 193                 if saving the changes to the backend fails.
 194                 The exact exception being thrown may depend on the underlying backend.
 195         */
 196         void saveAndNotify(UpdateRequest const & _anUpdate)
 197             SAL_THROW((com::sun::star::uno::Exception));
 198
 199        /** @returns
 200                 an object that can used to broadcast changes done through this object.
 201                 <p> The object returned is guaranteed to live as long
 202                     as this object lives.
 203                 </p>
 204         */
 205         CacheChangeMulticaster & getNotifier() SAL_THROW(())
 206         { return m_aNotifier; }
 207
 208         /** loads merged data for a (complete) tree and returns it as return value.
 209
 210             @param _aRequest
 211                 identifies the component to be loaded
 212
 213             @param __bAddListenter
 214                 identifies is listener is to be registered to backend
 215
 216             @returns
 217                 A valid component instance for the given component.
 218
 219             @throws com::sun::star::uno::Exception
 220                 if the node cannot be retrieved.
 221                 The exact exception being thrown may depend on the underlying backend.
 222
 223         */
 224         ResultHolder< ComponentInstance > getComponentData(ComponentRequest const & _aRequest,
 225                                                  bool _bAddListenter)
 226             SAL_THROW((com::sun::star::uno::Exception));
 227
 228         /** loads default data for a (partial) tree and returns it as return value
 229
 230             @param _aRequest
 231                 identifies the node to be loaded
 232
 233             @returns
 234                 A valid node instance for the default state of the given node.
 235
 236                 <p>May be NULL, if the node exists but has no default equivalent.</p>
 237
 238             @throws com::sun::star::uno::Exception
 239                 if the default cannot be retrieved.
 240                 The exact exception being thrown may depend on the underlying backend.
 241         */
 242         ResultHolder< NodeInstance > getDefaultData(NodeRequest const & _aRequest)
 243             SAL_THROW((com::sun::star::uno::Exception));
 244
 245         /** loads a given template and returns it as return value
 246
 247             @param _aRequest
 248                 identifies the template to be loaded
 249
 250             @returns
 251                 A valid instance of the given template.
 252
 253                 <p> Currently a request with empty template name
 254                     will retrieve a group node holding all templates
 255                     of a component.
 256                 </p>
 257
 258             @throws com::sun::star::uno::Exception
 259                 if the template cannot be retrieved.
 260                 The exact exception being thrown may depend on the underlying backend.
 261         */
 262         virtual ResultHolder< TemplateInstance > getTemplateData(TemplateRequest const & _aRequest)
 263             SAL_THROW((com::sun::star::uno::Exception));
 264         //INodeDataListener Implementation
 265         /** Triggered when component data is changed
 266
 267             @param _aRequest
 268                 identifies the data that changed
 269         */
 270         virtual void dataChanged(const ComponentRequest& _aRequest) SAL_THROW(());
 271     protected:
 272         // ref counted, that's why no public dtor
 273         ~CacheController();
 274     // implementation
 275     private:
 276         configuration::AbsolutePath encodeTemplateLocation(rtl::OUString const & _rName, rtl::OUString const & _rModule) const;
 277
 278         configuration::AbsolutePath ensureTemplate(rtl::OUString const& _rName, rtl::OUString const& _rModule) SAL_THROW((com::sun::star::uno::Exception));
 279
 280         // adjust a node result for locale, ...
 281         bool normalizeResult(std::auto_ptr<ISubtree> &  _aResult, RequestOptions const & _aOptions);
 282
 283         // reads data from the backend directly
 284         ResultHolder< ComponentInstance > loadDirectly(ComponentRequest const & _aRequest, bool _bAddListenter )
 285             SAL_THROW((com::sun::star::uno::Exception));
 286         // reads default data from the backend directly
 287         ResultHolder< NodeInstance > loadDefaultsDirectly(NodeRequest const & _aRequest) SAL_THROW((com::sun::star::uno::Exception));
 288         // writes an update  to the backend directly
 289         void saveDirectly(UpdateRequest const & _anUpdate) SAL_THROW((com::sun::star::uno::Exception));
 290
 291         // writes updates for a component to the backend directly
 292         void savePendingChanges(rtl::Reference<CacheLoadingAccess> const & _aCache, ComponentRequest const & _aComponent)
 293             SAL_THROW((com::sun::star::uno::Exception));
 294         // saves all pending changes from a cache access to the backend
 295         bool saveAllPendingChanges(rtl::Reference<CacheLoadingAccess> const & _aCache, RequestOptions const & _aOptions)
 296             SAL_THROW((com::sun::star::uno::RuntimeException));
 297         // load templates componentwise from backend
 298         std::auto_ptr<ISubtree> loadTemplateData(TemplateRequest const & _aRequest)
 299             SAL_THROW((com::sun::star::uno::Exception));
 300
 301
 302         void flushCacheWriter() SAL_THROW(());
 303         // add templates componentwise to cache
 304         sharable::TreeFragment * addTemplates ( backend::ComponentDataStruct const & _aComponentInstance );
 305         rtl::Reference<CacheLoadingAccess> getCacheAlways(RequestOptions const & _aOptions);
 306
 307         OTreeDisposeScheduler   * createDisposer(const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >& _xContext);
 308         OCacheWriteScheduler    * createCacheWriter(const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >& _xContext);
 309
 310
 311
 312         // disposing
 313         void disposeAll(bool _bFlushRemainingUpdates);
 314
 315         void closeModules(std::vector< rtl::Reference<CacheLine> > & _aList, RequestOptions const & _aOptions);
 316     private:
 317         typedef AutoReferenceMap<RequestOptions,CacheLoadingAccess,lessRequestOptions>   CacheMap;
 318
 319         CacheChangeMulticaster  m_aNotifier;
 320         rtl::Reference< backend::IMergedDataProvider >          m_xBackend;
 321         CacheMap                m_aCacheMap;
 322         TemplateCacheData       m_aTemplates;
 323
 324         OTreeDisposeScheduler*  m_pDisposer;
 325         OCacheWriteScheduler *  m_pCacheWriter;
 326
 327         bool m_bDisposing; // disables async writing and automatic refresh
 328
 329         friend class configmgr::OTreeDisposeScheduler;
 330         friend class configmgr::OCacheWriteScheduler;
 331         friend class OInvalidateTreeThread;
 332
 333     };
 334 // ---------------------------------------------------------------------------
 335     } // namespace backend
 336
 337 // ---------------------------------------------------------------------------
 338 } // namespace configmgr
 339
 340 #endif
 341