xmltooling/util/ReloadableXMLFile.h

   1 /*
   2  *  Copyright 2001-2010 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file xmltooling/util/ReloadableXMLFile.h
  19  *
  20  * Base class for file-based XML configuration.
  21  */
  22
  23 #ifndef __xmltooling_reloadable_h__
  24 #define __xmltooling_reloadable_h__
  25
  26 #include <xmltooling/logging.h>
  27 #include <xmltooling/Lockable.h>
  28
  29 #include <ctime>
  30 #include <string>
  31 #include <xercesc/dom/DOM.hpp>
  32
  33 namespace xmltooling {
  34
  35     class XMLTOOL_API CondWait;
  36     class XMLTOOL_API RWLock;
  37     class XMLTOOL_API Thread;
  38
  39     /**
  40      * Base class for file-based XML configuration.
  41      */
  42     class XMLTOOL_API ReloadableXMLFile : protected virtual Lockable
  43     {
  44     MAKE_NONCOPYABLE(ReloadableXMLFile);
  45     protected:
  46         /**
  47          * Constructor taking a DOM element supporting the following content:
  48          *
  49          * <dl>
  50          *  <dt>file | filename | path | pathname</dt>
  51          *  <dd>identifies a local file</dd>
  52          *  <dt>uri | url</dt>
  53          *  <dd>identifies a remote resource</dd>
  54          *  <dt>validate</dt>
  55          *  <dd>use a validating parser</dd>
  56          *  <dt>reloadChanges</dt>
  57          *  <dd>enables monitoring of local file for changes</dd>
  58          *  <dt>reloadInterval</dt>
  59          *  <dd>enables periodic refresh of remote file</dd>
  60          *  <dt>backingFilePath</dt>
  61          *  <dd>location for backup of remote resource</dd>
  62          *  <dt>id</dt>
  63          *  <dd>identifies the plugin instance for logging purposes</dd>
  64          * </dl>
  65          *
  66          * @param e     DOM to supply configuration
  67          * @param log   logging object to use
  68          */
  69         ReloadableXMLFile(const xercesc::DOMElement* e, logging::Category& log);
  70
  71         virtual ~ReloadableXMLFile();
  72
  73         /**
  74          * Loads configuration material.
  75          *
  76          * <p>This method is called to load configuration material
  77          * initially and any time a change is detected. The base version
  78          * performs basic parsing duties and returns the result.
  79          *
  80          * <p>This method is not called with the object locked, so actual
  81          * modification of implementation state requires explicit locking within
  82          * the method override.
  83          *
  84          * @return a pair consisting of a flag indicating whether to take ownership of
  85          *      the document, and the root element of the tree to load
  86          */
  87         virtual std::pair<bool,xercesc::DOMElement*> background_load();
  88
  89         /**
  90          * Basic load/parse of configuration material.
  91          *
  92          * <p>The base version performs basic parsing duties and returns the result.
  93          * Subclasses should override the new background_load() method and perform
  94          * their own locking in conjunction with use of this method.
  95          *
  96          * <p>Subclasses that continue to override this method will function, but
  97          * a write lock will be acquired and held for the entire operation.
  98          *
  99          * @return a pair consisting of a flag indicating whether to take ownership of
 100          *      the document, and the root element of the tree to load
 101          */
 102         virtual std::pair<bool,xercesc::DOMElement*> load();
 103
 104         /**
 105          * Accesses a lock interface protecting use of backup file associated with the
 106          * object.
 107          *
 108          * <p>The lock is <strong>NOT</strong> acquired automatically.
 109          *
 110          * @return  pointer to a lock interface, or nullptr if unnecessary
 111          */
 112         virtual Lockable* getBackupLock();
 113
 114         /**
 115          * Shuts down reload thread, should be called from subclass destructor.
 116          */
 117         void shutdown();
 118
 119         /** Root of the original DOM element passed into constructor. */
 120         const xercesc::DOMElement* m_root;
 121
 122         /** Indicates whether resources is local or remote. */
 123         bool m_local;
 124
 125         /** Use a validating parser when parsing XML. */
 126         bool m_validate;
 127
 128         /** Resource location, may be a local path or a URI. */
 129         std::string m_source;
 130
 131         /** Path to backup copy for remote resource. */
 132         std::string m_backing;
 133
 134         /**
 135          * Before load, indicates whether the backup is handled by the base class,
 136          * after load, will be true iff it started false and a backup needs to be done.
 137          */
 138         bool m_backupIndicator;
 139
 140         /** Last modification of local resource. */
 141         time_t m_filestamp;
 142
 143         /** Time in seconds to wait before trying for new copy of remote resource. */
 144         time_t m_reloadInterval;
 145
 146         /** Caching tag associated with remote resource. */
 147         std::string m_cacheTag;
 148
 149         /** Shared lock for guarding reloads. */
 150         RWLock* m_lock;
 151
 152         /** Logging object. */
 153         logging::Category& m_log;
 154
 155         /** Plugin identifier. */
 156         std::string m_id;
 157
 158     public:
 159         Lockable* lock();
 160         void unlock();
 161
 162     private:
 163         std::pair<bool,xercesc::DOMElement*> load(bool backup);
 164
 165         // Used to manage background reload/refresh.
 166         bool m_shutdown;
 167         CondWait* m_reload_wait;
 168         Thread* m_reload_thread;
 169         static void* reload_fn(void*);
 170     };
 171
 172 };
 173
 174 #endif /* __xmltooling_reloadable_h__ */