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 occur:
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 automatically! 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