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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_uno_XWeak_idl__
  20 #define __com_sun_star_uno_XWeak_idl__
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23
  24 #include <com/sun/star/uno/XAdapter.idl>
  25
  26
  27
  28  module com {  module sun {  module star {  module uno {
  29
  30 /** the server-side interface to a weak object.
  31
  32
  33
  34     <p>This interface is proxy to the adapted object.
  35     In order to make it possible to have weak references to objects,
  36     the XAdapter interface must be implemented to provide
  37     a weak adapter for the clients.
  38
  39     <h4>Concept of weak referencing:</h4>
  40
  41     </p>
  42     <p>This module specifies the interfaces for implementing and using
  43     weak references.</p>
  44     <p>
  45
  46     </p>
  47     <p>The sense of weak references is to hold a reference to an object
  48     without affecting the lifetime of the object. That means that a weak
  49     reference may become invalid, at any time, if the referenced object dies.
  50
  51     </p>
  52     <p>The following interfaces describe one way to handle weak references
  53     by providing a weak adapter. The weak object has to provide this
  54     adapter if anyone wants to hold a weak reference. To separate their
  55     lifetimes, the adapter and the original object must not share the same
  56     reference counter.  The weak reference is in fact only a hard reference
  57     to the adapter, which knows - but does not hold - the original object.
  58     That means that the implementation and synchronization of weak
  59     referencing is the responsibility of the object.  The following
  60     interfaces are involved in the concept of weak referencing:
  61
  62     <dl>
  63     <dt>
  64     XWeak
  65     </dt>
  66     <dd>is the server-side interface of the referred object. This
  67     referred object must support the XAdapter interface.
  68
  69     </dd>
  70     <dt>
  71     XReference
  72     </dt>
  73     <dd>is a client-side interface which must be implemented by
  74     the holder of any weak reference. It is used for notification
  75     when the adapted object dies.
  76
  77     </dd>
  78     </dl>
  79     </p>
  80  */
  81 published interface XWeak: com::sun::star::uno::XInterface
  82 {
  83     /** queries the weak adapter.
  84
  85
  86
  87         <p>It is important that the adapter must know, but not hold
  88         the adapted object. If the adapted object dies, all references
  89         to the adapter have to be notified to release the adapter.
  90
  91         </p>
  92      */
  93     com::sun::star::uno::XAdapter queryAdapter();
  94
  95 };
  96
  97
  98 }; }; }; };
  99
 100 #endif
 101
 102 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */