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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XWeak.idl,v $
  10  * $Revision: 1.12 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_uno_XWeak_idl__
  31 #define __com_sun_star_uno_XWeak_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_uno_XAdapter_idl__
  38 #include <com/sun/star/uno/XAdapter.idl>
  39 #endif
  40
  41
  42 //=============================================================================
  43
  44  module com {  module sun {  module star {  module uno {
  45
  46 //=============================================================================
  47
  48 // DocMerge from xml: interface com::sun::star::uno::XWeak
  49 /** the server-side interface to a weak object.
  50
  51
  52
  53     <p>This interface is proxy to the adapted object.
  54     In order to make it possible to have weak references to objects,
  55     the <type>XAdapter</type> interface must be implemented to provide
  56     a weak adapter for the clients.
  57
  58     <h4>Concept of weak referencing:</h4>
  59
  60     </p>
  61     <p>This module specifies the interfaces for implementing and using
  62     weak references.</p>
  63     <p>
  64
  65     </p>
  66     <p>The sense of weak references is to hold a reference to an object
  67     without affecting the lifetime of the object. That means that a weak
  68     reference may become invalid, at any time, if the referenced object dies.
  69
  70     </p>
  71     <p>The following interfaces describe one way to handle weak references
  72     by providing a weak adapter. The weak object has to provide this
  73     adapter if anyone wants to hold a weak reference. To separate their
  74     lifetimes, the adapter and the original object must not share the same
  75     reference counter.  The weak reference is in fact only a hard reference
  76     to the adapter, which knows - but does not hold - the original object.
  77     That means that the implementation and synchronization of weak
  78     referencing is the responsibility of the object.  The following
  79     interfaces are involved in the concept of weak referencing:
  80
  81     <dl>
  82     <dt>
  83     <type>XWeak</type>
  84     </dt>
  85     <dd>is the server-side interface of the referred object. This
  86     referred object must support the <type>XAdapter</type> interface.
  87
  88     </dd>
  89     <dt>
  90     <type>XReference</type>
  91     </dt>
  92     <dd>is a client-side interface which must be implemented by
  93     the holder of any weak reference. It is used for notification
  94     when the adapted object dies.
  95
  96     </dd>
  97     </dl>
  98     </p>
  99  */
 100 published interface XWeak: com::sun::star::uno::XInterface
 101 {
 102     //-------------------------------------------------------------------------
 103
 104     // DocMerge from xml: method com::sun::star::uno::XWeak::queryAdapter
 105     /** queries the weak adapter.
 106
 107
 108
 109         <p>It is important that the adapter must know, but not hold
 110         the adapted object. If the adapted object dies, all references
 111         to the adapter have to be notified to release the adapter.
 112
 113         </p>
 114      */
 115     com::sun::star::uno::XAdapter queryAdapter();
 116
 117 };
 118
 119 //=============================================================================
 120
 121 }; }; }; };
 122
 123 /*=============================================================================
 124
 125 =============================================================================*/
 126 #endif