#97426# first revision of interfaces for close mechanism

1 files changed, 169 insertions, 0 deletions

diff --git a/offapi/com/sun/star/util/XCloseable.idl b/offapi/com/sun/star/util/XCloseable.idl
new file mode 100644
index 000000000000..7b7c7e2952a6
--- /dev/null
+++ b/offapi/com/sun/star/util/XCloseable.idl
@@ -0,0 +1,169 @@
+/*************************************************************************
+ *
+ *  $RCSfile: XCloseable.idl,v $
+ *
+ *  $Revision: 1.1 $
+ *
+ *  last change: $Author: as $ $Date: 2002-04-05 06:54:27 $
+ *
+ *  The Contents of this file are made available subject to the terms of
+ *  either of the following licenses
+ *
+ *         - GNU Lesser General Public License Version 2.1
+ *         - Sun Industry Standards Source License Version 1.1
+ *
+ *  Sun Microsystems Inc., October, 2000
+ *
+ *  GNU Lesser General Public License Version 2.1
+ *  =============================================
+ *  Copyright 2000 by Sun Microsystems, Inc.
+ *  901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License version 2.1, as published by the Free Software Foundation.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *  MA  02111-1307  USA
+ *
+ *
+ *  Sun Industry Standards Source License Version 1.1
+ *  =================================================
+ *  The contents of this file are subject to the Sun Industry Standards
+ *  Source License Version 1.1 (the "License"); You may not use this file
+ *  except in compliance with the License. You may obtain a copy of the
+ *  License at http://www.openoffice.org/license.html.
+ *
+ *  Software provided under this License is provided on an "AS IS" basis,
+ *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
+ *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
+ *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
+ *  See the License for the specific provisions governing your rights and
+ *  obligations concerning the Software.
+ *
+ *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
+ *
+ *  Copyright: 2000 by Sun Microsystems, Inc.
+ *
+ *  All Rights Reserved.
+ *
+ *  Contributor(s): _______________________________________
+ *
+ *
+ ************************************************************************/
+#ifndef __com_sun_star_util_XClosable_idl__
+#define __com_sun_star_util_XClosable_idl__
+
+#ifndef __com_sun_star_uno_XInterface_idl__
+#include <com/sun/star/uno/XInterface.idl>
+#endif
+
+#ifndef __com_sun_star_util_XCloseBroadcaster_idl__
+#include <com/sun/star/util/XCloseBroadcaster.idl>
+#endif
+
+//=============================================================================
+
+module com {  module sun {  module star {  module util {
+
+//=============================================================================
+/** makes it possible to release any objects in a ordered manner by using
+    a two-step mechanism
+
+    <p>
+    If an object should be terminated, it can be:<br>
+    <ul>
+        <li>disposed (if it supports <member scope="com::sun::star::lang">XComponent::dispose()</member>)</li>
+        <li>closed   (if it supports <member>XCloseable::close()</member>)</li>
+    </ul>
+    First version gives the object no chance to disagree with that (e.g. if a
+    process is still running and can't be cancelled realy). Last version
+    provides this possibility, but can't guarantee real termination of called object.
+    It depends from the environment of an object, if one or both mechanism are neccessary.
+    </p>
+
+    <p>
+    Base interface <type>XCloseBroadcaster</type> makes it possible that any listener
+    which is interrested on life time of listened object ...
+    <ul>
+        <li>can get a notification about closing of it</li>
+        <li>or can have a veto to break that.</li>
+    </ul>
+    </p>
+
+    @see com::sun::star::lang::XComponent::dispose()
+    @see XCloseBroadcaster
+    @see XCloseListener
+ */
+interface XCloseable: XCloseBroadcaster
+{
+    //-------------------------------------------------------------------------
+    /** try to close the object
+
+        <p>
+        Must definitly be called before <member scope="com::sun::star::lang">XComponent::dispose()</member>.
+        But nobody can guarentee real closing of called object - because it can disagree with that if any
+        still running processes can't be cancelled yet. It's not allowed to block this call till internal
+        operations will be finished here. They must be cancelled or call must return imediatly by throwing
+        the <type>CloseVetoException</type>.  Otherwise (if nothing exist to disagree) it must return normaly.
+        </p>
+
+        <p>
+        Before any internal processes will be cancelled, all registered <type>XCloseListener</type>
+        must be notified. Any of them can disagree with a <type>CloseVetoException</type> too.
+        It's forbidden to catch this exception inside the called close() method because the caller must
+        get this information!
+        </p>
+
+        <p>
+        If somewhere disagree with a CloseVetoException it will not clear who has to close the object again
+        after still running processes was finished. The parameter <var>DeliverOwnership</var> regulate that.
+        If it is set to <FALSE/> the caller of the method close() will be the owner of this object in every case.
+        Then it's not allowed to call close() from any other place (may a registered XCloseListener).
+        If it is set to <TRUE/> the caller gives up his ownership. If a XCloseListener throw the veto exception
+        he will be the new owner of the closing object. This information is passed to the listener by a parameter of
+        his notification method <member>XCloseListener::queryClosing()</member>. After his operations was finished
+        he MUST try to close it again. If the closing object itselfs disagree by an exception and the parameter
+        <var>DeliverOwnership</var> was set to <TRUE/> the object will be his own owner with all consequences of that.
+        <br><strong>Note:</strong><br>
+        There is no way to get the ownership back if it was delivered!
+        </p>
+
+        <p>
+        If this method was already called on an object it should return without any reaction. Normaly it's possible to throw
+        a <type scope="com::sun::star::lang">DisposedException</type> for already disposed or closed objects
+        (which represent a <type scope="com::sun::star::uno">RuntimeException</type> and can be thrown by every interface call),
+        but it shouldn't be used here. The veto exception should be the only way to indicates the result.
+        </p>
+
+        @param DeliverOwnership
+                <TRUE/> delegates the ownership of ths closing object to any one which throw the CloseVetoException.
+                This new owner has to close the closing object again if his still running processes will be finished.
+                <br>
+                <FALSE/> let the ownership at the original one which called the close() method. He must react for possible
+                CloseVetoExceptions and try it again at a later time. This can be usefull for a generic UI handling.
+
+        @raises CloseVetoException
+            indicates that the closing object himself or any of his currently registered listener disagree with this close() request.
+
+        @see XCloseListener
+        @see CloseVetoException
+        @see com::sun::star::lang::XComponent::dispose()
+        @see com::sun::star::lang::DisposedException
+     */
+    void close( [in] boolean DeliverOwnership )
+            raises( CloseVetoException );
+};
+
+//=============================================================================
+
+}; }; }; };
+
+#endif