diff options
Diffstat (limited to 'offapi/com/sun/star/util/XCloseable.idl')
| -rw-r--r-- | offapi/com/sun/star/util/XCloseable.idl | 120 |
1 files changed, 120 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 000000000..ad39183c8 --- /dev/null +++ b/offapi/com/sun/star/util/XCloseable.idl @@ -0,0 +1,120 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0 . + */ +#ifndef __com_sun_star_util_XCloseable_idl__ +#define __com_sun_star_util_XCloseable_idl__ + +#include <com/sun/star/uno/XInterface.idl> +#include <com/sun/star/util/XCloseBroadcaster.idl> + + +module com { module sun { module star { module util { + +/** makes it possible to release any objects in an 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 com::sun::star::lang::XComponent::dispose())</li> + <li>closed (if it supports XCloseable::close())</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 canceled really). 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 necessary. + </p> + + <p> + Base interface XCloseBroadcaster makes it possible that any listener + which is interested 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 + */ +published interface XCloseable: XCloseBroadcaster +{ + /** try to close the object + + <p> + Must definitely be called before com::sun::star::lang::XComponent::dispose(). + But nobody can guarantee real closing of called object - because it can disagree with that if any + still running processes can't be canceled yet. It's not allowed to block this call till internal + operations will be finished here. They must be canceled or call must return immediately by throwing + the CloseVetoException. Otherwise (if nothing exist to disagree) it must return normally. + </p> + + <p> + Before any internal processes will be canceled, all registered XCloseListener + must be notified. Any of them can disagree with a CloseVetoException 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 XCloseListener::queryClosing(). After his operations was finished + he MUST try to close it again. If the closing object itself 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. Normally it's possible to throw + a com::sun::star::lang::DisposedException for already disposed or closed objects + (which represent a com::sun::star::uno::RuntimeException 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 this closing object to anyone 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 useful for a generic UI handling. + + @throws 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 + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |