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