undoapi: detailed the error handling

8 files changed, 305 insertions, 30 deletions

diff --git a/offapi/com/sun/star/document/EmptyUndoStackException.idl b/offapi/com/sun/star/document/EmptyUndoStackException.idl
new file mode 100755
index 000000000000..e003d6af71b9
--- /dev/null
+++ b/offapi/com/sun/star/document/EmptyUndoStackException.idl
@@ -0,0 +1,51 @@
+/*************************************************************************
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * Copyright 2000, 2010 Oracle and/or its affiliates.
+ *
+ * OpenOffice.org - a multi-platform office productivity suite
+ *
+ * This file is part of OpenOffice.org.
+ *
+ * OpenOffice.org is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License version 3
+ * only, as published by the Free Software Foundation.
+ *
+ * OpenOffice.org 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 version 3 for more details
+ * (a copy is included in the LICENSE file that accompanied this code).
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * version 3 along with OpenOffice.org.  If not, see
+ * <http://www.openoffice.org/license.html>
+ * for a copy of the LGPLv3 License.
+ *
+ ************************************************************************/
+
+#ifndef __com_sun_star_document_EmptyUndoStackException_idl__
+#define __com_sun_star_document_EmptyUndoStackException_idl__
+
+#include <com/sun/star/util/InvalidStateException.idl>
+
+//==================================================================================================================
+
+module com { module sun { module star { module document {
+
+//==================================================================================================================
+
+/** is raised when an operation is attemption at an XUndoManager which requires a non-empty stack
+    of undo actions, and this requirement is not fullfilled.
+ */
+exception EmptyUndoStackException : ::com::sun::star::util::InvalidStateException
+{
+};
+
+//==================================================================================================================
+
+}; }; }; };
+
+//==================================================================================================================
+
+#endif
diff --git a/offapi/com/sun/star/document/NotLockedException.idl b/offapi/com/sun/star/document/NotLockedException.idl
new file mode 100755
index 000000000000..d739a6f52033
--- /dev/null
+++ b/offapi/com/sun/star/document/NotLockedException.idl
@@ -0,0 +1,50 @@
+/*************************************************************************
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * Copyright 2000, 2010 Oracle and/or its affiliates.
+ *
+ * OpenOffice.org - a multi-platform office productivity suite
+ *
+ * This file is part of OpenOffice.org.
+ *
+ * OpenOffice.org is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License version 3
+ * only, as published by the Free Software Foundation.
+ *
+ * OpenOffice.org 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 version 3 for more details
+ * (a copy is included in the LICENSE file that accompanied this code).
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * version 3 along with OpenOffice.org.  If not, see
+ * <http://www.openoffice.org/license.html>
+ * for a copy of the LGPLv3 License.
+ *
+ ************************************************************************/
+
+#ifndef __com_sun_star_document_NotLockedException_idl__
+#define __com_sun_star_document_NotLockedException_idl__
+
+#include <com/sun/star/util/InvalidStateException.idl>
+
+//==================================================================================================================
+
+module com { module sun { module star { module document {
+
+//==================================================================================================================
+
+/** is raised when attempt is made to unlock a lockable component which actually is not locked.
+ */
+exception NotLockedException : ::com::sun::star::util::InvalidStateException
+{
+};
+
+//==================================================================================================================
+
+}; }; }; };
+
+//==================================================================================================================
+
+#endif
diff --git a/offapi/com/sun/star/document/UndoContextNotClosedException.idl b/offapi/com/sun/star/document/UndoContextNotClosedException.idl
new file mode 100755
index 000000000000..4f7d746bad1a
--- /dev/null
+++ b/offapi/com/sun/star/document/UndoContextNotClosedException.idl
@@ -0,0 +1,51 @@
+/*************************************************************************
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * Copyright 2000, 2010 Oracle and/or its affiliates.
+ *
+ * OpenOffice.org - a multi-platform office productivity suite
+ *
+ * This file is part of OpenOffice.org.
+ *
+ * OpenOffice.org is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License version 3
+ * only, as published by the Free Software Foundation.
+ *
+ * OpenOffice.org 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 version 3 for more details
+ * (a copy is included in the LICENSE file that accompanied this code).
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * version 3 along with OpenOffice.org.  If not, see
+ * <http://www.openoffice.org/license.html>
+ * for a copy of the LGPLv3 License.
+ *
+ ************************************************************************/
+
+#ifndef __com_sun_star_document_UndoContextNotClosedException_idl__
+#define __com_sun_star_document_UndoContextNotClosedException_idl__
+
+#include <com/sun/star/util/InvalidStateException.idl>
+
+//==================================================================================================================
+
+module com { module sun { module star { module document {
+
+//==================================================================================================================
+
+/** is thrown when an operation is attempted at an <type>XUndoManager</type> which requires all undo
+    contexts to be closed, but this requirement is not fullfilled.
+ */
+exception UndoContextNotClosedException : ::com::sun::star::util::InvalidStateException
+{
+};
+
+//==================================================================================================================
+
+}; }; }; };
+
+//==================================================================================================================
+
+#endif
diff --git a/offapi/com/sun/star/document/UndoFailedException.idl b/offapi/com/sun/star/document/UndoFailedException.idl
new file mode 100755
index 000000000000..4489ac5a0e0d
--- /dev/null
+++ b/offapi/com/sun/star/document/UndoFailedException.idl
@@ -0,0 +1,56 @@
+/*************************************************************************
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * Copyright 2000, 2010 Oracle and/or its affiliates.
+ *
+ * OpenOffice.org - a multi-platform office productivity suite
+ *
+ * This file is part of OpenOffice.org.
+ *
+ * OpenOffice.org is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License version 3
+ * only, as published by the Free Software Foundation.
+ *
+ * OpenOffice.org 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 version 3 for more details
+ * (a copy is included in the LICENSE file that accompanied this code).
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * version 3 along with OpenOffice.org.  If not, see
+ * <http://www.openoffice.org/license.html>
+ * for a copy of the LGPLv3 License.
+ *
+ ************************************************************************/
+
+#ifndef __com_sun_star_document_UndoFailedException_idl__
+#define __com_sun_star_document_UndoFailedException_idl__
+
+#include <com/sun/star/uno/Exception.idl>
+
+//==================================================================================================================
+
+module com { module sun { module star { module document {
+
+//==================================================================================================================
+
+/** thrown when reverting to re-applying an undoable action fails.
+
+    @see XUndoAction::undo
+    @see XUndoManager::undo
+ */
+exception UndoFailedException : ::com::sun::star::uno::Exception
+{
+    /** describes the reason why the operation failed. Usually, this member will carry an exception.
+    */
+    any Reason;
+};
+
+//==================================================================================================================
+
+}; }; }; };
+
+//==================================================================================================================
+
+#endif
diff --git a/offapi/com/sun/star/document/XUndoAction.idl b/offapi/com/sun/star/document/XUndoAction.idl
index 8449a24b9ca7..b47550a3f52f 100755
--- a/offapi/com/sun/star/document/XUndoAction.idl
+++ b/offapi/com/sun/star/document/XUndoAction.idl
@@ -28,6 +28,7 @@
 #define __com_sun_star_document_XUndoAction_idl__
 
 #include <com/sun/star/uno/XInterface.idl>
