svtools/inc/templatefoldercache.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: templatefoldercache.hxx,v $
  10  * $Revision: 1.5 $
  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 SFX2_TEMPLATEFOLDERCACHE_HXX
  32 #define SFX2_TEMPLATEFOLDERCACHE_HXX
  33
  34 #include "svtools/svtdllapi.h"
  35 #include <sal/types.h>
  36
  37 //.........................................................................
  38 namespace svt
  39 {
  40 //.........................................................................
  41
  42     //=====================================================================
  43     //= TemplateFolderCache
  44     //=====================================================================
  45     class TemplateFolderCacheImpl;
  46     /** allows to cache the state of the template directories of OOo
  47         <p>Usually, this class is used together with an instance of a the
  48         <service scope="com.sun.star.frame">DocumentTemplates</service> service. It allows to scan the template folders
  49         of the Office, and updates the configuration so that it reflects the most recent state of the folders.<br/>
  50         As this is an expensive, the TemplateFolderCache has been introduced. It caches the state of the template
  51         folders, and allows to determine if the DocumentTemplates service needs to be invoked to do the (much more expensive)
  52         update.</p>
  53     @example C++
  54     <listing>
  55         TemplateFolderCache aTemplateFolders;
  56         if ( aTemplateFolders.needsUpdate() )
  57         {
  58             // store the current state
  59             aCache.storeState();
  60
  61             // create the DocumentTemplates instance
  62             Reference< XDocumentTemplates > xTemplates = ...;
  63
  64             // update the templates configuration
  65             xTemplates->update();
  66         }
  67
  68         // do anything which relies on a up-to-date template configuration
  69     </listing>
  70     */
  71     class SVT_DLLPUBLIC TemplateFolderCache
  72     {
  73     private:
  74         TemplateFolderCacheImpl*                m_pImpl;
  75
  76     public:
  77         /** ctor.
  78         @param _bAutoStoreState
  79             Set this to <TRUE/> if you want the instance to automatically store the state of the template folders upon
  80             destruction.<br/>
  81             If set to <FALSE/>, you would epplicitly need to call <method>storeState</method> to do this.<br/>
  82             If the current state is not known (e.g. because you did not call needsUpdate, which retrieves it),
  83             it is not retrieved in the dtor, regardless of the <arg>_bAutoStoreState</arg> flag.
  84         */
  85         TemplateFolderCache( sal_Bool _bAutoStoreState = sal_False );
  86         ~TemplateFolderCache( );
  87
  88         /** determines whether or not the template configuration needs to be updated
  89         @param _bForceCheck
  90             set this to <TRUE/> if you want the object to rescan the template folders in every case. The default (<FALSE/>)
  91             means that once the information has been retrieved in a first call, every second call returns the same result
  92             as the first one, even if in the meantime the template folders changed.
  93         @return
  94             <TRUE/> if the template configuration needs to be updated
  95         */
  96         sal_Bool        needsUpdate( sal_Bool _bForceCheck = sal_False );
  97
  98         /** stores the current state of the template folders in the cache
  99         @param _bForceRetrieval
 100             if set to <TRUE/>, the current state of the template folders is retrieved again, even if it is already known.
 101             Usually, you set this to <FALSE/>: After calling <method>needsUpdate</method>, the state is know and does not
 102             need to be read again.
 103         */
 104         void            storeState( sal_Bool _bForceRetrieval = sal_False );
 105     };
 106
 107 //.........................................................................
 108 }       // namespace svt
 109 //.........................................................................
 110
 111 #endif // SFX2_TEMPLATEFOLDERCACHE_HXX