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_lang_XComponent_idl__ 24#define __com_sun_star_lang_XComponent_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 lang { 33 34 published interface XEventListener; 35 36//============================================================================= 37 38// DocMerge from xml: interface com::sun::star::lang::XComponent 39/** allows to exclicitly free resources and break cyclic references. 40 41 <p>Actually the real lifetime of an UNO object is controlled by 42 references kept on interfaces of this object. But there are two 43 distinct meanings in keeping a reference to an interface: 44 1st to own the object and 2nd to know the object. 45 46 <p>You are only allowed to keep references of interfaces 47 to UNO objects if you are by definition the owner of that object or 48 your reference is very temporary or you have registered an 49 EventListener at that object and release the reference when 50 "disposing" is called.</p> 51 */ 52published interface XComponent: com::sun::star::uno::XInterface 53{ 54 //------------------------------------------------------------------------- 55 56 // DocMerge from xml: method com::sun::star::lang::XComponent::dispose 57 /** The owner of an object calls this method to explicitly free all 58 resources kept by this object and thus break cyclic references. 59 60 <p>Only the owner of this object is allowed to call this method. 61 The object should release all resources and references in the 62 easiest possible manner ( for instance no serialization should 63 take place anymore ). 64 </p> 65 <p> 66 The object must notify all registered listeners using the method 67 <member>XEventListener::disposing</member>. All notfied objects 68 should release there references to this object without 69 calling <member>XComponent::removeEventListener</member> 70 (the disposed object will release the listeners eitherway). 71 </p> 72 73 <p>After this method has been called, the object should behave as passive 74 as possible, thus it should ignore all calls 75 in case it can comply with its specification (for instance addEventListener()). 76 Often the object can't fulfill its specification anymore, 77 in this case it must throw the <type>DisposedException</type> 78 (which is derived from <type scope="com::sun::star::uno">RuntimeException</type>) 79 when it gets called.</p> 80 81 <p>For some objects no real owner can be identified, thus it can be 82 disposed from multiple reference holders. In this case 83 the object should be able to cope with multiple dispose()-calls (which 84 are inevitable in a multithreaded environment). 85 */ 86 void dispose(); 87 88 //------------------------------------------------------------------------- 89 90 // DocMerge from xml: method com::sun::star::lang::XComponent::addEventListener 91 /** adds an event listener to the object. 92 93 <p>The broadcaster fires the disposing method of this listener 94 if the <member>XComponent::dispose</member> method is called.</p> 95 96 <p>It is suggested to allow multiple registration of the same listener, 97 thus for each time a listener is added, it has to be removed.</p> 98 99 <p>If this <type scope="com::sun::star::lang">XComponent</type> is 100 already disposed when <member scope="com::sun::star::lang"> 101 XComponent::addEventListener</member> is called, the call will not fail 102 with a <type scope="com::sun::star::lang">DisposedException</type>, but 103 the caller will be notified via the 104 <member scope="com::sun::star::lang">XEventListener::disposing</member> 105 callback. This callback can occur synchronously within the 106 <member scope="com::sun::star::lang">XComponent::addEventListener 107 </member> call.</p> 108 109 @see XComponent::removeEventListener 110 */ 111 void addEventListener( [in] XEventListener xListener ); 112 113 //------------------------------------------------------------------------- 114 115 // DocMerge from xml: method com::sun::star::lang::XComponent::removeEventListener 116 /** removes an event listener from the listener list. 117 118 <p>It is a "noop" if the specified listener is not registered.</p> 119 120 <p>It is suggested to allow multiple registration of the same listener, 121 thus for each time a listener is added, it has to be removed. 122 123 <p>If this <type scope="com::sun::star::lang">XComponent</type> is 124 already disposed when <member scope="com::sun::star::lang"> 125 XComponent::removeEventListener</member> is called, the call will not 126 fail with a <type scope="com::sun::star::lang">DisposedException</type>, 127 but will rather be ignored silently.</p> 128 129 @see XComponent::addEventListener 130 */ 131 void removeEventListener( [in] XEventListener aListener ); 132 133}; 134 135//============================================================================= 136 137}; }; }; }; 138 139#endif 140