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