X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=xmltooling%2Futil%2FReloadableXMLFile.h;h=d7cf55eb3cc2a3190a8e4a9d08862f269fa2b9a6;hb=81b488b2790e7bdeb2f43560b1d4a7d22c3dfdf5;hp=d8dda9e5a2735cca86412806641fa1ebef5a07a8;hpb=c9a063e554871e212edc46a1fd9ae865cbc9da9e;p=shibboleth%2Fcpp-xmltooling.git diff --git a/xmltooling/util/ReloadableXMLFile.h b/xmltooling/util/ReloadableXMLFile.h index d8dda9e..d7cf55e 100644 --- a/xmltooling/util/ReloadableXMLFile.h +++ b/xmltooling/util/ReloadableXMLFile.h @@ -1,17 +1,21 @@ -/* - * Copyright 2001-2009 Internet2 - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at +/** + * Licensed to the University Corporation for Advanced Internet + * Development, Inc. (UCAID) under one or more contributor license + * agreements. See the NOTICE file distributed with this work for + * additional information regarding copyright ownership. + * + * UCAID licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. You may obtain a copy of the + * License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + * either express or implied. See the License for the specific + * language governing permissions and limitations under the License. */ /** @@ -25,21 +29,34 @@ #include #include -#include #include #include #include +#ifndef XMLTOOLING_LITE + namespace xmlsignature { + class XMLTOOL_API Signature; + }; +#endif + namespace xmltooling { + class XMLTOOL_API CondWait; + class XMLTOOL_API RWLock; + class XMLTOOL_API Thread; + +#ifndef XMLTOOLING_LITE + class XMLTOOL_API CredentialResolver; + class XMLTOOL_API SignatureTrustEngine; +#endif + /** * Base class for file-based XML configuration. */ class XMLTOOL_API ReloadableXMLFile : protected virtual Lockable { - MAKE_NONCOPYABLE(ReloadableXMLFile); - + MAKE_NONCOPYABLE(ReloadableXMLFile); protected: /** * Constructor taking a DOM element supporting the following content: @@ -53,20 +70,30 @@ namespace xmltooling { *
use a validating parser
*
reloadChanges
*
enables monitoring of local file for changes
- *
reloadInterval
+ *
reloadInterval or maxRefreshDelay
*
enables periodic refresh of remote file
*
backingFilePath
*
location for backup of remote resource
+ *
id
+ *
identifies the plugin instance for logging purposes
+ *
certificate
+ *
requires XML be signed with an enveloped signature verifiable with specified key
+ *
signerName
+ *
requires XML be signed with an enveloped signature verifiable with <TrustEngine> + * by certificate containing this name
+ *
<CredentialResolver>
+ *
requires XML be signed with an enveloped signature verifiable with specified key
+ *
<TrustEngine>
+ *
requires XML be signed with an enveloped signature verifiable with specified TrustEngine
* * - * @param e DOM to supply configuration - * @param log logging object to use + * @param e DOM to supply configuration + * @param log logging object to use + * @param startReloadThread true iff refresh thread for resources should be started by constructor */ - ReloadableXMLFile(const xercesc::DOMElement* e, logging::Category& log); + ReloadableXMLFile(const xercesc::DOMElement* e, logging::Category& log, bool startReloadThread=true); - virtual ~ReloadableXMLFile() { - delete m_lock; - } + virtual ~ReloadableXMLFile(); /** * Loads configuration material. @@ -74,14 +101,76 @@ namespace xmltooling { *

This method is called to load configuration material * initially and any time a change is detected. The base version * performs basic parsing duties and returns the result. + * + *

This method is not called with the object locked, so actual + * modification of implementation state requires explicit locking within + * the method override. * * @return a pair consisting of a flag indicating whether to take ownership of * the document, and the root element of the tree to load */ - virtual std::pair load() { - return load(false); - } - + virtual std::pair background_load(); + + /** + * @deprecated + * Basic load/parse of configuration material. + * + *

The base version performs basic parsing duties and returns the result. + * Subclasses should override the new background_load() method and perform + * their own locking in conjunction with use of this method. + * + *

Subclasses that continue to override this method will function, but + * a write lock will be acquired and held for the entire operation. + * + * @return a pair consisting of a flag indicating whether to take ownership of + * the document, and the root element of the tree to load + */ + virtual std::pair load(); + + /** + * Basic load/parse of configuration material. + * + *

The base version performs basic parsing duties and returns the result. + * Subclasses should override the new background_load() method and perform + * their own locking in conjunction with use of this method. + * + *

This version allows subclasses to explicitly control the use of a + * backup for remote resources, which allows additional validation to be + * performed besides just successful XML parsing. + * + * @param backup true iff the backup source should be loaded + * @return a pair consisting of a flag indicating whether to take ownership of + * the document, and the root element of the tree to load + */ + virtual std::pair load(bool backup); + + /** + * Accesses a lock interface protecting use of backup file associated with the + * object. + * + *

The lock is NOT acquired automatically. + * + * @return pointer to a lock interface, or nullptr if unnecessary + */ + virtual Lockable* getBackupLock(); + + /** + * Preserves the last remote resource caching identifier in a backup file + * for use on the next restart. + */ + void preserveCacheTag(); + + /** + * Starts up reload thread, can be automatically called by constructor, or + * manually invoked by subclass. + */ + void startup(); + + /** + * Shuts down reload thread, should be called from subclass destructor. + */ + void shutdown(); + /** Root of the original DOM element passed into constructor. */ const xercesc::DOMElement* m_root; @@ -94,31 +183,54 @@ namespace xmltooling { /** Resource location, may be a local path or a URI. */ std::string m_source; - /** Path to backup copy for remote resources. */ + /** Path to backup copy for remote resource. */ std::string m_backing; - - /** Last modification of local resource or reload of remote resource. */ + + /** Last modification of local resource. */ time_t m_filestamp; /** Time in seconds to wait before trying for new copy of remote resource. */ time_t m_reloadInterval; + /** Caching tag associated with remote resource. */ + std::string m_cacheTag; + /** Shared lock for guarding reloads. */ RWLock* m_lock; /** Logging object. */ logging::Category& m_log; + /** Plugin identifier. */ + std::string m_id; + + /** Indicates whether a usable version of the resource is in place. */ + bool m_loaded; + +#ifndef XMLTOOLING_LITE + /** CredentialResolver for signature verification. */ + CredentialResolver* m_credResolver; + + /** TrustEngine for signature verification. */ + SignatureTrustEngine* m_trust; + + /** Name of signer for signature verification. */ + std::string m_signerName; +#endif + public: Lockable* lock(); - - void unlock() { - if (m_lock) - m_lock->unlock(); - } + void unlock(); private: - std::pair load(bool backup); +#ifndef XMLTOOLING_LITE + void validateSignature(xmlsignature::Signature& sigObj) const; +#endif + // Used to manage background reload/refresh. + bool m_shutdown; + CondWait* m_reload_wait; + Thread* m_reload_thread; + static void* reload_fn(void*); }; };