2 * Copyright 2001-2010 Internet2
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file xmltooling/util/ReloadableXMLFile.h
20 * Base class for file-based XML configuration.
23 #ifndef __xmltooling_reloadable_h__
24 #define __xmltooling_reloadable_h__
26 #include <xmltooling/logging.h>
27 #include <xmltooling/Lockable.h>
31 #include <xercesc/dom/DOM.hpp>
33 namespace xmltooling {
35 class XMLTOOL_API CondWait;
36 class XMLTOOL_API RWLock;
37 class XMLTOOL_API Thread;
40 * Base class for file-based XML configuration.
42 class XMLTOOL_API ReloadableXMLFile : protected virtual Lockable
44 MAKE_NONCOPYABLE(ReloadableXMLFile);
47 * Constructor taking a DOM element supporting the following content:
50 * <dt>file | filename | path | pathname</dt>
51 * <dd>identifies a local file</dd>
53 * <dd>identifies a remote resource</dd>
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>
63 * <dd>identifies the plugin instance for logging purposes</dd>
66 * @param e DOM to supply configuration
67 * @param log logging object to use
69 ReloadableXMLFile(const xercesc::DOMElement* e, logging::Category& log);
71 virtual ~ReloadableXMLFile();
74 * Loads configuration material.
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.
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.
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
87 virtual std::pair<bool,xercesc::DOMElement*> background_load();
90 * Basic load/parse of configuration material.
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.
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.
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
102 virtual std::pair<bool,xercesc::DOMElement*> load();
105 * Accesses a lock interface protecting use of backup file associated with the
108 * <p>The lock is <strong>NOT</strong> acquired automatically.
110 * @return pointer to a lock interface, or NULL if unnecessary
112 virtual Lockable* getBackupLock();
114 /** Root of the original DOM element passed into constructor. */
115 const xercesc::DOMElement* m_root;
117 /** Indicates whether resources is local or remote. */
120 /** Use a validating parser when parsing XML. */
123 /** Resource location, may be a local path or a URI. */
124 std::string m_source;
126 /** Path to backup copy for remote resource. */
127 std::string m_backing;
130 * Before load, indicates whether the backup is handled by the base class,
131 * after load, will be true iff it started false and a backup needs to be done.
133 bool m_backupIndicator;
135 /** Last modification of local resource. */
138 /** Time in seconds to wait before trying for new copy of remote resource. */
139 time_t m_reloadInterval;
141 /** Caching tag associated with remote resource. */
142 std::string m_cacheTag;
144 /** Shared lock for guarding reloads. */
147 /** Logging object. */
148 logging::Category& m_log;
150 /** Plugin identifier. */
158 std::pair<bool,xercesc::DOMElement*> load(bool backup);
160 // Used to manage background reload/refresh.
162 CondWait* m_reload_wait;
163 Thread* m_reload_thread;
164 static void* reload_fn(void*);
169 #endif /* __xmltooling_reloadable_h__ */