1 /************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 28 #ifndef __FRAMEWORK_THREADHELP_ITRANSACTIONMANAGER_H_ 29 #define __FRAMEWORK_THREADHELP_ITRANSACTIONMANAGER_H_ 30 31 //_________________________________________________________________________________________________________________ 32 // includes 33 //_________________________________________________________________________________________________________________ 34 35 #include <general.h> 36 #include <com/sun/star/uno/RuntimeException.hpp> 37 #include <com/sun/star/lang/DisposedException.hpp> 38 39 //_________________________________________________________________________________________________________________ 40 // namespace 41 //_________________________________________________________________________________________________________________ 42 43 namespace framework{ 44 45 //_________________________________________________________________________________________________________________ 46 // declarations 47 //_________________________________________________________________________________________________________________ 48 49 /*-************************************************************************************************************//** 50 @descr Describe different states of a feature of following implementation. 51 During live time of an object different working states occure: 52 initialization - working - closing - closed 53 If you whish to implement thread safe classes you should use these feature to protect 54 your code against calls at wrong time. e.g. you are not full initialized but somewhere 55 call an interface method (initialize phase means startup time from creating object till 56 calling specified first method e.g. XInitialization::initialze()!) then you should refuse 57 this call. The same for closing/disposing the object! 58 *//*-*************************************************************************************************************/ 59 enum EWorkingMode 60 { 61 E_INIT , // We stand in a init method -> some calls are accepted - some one are rejected 62 E_WORK , // Object is ready for working -> all calls are accepted 63 E_BEFORECLOSE, // We stand in a close method -> some calls are accepted - some one are rejected 64 E_CLOSE // Object is dead! -> all calls are rejected! 65 }; 66 67 /*-************************************************************************************************************//** 68 @descr If a request was refused by a transaction manager (internal state different E_WORK ...) 69 user can check the reason by using this enum values. 70 *//*-*************************************************************************************************************/ 71 enum ERejectReason 72 { 73 E_UNINITIALIZED , 74 E_NOREASON , 75 E_INCLOSE , 76 E_CLOSED 77 }; 78 79 /*-************************************************************************************************************//** 80 @descr A transaction object should support throwing exceptions if user used it at wrong working mode. 81 e.g. We can throw a DisposedException if user try to work and our mode is E_CLOSE! 82 But sometimes he dont need this feature - will handle it by himself. 83 Then we must differ between some exception-modi: 84 E_NOEXCEPTIONS We never throw any exceptions! User handle it private and looks for ERejectReason. 85 E_HARDEXCEPTIONS We throw exceptions for all working modes different from E_WORK! 86 E_SOFTEXCEPTIONS We throw exceptions for all working modes different from E_WORK AND E_INCLOSE! 87 This mode is useful for impl-methods which should be callable from dispose() method! 88 89 e.g. void dispose() 90 { 91 m_aTransactionManager.setWorkingMode( E_BEFORECLOSE ); 92 ... 93 impl_setA( 0 ); 94 ... 95 m_aTransactionManager.setWorkingMode( E_CLOSE ); 96 } 97 98 void impl_setA( int nA ) 99 { 100 ERejectReason EReason; 101 TransactionGuard aTransactionGuard( m_aTransactionManager, E_SOFTEXCEPTIONS, eReason ); 102 103 m_nA = nA; 104 } 105 106 Normaly (if E_HARDEXCEPTIONS was used!) creation of guard 107 will throw an exception ... but using of E_SOFTEXCEPTIONS suppress it 108 and member "A" can be set. 109 *//*-*************************************************************************************************************/ 110 enum EExceptionMode 111 { 112 E_NOEXCEPTIONS , 113 E_HARDEXCEPTIONS, 114 E_SOFTEXCEPTIONS 115 }; 116 117 /*-************************************************************************************************************//** 118 @descr How can you use the transaction manager? 119 Use it in combination with an TransactionGuard, which register your transaction in ctor 120 and release in dtor automaticly! Follow interface class can be used to make using 121 of different manager implmentations possible by using same guard. 122 *//*-*************************************************************************************************************/ 123 class ITransactionManager 124 { 125 //------------------------------------------------------------------------------------------------------------- 126 // public methods 127 //------------------------------------------------------------------------------------------------------------- 128 public: 129 130 /*-****************************************************************************************************//** 131 @descr These functions must be supported by a derived class! 132 getWorkingMode() -return current set working mode 133 setWorkingMode() -change working mode 134 (This will block till all current transactions are finished!) 135 isCallRejected() -test method to check if a call will be rejected by wrong working mode or not 136 registerTransaction() -start new transaction (increase internal transaction count) 137 unregisterTransaction() -finish transaction (decrease internal transaction count) 138 *//*-*****************************************************************************************************/ 139 virtual EWorkingMode getWorkingMode ( ) const = 0; 140 virtual void setWorkingMode ( EWorkingMode eMode ) = 0; 141 virtual sal_Bool isCallRejected ( ERejectReason& eReason ) const = 0; 142 virtual void registerTransaction ( EExceptionMode eMode , ERejectReason& eReason ) throw( css::uno::RuntimeException, css::lang::DisposedException ) = 0; 143 virtual void unregisterTransaction ( ) throw( css::uno::RuntimeException, css::lang::DisposedException ) = 0; 144 145 }; // class ITransactionManager 146 147 } // namespace framework 148 149 #endif // #ifndef __FRAMEWORK_THREADHELP_ITRANSACTIONMANAGER_H_ 150