xmltooling 1.5.6

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
xmltooling::ReloadableXMLFile Class Reference

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

`#include <xmltooling/util/ReloadableXMLFile.h>`

Inheritance diagram for xmltooling::ReloadableXMLFile:

## Public Member Functions
Lockable * | lock ()
| 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)
| 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 ()
virtual std::pair< bool, xercesc::DOMElement * > | load (bool backup)
| Basic load/parse of configuration material. More...
virtual Lockable * | getBackupLock ()
| Accesses a lock interface protecting use of backup file associated with the object. 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...
time_t | 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...
RWLock * | m_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...
CredentialResolver * | m_credResolver
| CredentialResolver for signature verification. More...
SignatureTrustEngine * | m_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

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

Constructor taking a DOM element supporting the following content:

file | filename | path | pathname
  identifies a local file
uri | 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

  e | DOM to supply configuration
  log | logging object to use
  startReloadThread | true iff refresh thread for resources should be started by constructor

## Member Function Documentation

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

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

virtual Lockable* xmltooling::ReloadableXMLFile::getBackupLock | ( |  | ) |
| protected virtual

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

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

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.

Returns
  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<bool,xercesc::DOMElement*> xmltooling::ReloadableXMLFile::load | ( | bool | backup | ) |
| protected virtual

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.

Parameters

  backup | true iff the backup source should be loaded

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

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

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

Path to backup copy for remote resource.

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

Caching tag associated with remote resource.

CredentialResolver* xmltooling::ReloadableXMLFile::m_credResolver
| protected

CredentialResolver for signature verification.

time_t xmltooling::ReloadableXMLFile::m_filestamp
| protected

Last modification of local resource.

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

Plugin identifier.

bool xmltooling::ReloadableXMLFile::m_loaded
| protected

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

bool xmltooling::ReloadableXMLFile::m_local
| protected

Indicates whether resources is local or remote.

RWLock* xmltooling::ReloadableXMLFile::m_lock
| protected

Shared lock for guarding reloads.

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

Logging object.

time_t xmltooling::ReloadableXMLFile::m_reloadInterval
| protected

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

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

Root of the original DOM element passed into constructor.

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

Name of signer for signature verification.

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

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

SignatureTrustEngine* xmltooling::ReloadableXMLFile::m_trust
| protected

TrustEngine for signature verification.

bool xmltooling::ReloadableXMLFile::m_validate
| protected

Use a validating parser when parsing XML.

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

- xmltooling/util/ReloadableXMLFile.h