udkapi/com/sun/star/uno/XAggregation.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27 #ifndef __com_sun_star_uno_XAggregation_idl__
  28 #define __com_sun_star_uno_XAggregation_idl__
  29
  30 #ifndef __com_sun_star_uno_XInterface_idl__
  31 #include <com/sun/star/uno/XInterface.idl>
  32 #endif
  33
  34 //=============================================================================
  35
  36 module com { module sun { module star { module uno {
  37
  38 //=============================================================================
  39 /** Objects which implement this interface can become aggregates of
  40     a delegator.
  41
  42     <p>That means if an object "A" aggregates "B", "A" can provide all
  43     or some of the interfaces of "B". Whenever the method
  44     <member>XInterface::queryInterface()</member>
  45     is called on either of the objects, the call will be forwarded
  46     to object "A". Object "A" now can determine whether to use the
  47     interfaces of "A" or "B" or neither. Actually, any number of
  48     aggregates can be used, even nested ones (aggregated objects which are
  49     delegators by themselves).
  50
  51     <p>The following rules are to be observed:
  52     <ol>
  53     <li>All calls to <member>XInterface::acquire()</member>
  54     which are made before the delegator was set (using the method
  55     <member>XAggregation::setDelegator()</member>) must not be taken back
  56     (using the method <member>XInterface::release()</member>)
  57     before the delegation is removed by calling
  58     <code>xAggregation-&gt;setDelegator(NULL)</code>.
  59
  60     <li>The constructor of a delegator has to increment its
  61     own reference count by calling its method
  62     <member>XInterface::acquire()</member>
  63     before it sets itself to any aggregate using the method
  64     <member>XAggregation::setDelegator()</member>. After that
  65     call it has to reset its own reference count without the
  66     destructor getting called.
  67
  68     <li>The destructor of a delegator has to reset the delegator in
  69     its aggregated objects by calling their method
  70     <member>XAggregation::setDelegator()</member> with
  71     <const>NULL</const> before it releases its reference to
  72     its aggregated objects.
  73     </ol>
  74
  75     @deprecated
  76     Aggregation will no longer be supported as a high-level concept of UNO.
  77     You may still have the option to implement an UNO object consisting of
  78     several single objects in your specific programming language, though this
  79     depends on your programming language.
  80 */
  81 published interface XAggregation: com::sun::star::uno::XInterface
  82 {
  83     //-------------------------------------------------------------------------
  84     /** sets the object to which all calls to the method
  85         <member>XInterface::queryInterface()</member>
  86         have to be forwarded. @
  87
  88         @param xDelegator
  89         specifies the object which handles the calls to
  90         <member>XInterface::queryInterface()</member>.
  91         If <var>xDelegator</var> is <const>NULL</const>, the delegator is
  92         removed and thus the object becomes its own delegator and has
  93         to handle calls to the method
  94         <member>XInterface::queryInterface()</member>
  95         itself.
  96
  97         @see XAggregation::queryAggregation
  98     */
  99     void setDelegator( [in] com::sun::star::uno::XInterface pDelegator );
 100
 101     //-------------------------------------------------------------------------
 102     /** is similar to <member>XInterface::queryInterface()</member>,
 103         but it is to be processed directly without being forwarded to the
 104         delegator. @
 105
 106         <p>This method is only called from within an implementation of
 107         <member>XInterface::queryInterface()</member>
 108         or <member>XAggregation::queryAggregation()</member>. This method
 109         is to be called by the delegator if it does not implement the
 110         interface itself. An object which got aggregated cannot depend
 111         on getting its own interface when it calls the method
 112         <member>XInterface::queryInterface()</member>.
 113
 114         @see XAggregation::setDelegator
 115     */
 116     any queryAggregation( [in] type aType );
 117
 118 };
 119
 120 //=============================================================================
 121
 122 }; }; }; };
 123
 124 #endif