framework/inc/threadhelp/itransactionmanager.h

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