xref: /aoo41x/main/udkapi/com/sun/star/uno/XWeak.idl (revision 408a4873)
1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_uno_XWeak_idl__
24#define __com_sun_star_uno_XWeak_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29
30#ifndef __com_sun_star_uno_XAdapter_idl__
31#include <com/sun/star/uno/XAdapter.idl>
32#endif
33
34
35//=============================================================================
36
37 module com {  module sun {  module star {  module uno {
38
39//=============================================================================
40
41// DocMerge from xml: interface com::sun::star::uno::XWeak
42/** the server-side interface to a weak object.
43
44
45
46	<p>This interface is proxy to the adapted object.
47	In order to make it possible to have weak references to objects,
48	the <type>XAdapter</type> interface must be implemented to provide
49	a weak adapter for the clients.
50
51	<h4>Concept of weak referencing:</h4>
52
53	</p>
54	<p>This module specifies the interfaces for implementing and using
55	weak references.</p>
56	<p>
57
58	</p>
59	<p>The sense of weak references is to hold a reference to an object
60	without affecting the lifetime of the object. That means that a weak
61	reference may become invalid, at any time, if the referenced object dies.
62
63	</p>
64	<p>The following interfaces describe one way to handle weak references
65	by providing a weak adapter. The weak object has to provide this
66	adapter if anyone wants to hold a weak reference. To separate their
67	lifetimes, the adapter and the original object must not share the same
68	reference counter.  The weak reference is in fact only a hard reference
69	to the adapter, which knows - but does not hold - the original object.
70	That means that the implementation and synchronization of weak
71	referencing is the responsibility of the object.  The following
72	interfaces are involved in the concept of weak referencing:
73
74	<dl>
75	<dt>
76	<type>XWeak</type>
77	</dt>
78	<dd>is the server-side interface of the referred object. This
79	referred object must support the <type>XAdapter</type> interface.
80
81	</dd>
82	<dt>
83	<type>XReference</type>
84	</dt>
85	<dd>is a client-side interface which must be implemented by
86	the holder of any weak reference. It is used for notification
87	when the adapted object dies.
88
89	</dd>
90	</dl>
91	</p>
92 */
93published interface XWeak: com::sun::star::uno::XInterface
94{
95	//-------------------------------------------------------------------------
96
97	// DocMerge from xml: method com::sun::star::uno::XWeak::queryAdapter
98	/** queries the weak adapter.
99
100
101
102		<p>It is important that the adapter must know, but not hold
103		the adapted object. If the adapted object dies, all references
104		to the adapter have to be notified to release the adapter.
105
106		</p>
107	 */
108	com::sun::star::uno::XAdapter queryAdapter();
109
110};
111
112//=============================================================================
113
114}; }; }; };
115
116/*=============================================================================
117
118=============================================================================*/
119#endif
120