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