xmltooling  3.2.0
xmltooling::ReloadableXMLFile Class Reference

Base class for file-based XML configuration. More...

#include <xmltooling/util/ReloadableXMLFile.h>

Inheritance diagram for xmltooling::ReloadableXMLFile:
Collaboration diagram for xmltooling::ReloadableXMLFile:

Public Member Functions

Lockablelock ()
 Lock the associated object for exclusive access. More...
 
void unlock ()
 Unlock the associated object from exclusive access.
 

Protected Member Functions

 ReloadableXMLFile (const xercesc::DOMElement *e, logging::Category &log, bool startReloadThread=true, bool deprecationSupport=true)
 Constructor taking a DOM element supporting the following content: More...
 
virtual std::pair< bool, xercesc::DOMElement * > background_load ()
 Loads configuration material. More...
 
virtual std::pair< bool, xercesc::DOMElement * > load (bool backup, std::string backingFile)
 Basic load/parse of configuration material. More...
 
virtual LockablegetBackupLock ()
 Accesses a lock interface protecting use of backup file associated with the object. More...
 
std::pair< bool, xercesc::DOMElement * > load ()
 Basic load/parse of configuration material. More...
 
void preserveCacheTag ()
 Preserves the last remote resource caching identifier in a backup file for use on the next restart.
 
void startup ()
 Starts up reload thread, can be automatically called by constructor, or manually invoked by subclass.
 
void shutdown ()
 Shuts down reload thread, should be called from subclass destructor.
 

Protected Attributes

const xercesc::DOMElement * m_root
 Root of the original DOM element passed into constructor. More...
 
bool m_local
 Indicates whether resources is local or remote. More...
 
bool m_validate
 Use a validating parser when parsing XML. More...
 
std::string m_source
 Resource location, may be a local path or a URI. More...
 
std::string m_backing
 Path to backup copy for remote resource. More...
 
time_t m_filestamp
 Last modification of local resource. More...
 
long m_reloadInterval
 Time in seconds to wait before trying for new copy of remote resource. More...
 
std::string m_cacheTag
 Caching tag associated with remote resource. More...
 
boost::scoped_ptr< RWLockm_lock
 Shared lock for guarding reloads. More...
 
logging::Category & m_log
 Logging object. More...
 
std::string m_id
 Plugin identifier. More...
 
bool m_loaded
 Indicates whether a usable version of the resource is in place. More...
 
boost::scoped_ptr< CredentialResolverm_credResolver
 CredentialResolver for signature verification. More...
 
boost::scoped_ptr< SignatureTrustEnginem_trust
 TrustEngine for signature verification. More...
 
std::string m_signerName
 Name of signer for signature verification. More...
 

Detailed Description

Base class for file-based XML configuration.

Constructor & Destructor Documentation

◆ ReloadableXMLFile()

xmltooling::ReloadableXMLFile::ReloadableXMLFile ( const xercesc::DOMElement *  e,
logging::Category &  log,
bool  startReloadThread = true,
bool  deprecationSupport = true 
)
protected

Constructor taking a DOM element supporting the following content:

path
identifies a local file
url
identifies a remote resource
validate
use a validating parser
reloadChanges
enables monitoring of local file for changes
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
Parameters
eDOM to supply configuration
loglogging object to use
startReloadThreadtrue iff refresh thread for resources should be started by constructor
deprecationSupporttrue iff deprecated options and settings should be accepted

Member Function Documentation

◆ background_load()

virtual std::pair<bool,xercesc::DOMElement*> xmltooling::ReloadableXMLFile::background_load ( )
protectedvirtual

Loads configuration material.

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.

Returns
a pair consisting of a flag indicating whether to take ownership of the document, and the root element of the tree to load

◆ getBackupLock()

virtual Lockable* xmltooling::ReloadableXMLFile::getBackupLock ( )
protectedvirtual

Accesses a lock interface protecting use of backup file associated with the object.

The lock is NOT acquired automatically.

Returns
pointer to a lock interface, or nullptr if unnecessary

◆ load() [1/2]

virtual std::pair<bool, xercesc::DOMElement*> xmltooling::ReloadableXMLFile::load ( bool  backup,
std::string  backingFile 
)
protectedvirtual

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.

Anyone calling this code needs to take ownership of the job of creating the backup (if the input is well formed). As an assist, providing a unique file name as the second parameter causes the input source to be copied to this file. Thus backup can be done without locking and the job of creating the backup consists of doing a rename (under the lock).

Parameters
backuptrue iff the backup source should be loaded
backingFileFilename to copy the input to
Returns
a pair consisting of a flag indicating whether to take ownership of the document, and the root element of the tree to load

◆ load() [2/2]

std::pair<bool,xercesc::DOMElement*> xmltooling::ReloadableXMLFile::load ( )
protected

Basic load/parse of configuration material.

The base version erforms basic parsing duties and returns the result. Subclasses should override the new background_load() method and perform their own locking in conjunction with calling this method.

Returns
a pair consisting of a flag indicating whether to take ownership of the document, and the root element of the tree to load

◆ lock()

Lockable* xmltooling::ReloadableXMLFile::lock ( )
virtual

Lock the associated object for exclusive access.

Returns
a pointer to the object being locked

Implements xmltooling::Lockable.

Member Data Documentation

◆ m_backing

std::string xmltooling::ReloadableXMLFile::m_backing
protected

Path to backup copy for remote resource.

◆ m_cacheTag

std::string xmltooling::ReloadableXMLFile::m_cacheTag
protected

Caching tag associated with remote resource.

◆ m_credResolver

boost::scoped_ptr<CredentialResolver> xmltooling::ReloadableXMLFile::m_credResolver
protected

CredentialResolver for signature verification.

◆ m_filestamp

time_t xmltooling::ReloadableXMLFile::m_filestamp
protected

Last modification of local resource.

◆ m_id

std::string xmltooling::ReloadableXMLFile::m_id
protected

Plugin identifier.

◆ m_loaded

bool xmltooling::ReloadableXMLFile::m_loaded
protected

Indicates whether a usable version of the resource is in place.

◆ m_local

bool xmltooling::ReloadableXMLFile::m_local
protected

Indicates whether resources is local or remote.

◆ m_lock

boost::scoped_ptr<RWLock> xmltooling::ReloadableXMLFile::m_lock
protected

Shared lock for guarding reloads.

◆ m_log

logging::Category& xmltooling::ReloadableXMLFile::m_log
protected

Logging object.

◆ m_reloadInterval

long xmltooling::ReloadableXMLFile::m_reloadInterval
protected

Time in seconds to wait before trying for new copy of remote resource.

◆ m_root

const xercesc::DOMElement* xmltooling::ReloadableXMLFile::m_root
protected

Root of the original DOM element passed into constructor.

◆ m_signerName

std::string xmltooling::ReloadableXMLFile::m_signerName
protected

Name of signer for signature verification.

◆ m_source

std::string xmltooling::ReloadableXMLFile::m_source
protected

Resource location, may be a local path or a URI.

◆ m_trust

boost::scoped_ptr<SignatureTrustEngine> xmltooling::ReloadableXMLFile::m_trust
protected

TrustEngine for signature verification.

◆ m_validate

bool xmltooling::ReloadableXMLFile::m_validate
protected

Use a validating parser when parsing XML.


The documentation for this class was generated from the following file: