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