1*408a4873SAndrew Rist/************************************************************** 2cdf0e10cSrcweir * 3*408a4873SAndrew Rist * Licensed to the Apache Software Foundation (ASF) under one 4*408a4873SAndrew Rist * or more contributor license agreements. See the NOTICE file 5*408a4873SAndrew Rist * distributed with this work for additional information 6*408a4873SAndrew Rist * regarding copyright ownership. The ASF licenses this file 7*408a4873SAndrew Rist * to you under the Apache License, Version 2.0 (the 8*408a4873SAndrew Rist * "License"); you may not use this file except in compliance 9*408a4873SAndrew Rist * with the License. You may obtain a copy of the License at 10*408a4873SAndrew Rist * 11*408a4873SAndrew Rist * http://www.apache.org/licenses/LICENSE-2.0 12*408a4873SAndrew Rist * 13*408a4873SAndrew Rist * Unless required by applicable law or agreed to in writing, 14*408a4873SAndrew Rist * software distributed under the License is distributed on an 15*408a4873SAndrew Rist * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16*408a4873SAndrew Rist * KIND, either express or implied. See the License for the 17*408a4873SAndrew Rist * specific language governing permissions and limitations 18*408a4873SAndrew Rist * under the License. 19*408a4873SAndrew Rist * 20*408a4873SAndrew Rist *************************************************************/ 21*408a4873SAndrew Rist 22*408a4873SAndrew Rist 23cdf0e10cSrcweir#ifndef __com_sun_star_lang_XComponent_idl__ 24cdf0e10cSrcweir#define __com_sun_star_lang_XComponent_idl__ 25cdf0e10cSrcweir 26cdf0e10cSrcweir#ifndef __com_sun_star_uno_XInterface_idl__ 27cdf0e10cSrcweir#include <com/sun/star/uno/XInterface.idl> 28cdf0e10cSrcweir#endif 29cdf0e10cSrcweir 30cdf0e10cSrcweir//============================================================================= 31cdf0e10cSrcweir 32cdf0e10cSrcweirmodule com { module sun { module star { module lang { 33cdf0e10cSrcweir 34cdf0e10cSrcweir published interface XEventListener; 35cdf0e10cSrcweir 36cdf0e10cSrcweir//============================================================================= 37cdf0e10cSrcweir 38cdf0e10cSrcweir// DocMerge from xml: interface com::sun::star::lang::XComponent 39cdf0e10cSrcweir/** allows to exclicitly free resources and break cyclic references. 40cdf0e10cSrcweir 41cdf0e10cSrcweir <p>Actually the real lifetime of an UNO object is controlled by 42cdf0e10cSrcweir references kept on interfaces of this object. But there are two 43cdf0e10cSrcweir distinct meanings in keeping a reference to an interface: 44cdf0e10cSrcweir 1st to own the object and 2nd to know the object. 45cdf0e10cSrcweir 46cdf0e10cSrcweir <p>You are only allowed to keep references of interfaces 47cdf0e10cSrcweir to UNO objects if you are by definition the owner of that object or 48cdf0e10cSrcweir your reference is very temporary or you have registered an 49cdf0e10cSrcweir EventListener at that object and release the reference when 50cdf0e10cSrcweir "disposing" is called.</p> 51cdf0e10cSrcweir */ 52cdf0e10cSrcweirpublished interface XComponent: com::sun::star::uno::XInterface 53cdf0e10cSrcweir{ 54cdf0e10cSrcweir //------------------------------------------------------------------------- 55cdf0e10cSrcweir 56cdf0e10cSrcweir // DocMerge from xml: method com::sun::star::lang::XComponent::dispose 57cdf0e10cSrcweir /** The owner of an object calls this method to explicitly free all 58cdf0e10cSrcweir resources kept by this object and thus break cyclic references. 59cdf0e10cSrcweir 60cdf0e10cSrcweir <p>Only the owner of this object is allowed to call this method. 61cdf0e10cSrcweir The object should release all resources and references in the 62cdf0e10cSrcweir easiest possible manner ( for instance no serialization should 63cdf0e10cSrcweir take place anymore ). 64cdf0e10cSrcweir </p> 65cdf0e10cSrcweir <p> 66cdf0e10cSrcweir The object must notify all registered listeners using the method 67cdf0e10cSrcweir <member>XEventListener::disposing</member>. All notfied objects 68cdf0e10cSrcweir should release there references to this object without 69cdf0e10cSrcweir calling <member>XComponent::removeEventListener</member> 70cdf0e10cSrcweir (the disposed object will release the listeners eitherway). 71cdf0e10cSrcweir </p> 72cdf0e10cSrcweir 73cdf0e10cSrcweir <p>After this method has been called, the object should behave as passive 74cdf0e10cSrcweir as possible, thus it should ignore all calls 75cdf0e10cSrcweir in case it can comply with its specification (for instance addEventListener()). 76cdf0e10cSrcweir Often the object can't fulfill its specification anymore, 77cdf0e10cSrcweir in this case it must throw the <type>DisposedException</type> 78cdf0e10cSrcweir (which is derived from <type scope="com::sun::star::uno">RuntimeException</type>) 79cdf0e10cSrcweir when it gets called.</p> 80cdf0e10cSrcweir 81cdf0e10cSrcweir <p>For some objects no real owner can be identified, thus it can be 82cdf0e10cSrcweir disposed from multiple reference holders. In this case 83cdf0e10cSrcweir the object should be able to cope with multiple dispose()-calls (which 84cdf0e10cSrcweir are inevitable in a multithreaded environment). 85cdf0e10cSrcweir */ 86cdf0e10cSrcweir void dispose(); 87cdf0e10cSrcweir 88cdf0e10cSrcweir //------------------------------------------------------------------------- 89cdf0e10cSrcweir 90cdf0e10cSrcweir // DocMerge from xml: method com::sun::star::lang::XComponent::addEventListener 91cdf0e10cSrcweir /** adds an event listener to the object. 92cdf0e10cSrcweir 93cdf0e10cSrcweir <p>The broadcaster fires the disposing method of this listener 94cdf0e10cSrcweir if the <member>XComponent::dispose</member> method is called.</p> 95cdf0e10cSrcweir 96cdf0e10cSrcweir <p>It is suggested to allow multiple registration of the same listener, 97cdf0e10cSrcweir thus for each time a listener is added, it has to be removed.</p> 98cdf0e10cSrcweir 99cdf0e10cSrcweir <p>If this <type scope="com::sun::star::lang">XComponent</type> is 100cdf0e10cSrcweir already disposed when <member scope="com::sun::star::lang"> 101cdf0e10cSrcweir XComponent::addEventListener</member> is called, the call will not fail 102cdf0e10cSrcweir with a <type scope="com::sun::star::lang">DisposedException</type>, but 103cdf0e10cSrcweir the caller will be notified via the 104cdf0e10cSrcweir <member scope="com::sun::star::lang">XEventListener::disposing</member> 105cdf0e10cSrcweir callback. This callback can occur synchronously within the 106cdf0e10cSrcweir <member scope="com::sun::star::lang">XComponent::addEventListener 107cdf0e10cSrcweir </member> call.</p> 108cdf0e10cSrcweir 109cdf0e10cSrcweir @see XComponent::removeEventListener 110cdf0e10cSrcweir */ 111cdf0e10cSrcweir void addEventListener( [in] XEventListener xListener ); 112cdf0e10cSrcweir 113cdf0e10cSrcweir //------------------------------------------------------------------------- 114cdf0e10cSrcweir 115cdf0e10cSrcweir // DocMerge from xml: method com::sun::star::lang::XComponent::removeEventListener 116cdf0e10cSrcweir /** removes an event listener from the listener list. 117cdf0e10cSrcweir 118cdf0e10cSrcweir <p>It is a "noop" if the specified listener is not registered.</p> 119cdf0e10cSrcweir 120cdf0e10cSrcweir <p>It is suggested to allow multiple registration of the same listener, 121cdf0e10cSrcweir thus for each time a listener is added, it has to be removed. 122cdf0e10cSrcweir 123cdf0e10cSrcweir <p>If this <type scope="com::sun::star::lang">XComponent</type> is 124cdf0e10cSrcweir already disposed when <member scope="com::sun::star::lang"> 125cdf0e10cSrcweir XComponent::removeEventListener</member> is called, the call will not 126cdf0e10cSrcweir fail with a <type scope="com::sun::star::lang">DisposedException</type>, 127cdf0e10cSrcweir but will rather be ignored silently.</p> 128cdf0e10cSrcweir 129cdf0e10cSrcweir @see XComponent::addEventListener 130cdf0e10cSrcweir */ 131cdf0e10cSrcweir void removeEventListener( [in] XEventListener aListener ); 132cdf0e10cSrcweir 133cdf0e10cSrcweir}; 134cdf0e10cSrcweir 135cdf0e10cSrcweir//============================================================================= 136cdf0e10cSrcweir 137cdf0e10cSrcweir}; }; }; }; 138cdf0e10cSrcweir 139cdf0e10cSrcweir#endif 140