include/comphelper/accessiblecontexthelper.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_COMPHELPER_ACCESSIBLECONTEXTHELPER_HXX
  21 #define INCLUDED_COMPHELPER_ACCESSIBLECONTEXTHELPER_HXX
  22
  23 #include <cppuhelper/compbase2.hxx>
  24 #include <com/sun/star/accessibility/XAccessibleContext.hpp>
  25 #include <com/sun/star/accessibility/XAccessibleEventBroadcaster.hpp>
  26 #include <com/sun/star/lang/DisposedException.hpp>
  27 #include <comphelper/broadcasthelper.hxx>
  28 #include <comphelper/comphelperdllapi.h>
  29
  30
  31 namespace comphelper
  32 {
  33
  34
  35     //= IMutex
  36
  37
  38     // This whole thingie here (own mutex classes and such) is a HACK. I hate the SolarMutex.
  39     // See below for more explanations ....
  40
  41     /** abstract interface for implementing a mutex
  42     */
  43     class COMPHELPER_DLLPUBLIC IMutex
  44     {
  45     public:
  46         virtual ~IMutex();
  47         virtual void acquire() = 0;
  48         virtual void release() = 0;
  49     };
  50
  51
  52     //= OMutexGuard
  53
  54
  55     class OMutexGuard
  56     {
  57         IMutex* m_pMutex;
  58     public:
  59         inline OMutexGuard( IMutex* _pMutex )
  60             :m_pMutex( _pMutex )
  61         {
  62             if ( m_pMutex )
  63                 m_pMutex->acquire();
  64         }
  65
  66         inline ~OMutexGuard( )
  67         {
  68             if ( m_pMutex )
  69                 m_pMutex->release();
  70         }
  71     };
  72
  73
  74     //= OAccessibleContextHelper
  75
  76
  77     class OContextHelper_Impl;
  78     typedef ::cppu::WeakAggComponentImplHelper2 <   css::accessibility::XAccessibleContext,
  79                                                     css::accessibility::XAccessibleEventBroadcaster
  80                                                 >   OAccessibleContextHelper_Base;
  81
  82     /** helper class for implementing an AccessibleContext
  83     */
  84     class COMPHELPER_DLLPUBLIC OAccessibleContextHelper
  85                 :public ::comphelper::OBaseMutex
  86                 ,public OAccessibleContextHelper_Base
  87     {
  88     private:
  89         OContextHelper_Impl*    m_pImpl;
  90
  91     protected:
  92         virtual ~OAccessibleContextHelper( );
  93
  94         /** ctor
  95
  96             <p>If you need additional object safety for your class, and want to ensure that your own
  97             mutex is locked before the mutex this class provides is, than use this ctor.</p>
  98
  99             <p>Beware that this is a hack. Unfortunately, OpenOffice.org has two different mutex hierarchies,
 100             which are not compatible. In addition, wide parts of the code (especially VCL) is not thread-safe,
 101             but instead relies on a <em>single global mutex</em>. As a consequence, components using
 102             directly or indirectly such code need to care for this global mutex. Yes, this is as ugly as
 103             anything.</p>
 104
 105             <p>Note that the external lock is used as additional lock, not as the only one. The own mutex of the
 106             instance is used for internal actions, and every action which potentially involves external code
 107             (for instance every call to a virtual method overridden by derivees) is <em>additionally</em> and
 108             <em>first</em> guarded by with the external lock.</p>
 109
 110             <p>Beware of the lifetime of the lock - you must ensure that the lock exists at least as long as
 111             the context does. A good approach to implement the lock may be to derive you own context
 112             not only from OAccessibleContextHelper, but also from IMutex.</p>
 113
 114             <p>One more note. This lock is definitely not used once the dtor is reached. Means whatever
 115             the dtor implementation does, it does <em>not</em> guard the external lock. See this as a contract.
 116             <br/>You should ensure the same thing for own derivees which do not supply the lock themself,
 117             but get them from yet another derivee.</p>
 118             @see forgetExternalLock
 119         */
 120         OAccessibleContextHelper( IMutex* _pExternalLock );
 121
 122         /** late construction
 123         @param _rxAccessible
 124             the Accessible object which created this context.
 125             <p>If your derived implementation implements the XAccessible (and does not follow the proposed
 126             separation of XAccessible from XAccessibleContext), you may pass <code>this</code> here.</p>
 127
 128             <p>The object is hold weak, so its life time is not affected.</p>
 129
 130             <p>The object is needed for performance reasons: for <method>getAccessibleIndexInParent</method>,
 131             all children (which are XAccessible's theirself) of our parent have to be asked. If we know our
 132             XAccessible, we can compare it with all the children, instead of asking all children for their
 133             context and comparing this context with ourself.</p>
 134         */
 135         void    lateInit( const css::uno::Reference< css::accessibility::XAccessible >& _rxAccessible );
 136
 137         /** retrieves the creator previously set with <method>lateInit</method>
 138         */
 139         css::uno::Reference< css::accessibility::XAccessible >
 140                 getAccessibleCreator( ) const;
 141
 142     private:
 143         /** forgets the reference to the external lock, if present.
 144
 145             <p>This means any further locking will not be guard the external lock anymore, never.</p>
 146
 147             <p>To be used in derived classes which do not supply the external lock themself, but instead get
 148             them passed from own derivees (or clients).</p>
 149         */
 150         void    forgetExternalLock();
 151
 152     public:
 153         // XAccessibleEventBroadcaster
 154         virtual void SAL_CALL addAccessibleEventListener( const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener ) throw (css::uno::RuntimeException, std::exception) override;
 155         virtual void SAL_CALL removeAccessibleEventListener( const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener ) throw (css::uno::RuntimeException, std::exception) override;
 156
 157         // XAccessibleContext - still waiting to be overwritten
 158         virtual sal_Int32 SAL_CALL getAccessibleChildCount(  ) throw (css::uno::RuntimeException, std::exception) override = 0;
 159         virtual css::uno::Reference< css::accessibility::XAccessible > SAL_CALL getAccessibleChild( sal_Int32 i ) throw (css::lang::IndexOutOfBoundsException, css::uno::RuntimeException, std::exception) override = 0;
 160         virtual css::uno::Reference< css::accessibility::XAccessible > SAL_CALL getAccessibleParent(  ) throw (css::uno::RuntimeException, std::exception) override = 0;
 161         virtual sal_Int16 SAL_CALL getAccessibleRole(  ) throw (css::uno::RuntimeException, std::exception) override = 0;
 162         virtual OUString SAL_CALL getAccessibleDescription(  ) throw (css::uno::RuntimeException, std::exception) override = 0;
 163         virtual OUString SAL_CALL getAccessibleName(  ) throw (css::uno::RuntimeException, std::exception) override = 0;
 164         virtual css::uno::Reference< css::accessibility::XAccessibleRelationSet > SAL_CALL getAccessibleRelationSet(  ) throw (css::uno::RuntimeException, std::exception) override = 0;
 165         virtual css::uno::Reference< css::accessibility::XAccessibleStateSet > SAL_CALL getAccessibleStateSet(  ) throw (css::uno::RuntimeException, std::exception) override = 0;
 166
 167         // XAccessibleContext - default implementations
 168         /** default implementation for retrieving the index of this object within the parent
 169             <p>This basic implementation here returns the index <code>i</code> of the child for which
 170                 <code>&lt;parent&gt;.getAccessibleChild( i )</code> equals our creator.</p>
 171         */
 172         virtual sal_Int32 SAL_CALL getAccessibleIndexInParent(  ) throw (css::uno::RuntimeException, std::exception) override;
 173         /** default implementation for retrieving the locale
 174             <p>This basic implementation returns the locale of the parent context,
 175             as retrieved via getAccessibleParent()->getAccessibleContext.</p>
 176         */
 177         virtual css::lang::Locale SAL_CALL getLocale(  ) throw (css::accessibility::IllegalAccessibleComponentStateException, css::uno::RuntimeException, std::exception) override;
 178
 179     public:
 180         // helper struct for granting selective access rights
 181         struct OAccessControl
 182         {
 183             friend class OContextEntryGuard;
 184             friend class OContextHelper_Impl;
 185             friend class OExternalLockGuard;
 186         private:
 187             OAccessControl() { }
 188         };
 189
 190         // ensures that the object is alive
 191         inline  void            ensureAlive( const OAccessControl& ) const;
 192         inline  IMutex*         getExternalLock( const OAccessControl& );
 193         inline  ::osl::Mutex&   GetMutex( const OAccessControl& );
 194
 195     protected:
 196         // OComponentHelper
 197         virtual void SAL_CALL disposing() override;
 198
 199     protected:
 200         // helper
 201         /** notifies all AccessibleEventListeners of a certain event
 202
 203         @precond    not to be called with our mutex locked
 204         @param  _nEventId
 205             the id of the event. See AccessibleEventType
 206         @param  _rOldValue
 207             the old value to be notified
 208         @param  _rNewValue
 209             the new value to be notified
 210         */
 211         void NotifyAccessibleEvent(
 212                     const sal_Int16 _nEventId,
 213                     const css::uno::Any& _rOldValue,
 214                     const css::uno::Any& _rNewValue
 215                 );
 216
 217         // life time control
 218         /// checks whether the object is alive (returns <TRUE/> then) or disposed
 219         bool    isAlive() const;
 220         /// checks for being alive. If the object is already disposed (i.e. not alive), an exception is thrown.
 221         void        ensureAlive() const;
 222
 223         /** ensures that the object is disposed.
 224         @precond
 225             to be called from within the destructor of your derived class only!
 226         */
 227         void        ensureDisposed( );
 228
 229         /** shortcut for retrieving the context of the parent (returned by getAccessibleParent)
 230         */
 231         css::uno::Reference< css::accessibility::XAccessibleContext >
 232                     implGetParentContext();
 233
 234         // access to the base class' broadcast helper/mutex
 235         ::cppu::OBroadcastHelper&       GetBroadcastHelper()        { return rBHelper; }
 236         const ::cppu::OBroadcastHelper& GetBroadcastHelper() const  { return rBHelper; }
 237         ::osl::Mutex&                   GetMutex()                  { return m_aMutex; }
 238         IMutex*                         getExternalLock( );
 239     };
 240
 241
 242     inline  void OAccessibleContextHelper::ensureAlive( const OAccessControl& ) const
 243     {
 244         ensureAlive();
 245     }
 246
 247
 248     inline  IMutex* OAccessibleContextHelper::getExternalLock( const OAccessControl& )
 249     {
 250         return getExternalLock();
 251     }
 252
 253
 254     inline  ::osl::Mutex& OAccessibleContextHelper::GetMutex( const OAccessControl& )
 255     {
 256         return GetMutex();
 257     }
 258
 259
 260     //= OContextEntryGuard
 261
 262     typedef ::osl::ClearableMutexGuard  OContextEntryGuard_Base;
 263     /** helper class for guarding the entry into OAccessibleContextHelper methods.
 264
 265         <p>The class has two responsibilities:
 266         <ul><li>it locks the mutex of an OAccessibleContextHelper instance, as long as the guard lives</li>
 267             <li>it checks if an given OAccessibleContextHelper instance is alive, else an exception is thrown
 268                 our of the constructor of the guard</li>
 269         </ul>
 270         <br/>
 271         This makes it your first choice (hopefully :) for guarding any interface method implementations of
 272         you derived class.
 273         </p>
 274     */
 275     class OContextEntryGuard : public OContextEntryGuard_Base
 276     {
 277     public:
 278         /** constructs the guard
 279
 280             <p>The given context (it's mutex, respectively) is locked, and an exception is thrown if the context
 281             is not alive anymore. In the latter case, of course, the mutex is freed, again.</p>
 282
 283         @param _pContext
 284             the context which shall be guarded
 285         @precond <arg>_pContext</arg> != NULL
 286         */
 287         inline OContextEntryGuard( OAccessibleContextHelper* _pContext );
 288
 289         /** destructs the guard.
 290             <p>The context (it's mutex, respectively) is unlocked.</p>
 291         */
 292         inline ~OContextEntryGuard();
 293     };
 294
 295
 296     inline OContextEntryGuard::OContextEntryGuard( OAccessibleContextHelper* _pContext  )
 297         :OContextEntryGuard_Base( _pContext->GetMutex( OAccessibleContextHelper::OAccessControl() ) )
 298     {
 299         _pContext->ensureAlive( OAccessibleContextHelper::OAccessControl() );
 300     }
 301
 302
 303     inline OContextEntryGuard::~OContextEntryGuard()
 304     {
 305     }
 306
 307
 308     //= OExternalLockGuard
 309
 310     class OExternalLockGuard
 311             :public OMutexGuard
 312             ,public OContextEntryGuard
 313     {
 314     public:
 315         inline OExternalLockGuard( OAccessibleContextHelper* _pContext );
 316         inline ~OExternalLockGuard( );
 317     };
 318
 319
 320     inline OExternalLockGuard::OExternalLockGuard( OAccessibleContextHelper* _pContext )
 321         :OMutexGuard( _pContext->getExternalLock( OAccessibleContextHelper::OAccessControl() ) )
 322         ,OContextEntryGuard( _pContext )
 323     {
 324         // Only lock the external mutex,
 325         // release the ::osl::Mutex of the OAccessibleContextHelper instance.
 326         // If you call into another UNO object with locked ::osl::Mutex,
 327         // this may lead to dead locks.
 328         clear();
 329     }
 330
 331
 332     inline OExternalLockGuard::~OExternalLockGuard( )
 333     {
 334     }
 335
 336
 337 }   // namespace comphelper
 338
 339
 340 #endif // INCLUDED_COMPHELPER_ACCESSIBLECONTEXTHELPER_HXX
 341
 342
 343 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */