2 * Licensed to the University Corporation for Advanced Internet
3 * Development, Inc. (UCAID) under one or more contributor license
4 * agreements. See the NOTICE file distributed with this work for
5 * additional information regarding copyright ownership.
7 * UCAID licenses this file to you under the Apache License,
8 * Version 2.0 (the "License"); you may not use this file except
9 * in compliance with the License. You may obtain a copy of the
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
17 * either express or implied. See the License for the specific
18 * language governing permissions and limitations under the License.
22 * @file xmltooling/util/ReloadableXMLFile.h
24 * Base class for file-based XML configuration.
27 #ifndef __xmltooling_reloadable_h__
28 #define __xmltooling_reloadable_h__
30 #include <xmltooling/logging.h>
31 #include <xmltooling/Lockable.h>
35 #include <xercesc/dom/DOM.hpp>
37 #ifndef XMLTOOLING_LITE
38 namespace xmlsignature {
39 class XMLTOOL_API Signature;
43 namespace xmltooling {
45 class XMLTOOL_API CondWait;
46 class XMLTOOL_API RWLock;
47 class XMLTOOL_API Thread;
49 #ifndef XMLTOOLING_LITE
50 class XMLTOOL_API CredentialResolver;
51 class XMLTOOL_API SignatureTrustEngine;
55 * Base class for file-based XML configuration.
57 class XMLTOOL_API ReloadableXMLFile : protected virtual Lockable
59 MAKE_NONCOPYABLE(ReloadableXMLFile);
62 * Constructor taking a DOM element supporting the following content:
65 * <dt>file | filename | path | pathname</dt>
66 * <dd>identifies a local file</dd>
68 * <dd>identifies a remote resource</dd>
70 * <dd>use a validating parser</dd>
71 * <dt>reloadChanges</dt>
72 * <dd>enables monitoring of local file for changes</dd>
73 * <dt>reloadInterval or maxRefreshDelay</dt>
74 * <dd>enables periodic refresh of remote file</dd>
75 * <dt>backingFilePath</dt>
76 * <dd>location for backup of remote resource</dd>
78 * <dd>identifies the plugin instance for logging purposes</dd>
79 * <dt>certificate</dt>
80 * <dd>requires XML be signed with an enveloped signature verifiable with specified key</dd>
82 * <dd>requires XML be signed with an enveloped signature verifiable with <TrustEngine>
83 * by certificate containing this name</dd>
84 * <dt><CredentialResolver></dt>
85 * <dd>requires XML be signed with an enveloped signature verifiable with specified key</dd>
86 * <dt><TrustEngine></dt>
87 * <dd>requires XML be signed with an enveloped signature verifiable with specified TrustEngine</dd>
90 * @param e DOM to supply configuration
91 * @param log logging object to use
92 * @param startReloadThread true iff refresh thread for resources should be started by constructor
94 ReloadableXMLFile(const xercesc::DOMElement* e, logging::Category& log, bool startReloadThread=true);
96 virtual ~ReloadableXMLFile();
99 * Loads configuration material.
101 * <p>This method is called to load configuration material
102 * initially and any time a change is detected. The base version
103 * performs basic parsing duties and returns the result.
105 * <p>This method is not called with the object locked, so actual
106 * modification of implementation state requires explicit locking within
107 * the method override.
109 * @return a pair consisting of a flag indicating whether to take ownership of
110 * the document, and the root element of the tree to load
112 virtual std::pair<bool,xercesc::DOMElement*> background_load();
116 * Basic load/parse of configuration material.
118 * <p>The base version performs basic parsing duties and returns the result.
119 * Subclasses should override the new background_load() method and perform
120 * their own locking in conjunction with use of this method.
122 * <p>Subclasses that continue to override this method will function, but
123 * a write lock will be acquired and held for the entire operation.
125 * @return a pair consisting of a flag indicating whether to take ownership of
126 * the document, and the root element of the tree to load
128 virtual std::pair<bool,xercesc::DOMElement*> load();
131 * Basic load/parse of configuration material.
133 * <p>The base version performs basic parsing duties and returns the result.
134 * Subclasses should override the new background_load() method and perform
135 * their own locking in conjunction with use of this method.
137 * <p>This version allows subclasses to explicitly control the use of a
138 * backup for remote resources, which allows additional validation to be
139 * performed besides just successful XML parsing.
141 * @param backup true iff the backup source should be loaded
142 * @return a pair consisting of a flag indicating whether to take ownership of
143 * the document, and the root element of the tree to load
145 virtual std::pair<bool,xercesc::DOMElement*> load(bool backup);
148 * Accesses a lock interface protecting use of backup file associated with the
151 * <p>The lock is <strong>NOT</strong> acquired automatically.
153 * @return pointer to a lock interface, or nullptr if unnecessary
155 virtual Lockable* getBackupLock();
158 * Preserves the last remote resource caching identifier in a backup file
159 * for use on the next restart.
161 void preserveCacheTag();
164 * Starts up reload thread, can be automatically called by constructor, or
165 * manually invoked by subclass.
170 * Shuts down reload thread, should be called from subclass destructor.
174 /** Root of the original DOM element passed into constructor. */
175 const xercesc::DOMElement* m_root;
177 /** Indicates whether resources is local or remote. */
180 /** Use a validating parser when parsing XML. */
183 /** Resource location, may be a local path or a URI. */
184 std::string m_source;
186 /** Path to backup copy for remote resource. */
187 std::string m_backing;
189 /** Last modification of local resource. */
192 /** Time in seconds to wait before trying for new copy of remote resource. */
193 time_t m_reloadInterval;
195 /** Caching tag associated with remote resource. */
196 std::string m_cacheTag;
198 /** Shared lock for guarding reloads. */
201 /** Logging object. */
202 logging::Category& m_log;
204 /** Plugin identifier. */
207 /** Indicates whether a usable version of the resource is in place. */
210 #ifndef XMLTOOLING_LITE
211 /** CredentialResolver for signature verification. */
212 CredentialResolver* m_credResolver;
214 /** TrustEngine for signature verification. */
215 SignatureTrustEngine* m_trust;
217 /** Name of signer for signature verification. */
218 std::string m_signerName;
226 #ifndef XMLTOOLING_LITE
227 void validateSignature(xmlsignature::Signature& sigObj) const;
229 // Used to manage background reload/refresh.
231 CondWait* m_reload_wait;
232 Thread* m_reload_thread;
233 static void* reload_fn(void*);
238 #endif /* __xmltooling_reloadable_h__ */