configmgr/source/api2/confignotifier.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: confignotifier.hxx,v $
  10  * $Revision: 1.11 $
  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_CONFIGNOTIFIER_HXX_
  32 #define CONFIGMGR_CONFIGNOTIFIER_HXX_
  33
  34 #include "configexcept.hxx"
  35 #include "configpath.hxx"
  36 #include "datalock.hxx"
  37 #include "utility.hxx"
  38 #include <boost/utility.hpp>
  39 #include <vos/ref.hxx>
  40 #include <com/sun/star/lang/DisposedException.hpp>
  41 #include <com/sun/star/uno/Sequence.hxx>
  42
  43 namespace com { namespace sun { namespace star {
  44     namespace beans
  45     {
  46         class XPropertyChangeListener;
  47         class XVetoableChangeListener;
  48         class XPropertiesChangeListener;
  49         class PropertyVetoException;
  50     }
  51     namespace lang
  52     {
  53         class XEventListener;
  54         struct EventObject;
  55     }
  56     namespace container { class XContainerListener; }
  57     namespace util              { class XChangesListener; }
  58     namespace uno               { class RuntimeException; }
  59 } } }
  60 namespace osl { class Mutex; }
  61
  62 namespace configmgr
  63 {
  64     namespace configuration
  65     {
  66 // ---------------------------------------------------------------------------------------------------
  67         class NodeRef;
  68         class ValueRef;
  69         class NodeChange;
  70         class NodeChanges;
  71     }
  72 // ---------------------------------------------------------------------------------------------------
  73     namespace configapi
  74     {
  75 // ---------------------------------------------------------------------------------------------------
  76         class Broadcaster;
  77         class NotifierImpl;
  78         class ApiTreeImpl;
  79
  80         namespace css = ::com::sun::star;
  81 // ---------------------------------------------------------------------------------------------------
  82         /// manages collections of event listeners observing a config tree, thread-safe
  83         class Notifier
  84         {
  85             friend class Broadcaster;
  86             friend class BroadcasterHelper;
  87             vos::ORef<NotifierImpl>                     m_aImpl;
  88             ApiTreeImpl const*const     m_pTree;
  89         public:
  90             /// construct this around the given Implementation, for the given tree
  91             explicit Notifier(vos::ORef<NotifierImpl> const & aImpl, ApiTreeImpl const* pTree);
  92             Notifier(Notifier const& aOther);
  93             ~Notifier();
  94
  95         // ---------------------------------------------------------------------------------------------------
  96             /// create a broadcaster for a single change (either local or (possibly) nested)
  97             Broadcaster makeBroadcaster(configuration::NodeChange const& aChange, bool bLocal) const;
  98             /// create a broadcaster for a collection of changes (either local or (possibly) nested)
  99             Broadcaster makeBroadcaster(configuration::NodeChanges const& aChange, bool bLocal) const;
 100
 101         // ---------------------------------------------------------------------------------------------------
 102             bool checkAlive(uno::XInterface* pObject) const throw(css::lang::DisposedException);
 103
 104         // ---------------------------------------------------------------------------------------------------
 105             /// Add a <type scope='com::sun::star::lang'>XEventListener</type> observing <var>aNode</var>.
 106             void add(configuration::NodeRef const& aNode, uno::Reference< css::lang::XEventListener > const& xListener) const;
 107
 108             /// Add a <type scope='com::sun::star::container'>XContainerListener</type> observing <var>aNode</var>.
 109             void add(configuration::NodeRef const& aNode, uno::Reference< css::container::XContainerListener > const& xListener) const;
 110
 111             /// Add a <type scope='com::sun::star::util'>XChangesListener</type> observing <var>aNode</var> and its descendants.
 112             void add(configuration::NodeRef const& aNode, uno::Reference< css::util::XChangesListener > const& xListener) const;
 113
 114             /// Add a <type scope='com::sun::star::beans'>XPropertyChangeListener</type> observing all children of <var>aNode</var>.
 115             void addForAll(configuration::NodeRef const& aNode, uno::Reference< css::beans::XPropertyChangeListener > const& xListener) const;
 116             /// Add a <type scope='com::sun::star::beans'>XPropertyChangeListener</type> observing only the child named <var>aName</var> of <var>aNode</var>.
 117             void addForOne(configuration::NodeRef const& aNode, uno::Reference< css::beans::XPropertyChangeListener > const& xListener, rtl::OUString const& aName) const;
 118             /// Add a <type scope='com::sun::star::beans'>XVetoableChangeListener</type> constraining all children of <var>aNode</var>.
 119             void addForAll(configuration::NodeRef const& aNode, uno::Reference< css::beans::XVetoableChangeListener > const& xListener) const;
 120             /// Add a <type scope='com::sun::star::beans'>XVetoableChangeListener</type> constraining only the child named <var>aName</var> of <var>aNode</var>.
 121             void addForOne(configuration::NodeRef const& aNode, uno::Reference< css::beans::XVetoableChangeListener > const& xListener, rtl::OUString const& aName) const;
 122
 123             /** Add a <type scope='com::sun::star::beans'>XPropertiesChangeListener</type>
 124                 observing the properties of <var>aNode</var> (optimally only those given by <var>aNames</var>.
 125             */
 126             void add(configuration::NodeRef const& aNode, uno::Reference< css::beans::XPropertiesChangeListener > const& xListener, uno::Sequence<rtl::OUString> const& aNames) const;
 127
 128         // ---------------------------------------------------------------------------------------------------
 129             /// Remove a <type scope='com::sun::star::lang'>XEventListener</type> observing <var>aNode</var>.
 130             void remove(configuration::NodeRef const& aNode, uno::Reference< css::lang::XEventListener > const& xListener) const;
 131
 132             /// Remove a <type scope='com::sun::star::container'>XContainerListener</type> observing <var>aNode</var>.
 133             void remove(configuration::NodeRef const& aNode, uno::Reference< css::container::XContainerListener > const& xListener) const;
 134
 135             /// Remove a <type scope='com::sun::star::util'>XChangesListener</type> observing <var>aNode</var> and its descendants.
 136             void remove(configuration::NodeRef const& aNode, uno::Reference< css::util::XChangesListener > const& xListener) const;
 137
 138             /// Remove a <type scope='com::sun::star::beans'>XPropertyChangeListener</type> observing <var>aNode</var>.
 139             void removeForAll(configuration::NodeRef const& aNode, uno::Reference< css::beans::XPropertyChangeListener > const& xListener) const;
 140             /// Remove a <type scope='com::sun::star::beans'>XPropertyChangeListener</type> observing the child named <var>aName</var> of <var>aNode</var>.
 141             void removeForOne(configuration::NodeRef const& aNode, uno::Reference< css::beans::XPropertyChangeListener > const& xListener, rtl::OUString const& aName) const;
 142             /// Remove a <type scope='com::sun::star::beans'>XVetoableChangeListener</type> constraining <var>aNode</var>.
 143             void removeForAll(configuration::NodeRef const& aNode, uno::Reference< css::beans::XVetoableChangeListener > const& xListener) const;
 144             /// Remove a <type scope='com::sun::star::beans'>XVetoableChangeListener</type> constraining the child named <var>aName</var> of <var>aNode</var>.
 145             void removeForOne(configuration::NodeRef const& aNode, uno::Reference< css::beans::XVetoableChangeListener > const& xListener, rtl::OUString const& aName) const;
 146
 147             /// Remove a <type scope='com::sun::star::beans'>XVetoableChangeListener</type> constraining <var>aNode</var>.
 148             void remove(configuration::NodeRef const& aNode, uno::Reference< css::beans::XVetoableChangeListener > const& xListener) const;
 149             /** Remove a <type scope='com::sun::star::beans'>XPropertiesChangeListener</type>
 150                 observing any properties of <var>aNode</var>.
 151             */
 152             void remove(configuration::NodeRef const& aNode, uno::Reference< css::beans::XPropertiesChangeListener > const& xListener) const;
 153         // ---------------------------------------------------------------------------------------------------
 154         private:
 155             void operator=(Notifier const& aOther);
 156         };
 157 // ---------------------------------------------------------------------------------------------------
 158
 159 // Thin Wrappers around Notifiers: Provide guarding and convenient access
 160     // Guarding and locking implementations
 161         class NodeAccess;
 162         class TreeElement;
 163
 164         ///  guards a NodeAccess; provides a simple lock for non-data access, does not check for disposed state
 165         class DisposeGuardImpl: private boost::noncopyable
 166         {
 167         public:
 168             DisposeGuardImpl(Notifier const& rNotifier) throw();
 169             ~DisposeGuardImpl() throw ();
 170         };
 171
 172         /// wraps a Notifier (from a node or tree); provides a simple lock for notifier access, does not check for disposed state
 173         class GuardedNotifier
 174         {
 175             UnoApiLock          m_aLock;
 176             Notifier                    m_aNotifier;
 177             DisposeGuardImpl    m_aImpl;
 178         public:
 179             GuardedNotifier(NodeAccess& rNode) throw();
 180         public:
 181             Notifier const&     get()            const  { return m_aNotifier; }
 182
 183             Notifier const&     operator *() const      { return  get(); }
 184             Notifier const*     operator->() const      { return &get(); }
 185         };
 186
 187         /// guards a Node or Tree provides a simple lock for non-data access, does (!) check for disposed state
 188         class DisposeGuard
 189         {
 190             DisposeGuardImpl    m_aImpl;
 191             UnoApiLock          m_aLock;
 192         public:
 193             DisposeGuard(NodeAccess& rNode) throw(css::lang::DisposedException);
 194         };
 195
 196 // ---------------------------------------------------------------------------------------------------
 197     }
 198 }
 199
 200 #endif // CONFIGMGR_CONFIGNOTIFIER_HXX_