framework/inc/threadhelp/itransactionmanager.h

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