sd/source/ui/framework/configuration/ConfigurationUpdater.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: ConfigurationUpdater.hxx,v $
  10  * $Revision: 1.4 $
  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 SD_FRAMEWORK_CONFIGURATION_UPDATER_HXX
  32 #define SD_FRAMEWORK_CONFIGURATION_UPDATER_HXX
  33
  34 #include "ConfigurationControllerResourceManager.hxx"
  35 #include <com/sun/star/drawing/framework/XResourceId.hpp>
  36 #include <com/sun/star/drawing/framework/XConfiguration.hpp>
  37 #include <com/sun/star/drawing/framework/XControllerManager.hpp>
  38 #include <vcl/timer.hxx>
  39 #include <vector>
  40 #include <boost/shared_ptr.hpp>
  41
  42 namespace css = ::com::sun::star;
  43
  44 namespace sd { namespace framework {
  45
  46 class ConfigurationClassifier;
  47 class ConfigurationUpdaterLock;
  48
  49 /** This is a helper class for the ConfigurationController.  It handles the
  50     update of the current configuration so that it looks like a requested
  51     configuration.  An update is made by activating or deactivating drawing
  52     framework resources.
  53
  54     When an update is not successfull, i.e. after the update the current
  55     configuration is not equivalent to the requested configuration, then a
  56     timer is started to repeat the update after a short time.
  57 */
  58 class ConfigurationUpdater
  59 {
  60 public:
  61     /** Create a new ConfigurationUpdater object that notifies configuration
  62         changes and the start and end of updates via the given broadcaster.
  63     */
  64     ConfigurationUpdater (
  65         const ::boost::shared_ptr<ConfigurationControllerBroadcaster>& rpBroadcaster,
  66         const ::boost::shared_ptr<ConfigurationControllerResourceManager>& rpResourceManager,
  67         const css::uno::Reference<
  68             css::drawing::framework::XControllerManager>& rxControllerManager);
  69     ~ConfigurationUpdater (void);
  70
  71     /** This method is typically called once, when the controller manager is
  72         accessible to the caller.
  73     */
  74     void SetControllerManager(
  75         const css::uno::Reference<
  76             css::drawing::framework::XControllerManager>& rxControllerManager);
  77
  78     /** Request an update of the current configuration so that it looks like
  79         the given requested configuration.  It checks whether an update of
  80         the current configuration can be done.  Calls UpdateConfiguration()
  81         if that is the case.  Otherwise it schedules a later call to
  82         UpdateConfiguration().
  83     */
  84     void RequestUpdate (const css::uno::Reference<
  85         css::drawing::framework::XConfiguration>& rxRequestedConfiguration);
  86
  87     css::uno::Reference<
  88         css::drawing::framework::XConfiguration> GetCurrentConfiguration (void) const;
  89
  90     css::uno::Reference<
  91         css::drawing::framework::XConfiguration> GetRequestedConfiguration (void) const;
  92
  93     friend class ConfigurationUpdaterLock;
  94     /** Return a lock of the called ConfigurationUpdater.  While the
  95         returned object exists no update of the current configuration is
  96         made.
  97     */
  98     ::boost::shared_ptr<ConfigurationUpdaterLock> GetLock (void);
  99
 100 private:
 101     /** A reference to the XControllerManager is kept so that
 102         UpdateConfiguration() has access to the other sub controllers.
 103     */
 104     css::uno::Reference<
 105         css::drawing::framework::XControllerManager> mxControllerManager;
 106
 107     ::boost::shared_ptr<ConfigurationControllerBroadcaster> mpBroadcaster;
 108
 109     /** The current configuration holds the resources that are currently
 110         active.  It is modified during an update.
 111     */
 112     css::uno::Reference<
 113         css::drawing::framework::XConfiguration> mxCurrentConfiguration;
 114
 115     /** The requested configuration holds the resources that have been
 116         requested to activate or to deactivate since the last update.  It is
 117         (usually) not modified during an update.  This configuration is
 118         maintained by the ConfigurationController and given to the
 119         ConfigurationUpdater in the RequestUpdate() method.
 120     */
 121     css::uno::Reference<
 122         css::drawing::framework::XConfiguration> mxRequestedConfiguration;
 123
 124     /** This flag is set to </TRUE> when an update of the current
 125         configurtion was requested (because the last request in the queue
 126         was processed) but could not be exected because the
 127         ConfigurationController was locked.  A call to UpdateConfiguration()
 128         resets the flag to </FALSE>.
 129     */
 130     bool mbUpdatePending;
 131
 132     /** This flag is set to </TRUE> while the UpdateConfiguration() method
 133         is running.  It is used to prevent reentrance problems with this
 134         method.
 135     */
 136     bool mbUpdateBeingProcessed;
 137
 138     /** The ConfigurationController is locked when this count has a value
 139         larger then zero.  If the controller is locked then updates of the
 140         current configuration are not made.
 141     */
 142     sal_Int32 mnLockCount;
 143
 144     /** This timer is used to check from time to time whether the requested
 145         configuration and the current configuration are identcal and request
 146         an update when they are not.
 147         This is used to overcome problems with resources that become
 148         available asynchronously.
 149     */
 150     Timer maUpdateTimer;
 151
 152     /** The number of failed updates (those after which the current
 153         configuration is not equivalent to the requested configuration) is
 154         used to determine how long to wait before another update is made.
 155     */
 156     sal_Int32 mnFailedUpdateCount;
 157
 158     ::boost::shared_ptr<ConfigurationControllerResourceManager> mpResourceManager;
 159
 160     /** This method does the main work of an update.  It calls the sub
 161         controllers that are responsible for the various types of resources
 162         and tells them to update their active resources.  It notifies
 163         listeners about the start and end of the configuration update.
 164     */
 165     void UpdateConfiguration (void);
 166
 167     /** Basically calls UpdaterStart() andUpdateEnd() and makes some debug
 168         output.
 169     */
 170     void UpdateCore (const ConfigurationClassifier& rClassifier);
 171
 172     /** Check for all pure anchors if they have at least one child.
 173         Childless pure anchors are deactivated.
 174         This affects only the current configuration.
 175     */
 176     void CheckPureAnchors (
 177         const css::uno::Reference<css::drawing::framework::XConfiguration>& rxConfiguration,
 178         ::std::vector<css::uno::Reference<css::drawing::framework::XResourceId> >&
 179             rResourcesToDeactivate);
 180
 181     /** Remove from the requested configration all pure anchors that have no
 182         child.  Requested but not yet activated anchors can not be removed
 183         because without the actual resource the 'pureness' of an anchor can
 184         not be determined.
 185     */
 186     void CleanRequestedConfiguration (void);
 187
 188     /** Check the success of a recently executed configuration update.
 189         When the update failed then start the timer.
 190     */
 191     void CheckUpdateSuccess (void);
 192
 193     /** This method sets the mbUpdateBeingProcessed member that is used to
 194         prevent reentrance problems.  This method allows function objects
 195         easyly and safely to modify the variable.
 196     */
 197     void SetUpdateBeingProcessed (bool bValue);
 198
 199     /** Return whether it is possible to do an update of the configuration.
 200         This takes into account whether another update is currently being
 201         executed, the lock count, and whether the configuration controller
 202         is still valid.
 203     */
 204     bool IsUpdatePossible (void);
 205
 206     /** Lock updates of the current configuration.  For intermediate requests
 207         for updates mbUpdatePending is set to <TRUE/>.
 208     */
 209     void LockUpdates (void);
 210
 211     /** When an update was requested since the last LockUpdates() call then
 212         RequestUpdate() is called.
 213     */
 214     void UnlockUpdates (void);
 215
 216     DECL_LINK(TimeoutHandler, Timer*);
 217 };
 218
 219 } } // end of namespace sd::framework
 220
 221 #endif