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_XAggregation_idl__
24#define __com_sun_star_uno_XAggregation_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29
30//=============================================================================
31
32module com { module sun { module star { module uno {
33
34//=============================================================================
35/** Objects which implement this interface can become aggregates of
36	a delegator.
37
38	<p>That means if an object "A" aggregates "B", "A" can provide all
39	or some of the interfaces of "B". Whenever the method
40	<member>XInterface::queryInterface()</member>
41	is called on either of the objects, the call will be forwarded
42	to object "A". Object "A" now can determine whether to use the
43	interfaces of "A" or "B" or neither. Actually, any number of
44	aggregates can be used, even nested ones (aggregated objects which are
45	delegators by themselves).
46
47	<p>The following rules are to be observed:
48	<ol>
49	<li>All calls to <member>XInterface::acquire()</member>
50	which are made before the delegator was set (using the method
51	<member>XAggregation::setDelegator()</member>) must not be taken back
52	(using the method <member>XInterface::release()</member>)
53	before the delegation is removed by calling
54	<code>xAggregation-&gt;setDelegator(NULL)</code>.
55
56	<li>The constructor of a delegator has to increment its
57	own reference count by calling its method
58	<member>XInterface::acquire()</member>
59	before it sets itself to any aggregate using the method
60	<member>XAggregation::setDelegator()</member>. After that
61	call it has to reset its own reference count without the
62	destructor getting called.
63
64	<li>The destructor of a delegator has to reset the delegator in
65	its aggregated objects by calling their method
66	<member>XAggregation::setDelegator()</member> with
67	<const>NULL</const> before it releases its reference to
68	its aggregated objects.
69	</ol>
70
71	@deprecated
72    Aggregation will no longer be supported as a high-level concept of UNO.
73    You may still have the option to implement an UNO object consisting of
74    several single objects in your specific programming language, though this
75    depends on your programming language.
76*/
77published interface XAggregation: com::sun::star::uno::XInterface
78{
79	//-------------------------------------------------------------------------
80	/** sets the object to which all calls to the method
81		<member>XInterface::queryInterface()</member>
82		have to be forwarded. @
83
84		@param xDelegator
85		specifies the object which handles the calls to
86		<member>XInterface::queryInterface()</member>.
87		If <var>xDelegator</var> is <const>NULL</const>, the delegator is
88		removed and thus the object becomes its own delegator and has
89		to handle calls to the method
90		<member>XInterface::queryInterface()</member>
91		itself.
92
93		@see XAggregation::queryAggregation
94	*/
95	void setDelegator( [in] com::sun::star::uno::XInterface pDelegator );
96
97	//-------------------------------------------------------------------------
98	/** is similar to <member>XInterface::queryInterface()</member>,
99		but it is to be processed directly without being forwarded to the
100		delegator. @
101
102		<p>This method is only called from within an implementation of
103		<member>XInterface::queryInterface()</member>
104		or <member>XAggregation::queryAggregation()</member>. This method
105		is to be called by the delegator if it does not implement the
106		interface itself. An object which got aggregated cannot depend
107		on getting its own interface when it calls the method
108		<member>XInterface::queryInterface()</member>.
109
110		@see XAggregation::setDelegator
111	*/
112	any queryAggregation( [in] type aType );
113
114};
115
116//=============================================================================
117
118}; }; }; };
119
120#endif
121