+#include <com/sun/star/document/UndoFailedException.idl>
 
 //==================================================================================================================
 
@@ -40,12 +41,26 @@ module com { module sun { module star { module document {
 interface XUndoAction
 {
     /** reverts the action represented by the instance
+
+        @throws UndoFailedException
+            if reverting the action failed. In this case, the caller should assume that this is a permanent failure,
+            and take appropriate action, such as discarding the <code>XUndoAction</code> instance, and any possibly
+            depending instances.
     */
-    void    undo();
+    void    undo()
+            raises  (   ::com::sun::star::document::UndoFailedException
+                    );
 
     /** repeats the action represented by the instance, after it had previously been reverted.
+
+        @throws UndoFailedException
+            if repeating the action failed. In this case, the caller should assume that this is a permanent failure,
+            and take appropriate action, such as discarding the <code>XUndoAction</code> instance, and any possibly
+            depending instances.
     */
-    void    redo();
+    void    redo()
+            raises  (   ::com::sun::star::document::UndoFailedException
+                    );
 
     /** is the human-readable, localized description of the action.
     */
diff --git a/offapi/com/sun/star/document/XUndoManager.idl b/offapi/com/sun/star/document/XUndoManager.idl
index 1c8b29083f94..890bf9b4b3c6 100755
--- a/offapi/com/sun/star/document/XUndoManager.idl
+++ b/offapi/com/sun/star/document/XUndoManager.idl
@@ -27,6 +27,10 @@
 #ifndef __com_sun_star_document_XUndoManager_idl__
 #define __com_sun_star_document_XUndoManager_idl__
 
+#include <com/sun/star/document/EmptyUndoStackException.idl>
+#include <com/sun/star/document/NotLockedException.idl>
+#include <com/sun/star/document/UndoContextNotClosedException.idl>
+#include <com/sun/star/document/UndoFailedException.idl>
 #include <com/sun/star/util/InvalidStateException.idl>
 #include <com/sun/star/lang/IllegalArgumentException.idl>
 #include <com/sun/star/lang/WrappedTargetException.idl>
@@ -118,7 +122,7 @@ interface XUndoManager
 
         <p>The redo stack is cleared when a new hidden Undo context is entered.</p>
 
-        @throws ::com::sun::star::util::InvalidStateException
+        @throws EmptyUndoStackException
             if the undo stack is currently empty, in which case it is impossible to push a hidden undo action onto
             it.
 
@@ -126,7 +130,7 @@ interface XUndoManager
         @see leaveUndoContext
     */
     void    enterHiddenUndoContext()
-        raises( ::com::sun::star::util::InvalidStateException );
+        raises( EmptyUndoStackException );
 
     /** leaves the undo context previously opened via <member>enterUndoContext</member> respectively
         <member>enterHiddenUndoContext</member>.
@@ -168,69 +172,86 @@ interface XUndoManager
     /** reverts the most recent action on the document.
 
         <p>Effectively, invoking this method will
-        <ul><li>close any undo contexts which are currently open</p>
-            <li>invoke <member>XUndoAction::undo</member> on the top-most action of the undo stack</li>
+        <ul><li>invoke <member>XUndoAction::undo</member> on the top-most action of the undo stack</li>
             <li>move this undo action from the undo stack to the redo stack</li>
         </ul></p>
 
-        @throws ::com::sun::star::util::InvalidStateException
-            when the undo stack is currently empty
+        @throws EmptyUndoStackException
+            if the undo stack is currently empty
+
+        @throws UndoContextNotClosedException
+            if there currently is an open undo context
 
-        @throws ::com::sun::star::lang::WrappedTargetException
-            if the invocation of <member>XUndoAction::undo</member> raises an exception other than a <member scope="com::sun::star::uno">RuntimeException</member>
+        @throws UndoFailedException
+            if the invocation of <member>XUndoAction::undo</member> raised this exception. In this case, the undo stack
+            of the undo manager will have been cleared.
 
         @see redo
+        @see enterUndoContext
     */
     void    undo()
-            raises( ::com::sun::star::util::InvalidStateException,
-                    ::com::sun::star::lang::WrappedTargetException );
+            raises( ::com::sun::star::document::EmptyUndoStackException,
+                    ::com::sun::star::document::UndoContextNotClosedException,
+                    ::com::sun::star::document::UndoFailedException );
 
     /** replays the action on the document which has most recently been undone
 
         <p>Effectively, invoking this method will
-        <ul><li>close any undo contexts which are currently open</p>
-            <li>invoke <member>XUndoAction::redo</member> on the top-most action of the redo stack</li>
+        <ul><li>invoke <member>XUndoAction::redo</member> on the top-most action of the redo stack</li>
             <li>move this action from the redo stack to the undo stack</li>
         </ul></p>
 
-        @throws ::com::sun::star::util::InvalidStateException
+        @throws EmptyUndoStackException
             when the Redo stack is currently empty
 
-        @throws ::com::sun::star::lang::WrappedTargetException
-            if the invocation of <member>XUndoAction::redo</member> raises an exception other than a <member scope="com::sun::star::uno">RuntimeException</member>
+        @throws UndoContextNotClosedException
+            if there currently is an open undo context
+
+        @throws UndoFailedException
+            if the invocation of <member>XUndoAction::redo</member> raised this exception. In this case, the redo stack
+            of the undo manager will have been cleared.
 
         @see undo
     */
     void    redo()
-            raises( ::com::sun::star::util::InvalidStateException,
-                    ::com::sun::star::lang::WrappedTargetException );
+            raises( ::com::sun::star::document::EmptyUndoStackException,
+                    ::com::sun::star::document::UndoContextNotClosedException,
+                    ::com::sun::star::document::UndoFailedException );
 
-    /** determines whether the undo stack is currently non-empty.
+    /** determines whether <member>undo</member> can reasonably be expected to succeed.
+
+        @return
+            <FALSE/> if and only if the undo stack is currently, empty, or there is an open and not-yet-closed
+            undo context.
     */
     boolean isUndoPossible();
 
-    /** determines whether the Redo stack is currently non-empty.
+    /** determines whether <member>redo</member> can reasonably be expected to succeed.
+
+        @return
+            <FALSE/> if and only if the redo stack is currently, empty, or there is an open and not-yet-closed
+            undo context.
     */
     boolean isRedoPossible();
 
     /** returns the title of the top-most action on the undo stack
 
-        @throws ::com::sun::star::util::InvalidStateException
+        @throws EmptyUndoStackException
             when the undo stack is currently empty
 
         @see XUndoAction::Title
     */
     string  getCurrentUndoActionTitle()
-            raises( ::com::sun::star::util::InvalidStateException );
+            raises( ::com::sun::star::document::EmptyUndoStackException );
 
     /** returns the title of the top-most action on the Redo stack
 
-        @throws ::com::sun::star::util::InvalidStateException
+        @throws EmptyUndoStackException
             when the Redo stack is currently empty
         @see XUndoAction::Title
     */
     string  getCurrentRedoActionTitle()
-            raises( ::com::sun::star::util::InvalidStateException );
+            raises( ::com::sun::star::document::EmptyUndoStackException );
 
     /** returns the titles of all actions currently on the undo stack, from top to bottom
         @see XUndoAction::Title
@@ -249,15 +270,38 @@ interface XUndoManager
 
         <p>All actions will be removed from both the Undo and the Redo stack. Actions which implement the
         <type scope="com::sun::star::lang">XComponent</type> interface will be disposed.</p>
+
+        @throws UndoContextNotClosedException
+            if the method is invoked while an undo context is still open
     */
-    void    clear();
+    void    clear()
+            raises( ::com::sun::star::document::UndoContextNotClosedException );
 
     /** clears the redo stack.
 
         <p>All actions will be removed from the Redo stack. Actions which implement the <type scope="com::sun::star::lang">XComponent</type>
         interface will be disposed.</p>
+
+        @throws UndoContextNotClosedException
+            if the method is invoked while an undo context is still open
     */
-    void    clearRedo();
+    void    clearRedo()
+            raises( ::com::sun::star::document::UndoContextNotClosedException );
+
+    /** resets the Undo manager
+
+        <p>In particular, this method will
+            <ul><li>close all open undo contexts</li>
+                <li>clear the undo stack</li>
+                <li>clear the redo stack</li>
+            </ul></p>
+
+        <p>Note that possible listeners will not get notifications for the single parts of the reset, i.e. there
+        will be no single <member>XUndoManagerListener::allActionsCleared</member>,
+        <member>XUndoManagerListener::leftContext</member>, etc., notifications. Instead, listeners will be
+        notified of the reset by calling their <member>XUndoManagerListener::resetAll</member> method.</p>
+    */
+    void    reset();
 
     /** locks</a> the Undo manager
 
@@ -272,14 +316,14 @@ interface XUndoManager
 
     /** unlocks the Undo manager
 
-        @throws ::com::sun::star::util::InvalidStateException
+        @throws ::com::sun::star::document::NotLockedException
             if the Undo manager is not currently locked.
 
         @see lock
         @see isLocked
     */
     void    unlock()
-        raises  (   ::com::sun::star::util::InvalidStateException
+        raises  (   ::com::sun::star::document::NotLockedException
                 );
 
     /** determines whether the Undo manager is currently locked.
diff --git a/offapi/com/sun/star/document/XUndoManagerListener.idl b/offapi/com/sun/star/document/XUndoManagerListener.idl
index e08846035087..64c8c49db501 100755
--- a/offapi/com/sun/star/document/XUndoManagerListener.idl
+++ b/offapi/com/sun/star/document/XUndoManagerListener.idl
@@ -76,6 +76,10 @@ interface XUndoManagerListener : ::com::sun::star::lang::XEventListener
     */
     void    redoActionsCleared( [in] ::com::sun::star::lang::EventObject i_event );
 
+    /** called when the complete undo manager has been reset
+    */
+    void    resetAll( [in] ::com::sun::star::lang::EventObject i_event );
+
     /** is called when a new Undo context has been entered.
 
         <p><member>UndoManagerEvent::UndoActionTitle</member> carries the title of the Undo context, and
diff --git a/offapi/com/sun/star/document/makefile.mk b/offapi/com/sun/star/document/makefile.mk
index 3a426123f1bf..ebef44407a94 100644
--- a/offapi/com/sun/star/document/makefile.mk
+++ b/offapi/com/sun/star/document/makefile.mk
@@ -119,7 +119,11 @@ IDLFILES=\
     XUndoManager.idl \
     XUndoManagerListener.idl \
     XUndoManagerSupplier.idl \
-    UndoManagerEvent.idl
+    UndoManagerEvent.idl \
+    NotLockedException.idl \
+    EmptyUndoStackException.idl \
+    UndoContextNotClosedException.idl \
+    UndoFailedException.idl \
 
 
 # ------------------------------------------------------------------