framework/inc/threadhelp/transactionguard.hxx

   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: transactionguard.hxx,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_TRANSACTIONGUARD_HXX_
  32 #define __FRAMEWORK_THREADHELP_TRANSACTIONGUARD_HXX_
  33
  34 //_________________________________________________________________________________________________________________
  35 //      my own includes
  36 //_________________________________________________________________________________________________________________
  37
  38 #include <threadhelp/inoncopyable.h>
  39 #include <threadhelp/itransactionmanager.h>
  40
  41 //_________________________________________________________________________________________________________________
  42 //      interface includes
  43 //_________________________________________________________________________________________________________________
  44
  45 //_________________________________________________________________________________________________________________
  46 //      other includes
  47 //_________________________________________________________________________________________________________________
  48
  49 //_________________________________________________________________________________________________________________
  50 //      namespace
  51 //_________________________________________________________________________________________________________________
  52
  53 namespace framework{
  54
  55 //_________________________________________________________________________________________________________________
  56 //      const
  57 //_________________________________________________________________________________________________________________
  58
  59 //_________________________________________________________________________________________________________________
  60 //      declarations
  61 //_________________________________________________________________________________________________________________
  62
  63 /*-************************************************************************************************************//**
  64     @short          implement a guard to support non breakable transactions
  65     @descr          If you whish to support non breakable method calls without lockingf any mutex, rw-lock or
  66                     something like that - you should use this guard implementation.
  67                     Initialize it at first in your method and don't release it till end of your function!
  68                     Your "transaction" is registered in ctor and automaticly released in dtor.
  69                     Use set/get of working mode to enable/disable further transactions.
  70                     It's possible too, to enable automaticly throwing of some exceptions for illegal
  71                     transaction requests ... e.g. interface call for already disposed objects.
  72
  73     @attention          To prevent us against wrong using, the default ctor, copy ctor and the =operator are maked private!
  74
  75     @implements         -
  76     @base           INonCopyable
  77
  78     @devstatus      draft
  79 *//*-*************************************************************************************************************/
  80 class TransactionGuard : private INonCopyable
  81 {
  82     //-------------------------------------------------------------------------------------------------------------
  83     //  public methods
  84     //-------------------------------------------------------------------------------------------------------------
  85     public:
  86
  87         /*-****************************************************************************************************//**
  88             @short      ctors
  89             @descr      Use these ctor methods to initialize the guard right.
  90                         Given reference must be valid - otherwise crashes could occure!
  91
  92             @attention  It's not neccessary to lock any mutex here! Because a ctor should not be called
  93                         from different threads at the same time ... this class use no refcount mechanism!
  94
  95             @seealso    -
  96
  97             @param      "rManager"  reference to transaction manager for using to register a request
  98             @param      "eMode"     enable/disable throwing of exceptions for rejected calls
  99             @param      "eReason"   returns reason for rejected calls if "eMode=E_NOEXCEPTIONS"!
 100             @return     -
 101
 102             @onerror    -
 103         *//*-*****************************************************************************************************/
 104         inline TransactionGuard( ITransactionManager& rManager, EExceptionMode eMode, ERejectReason* eReason = NULL )
 105             : m_pManager( &rManager )
 106         {
 107             // If exception mode is set to E_HARDEXCETIONS we don't need a buffer to return reason!
 108             // We handle it private. If a call is rejected, our manager throw some exceptions ... and the reason
 109             // could be ignorable ...
 110             if( eReason == NULL )
 111             {
 112                 ERejectReason eMyReason;
 113                 m_pManager->registerTransaction( eMode, eMyReason );
 114             }
 115             else
 116             {
 117                 m_pManager->registerTransaction( eMode, *eReason );
 118             }
 119         }
 120
 121         /*-************************************************************************************************************//**
 122             @short      dtor
 123             @descr      We must release the transaction manager and can forget his pointer.
 124
 125             @seealso    -
 126
 127             @param      -
 128             @return     -
 129
 130             @onerror    -
 131         *//*-*************************************************************************************************************/
 132         inline ~TransactionGuard()
 133         {
 134             stop();
 135         }
 136
 137         /*-************************************************************************************************************//**
 138             @short      stop current transaction
 139             @descr      We must release the transaction manager and can forget his pointer.
 140
 141             @attention  We don't support any start() method here - because it is not easy to
 142                         detect if a transaction already started or not!
 143                         (combination of EExceptionMode and ERejectReason)
 144
 145             @seealso    -
 146
 147             @param      -
 148             @return     -
 149
 150             @onerror    -
 151         *//*-*************************************************************************************************************/
 152         inline void stop()
 153         {
 154             if( m_pManager != NULL )
 155             {
 156                 m_pManager->unregisterTransaction();
 157                 m_pManager = NULL;
 158             }
 159         }
 160
 161     //-------------------------------------------------------------------------------------------------------------
 162     //  private methods
 163     //-------------------------------------------------------------------------------------------------------------
 164     private:
 165
 166         /*-****************************************************************************************************//**
 167             @short              disable using of these functions!
 168             @descr              It's not allowed to use this methods. Different problem can occure otherwise.
 169                         Thats why we disable it by make it private.
 170
 171             @seealso    other ctor
 172
 173             @param              -
 174             @return             -
 175
 176             @onerror    -
 177         *//*-*****************************************************************************************************/
 178         TransactionGuard();
 179
 180     //-------------------------------------------------------------------------------------------------------------
 181     //  private member
 182     //-------------------------------------------------------------------------------------------------------------
 183     private:
 184
 185         ITransactionManager*   m_pManager   ;   /// pointer to safed transaction manager
 186
 187 };      //  class TransactionGuard
 188
 189 }               //      namespace framework
 190
 191 #endif  //  #ifndef __FRAMEWORK_THREADHELP_TRANSACTIONGUARD_HXX_