te::common::UserApplicationSettings Class Reference

A singleton for managing application settings applied to a single user. More...

#include <UserApplicationSettings.h>

Inheritance diagram for te::common::UserApplicationSettings:
te::common::ApplicationSettings te::common::Singleton< UserApplicationSettings > te::common::ObjectLevelLockable< ApplicationSettings, ::boost::recursive_mutex, ::boost::lock_guard< ::boost::recursive_mutex >, ::boost::lock_guard< ::boost::recursive_mutex > >

Public Types

typedef ObjectLevelLockingPolicy< ::boost::lock_guard< ::boost::recursive_mutex > > LockRead
 
typedef ObjectLevelLockingPolicy< ::boost::lock_guard< ::boost::recursive_mutex > > LockWrite
 
typedef volatile ApplicationSettings VolatileType
 

Public Member Functions

void changed ()
 This method can be used by clients to inform manually that the internal state has changed. More...
 
const boost::property_tree::ptree & getAllSettings () const
 It return a reading reference to the internal settings. More...
 
boost::property_tree::ptree & getAllSettings ()
 It return a reference to the internal settings. More...
 
std::string getValue (const std::string &key)
 It returns the value for a given key or empty. More...
 
void load (const std::string &fileName)
 It tries to find a default config file based on system macros and default condigurations. More...
 
void setValue (const std::string &key, const std::string &value)
 It stores the value according to the key. More...
 
void update ()
 It updates the application settings. More...
 

Static Public Member Functions

static UserApplicationSettingsgetInstance ()
 It returns a reference to the singleton instance. More...
 

Protected Member Functions

 UserApplicationSettings ()
 It initializes the singleton. More...
 
 ~UserApplicationSettings ()
 Destructor. More...
 

Protected Attributes

bool m_dirty
 A dirty bit to indicate wheter the clients have made changes in the settings since the last update. More...
 
std::string m_file
 The settings file name. More...
 
boost::property_tree::ptree m_settings
 This will keep our settings in memory. More...
 

Friends

class te::common::Singleton< UserApplicationSettings >
 

Detailed Description

A singleton for managing application settings applied to a single user.

This singleton can be used to keep user preferences that customize the application's appearance and behavior for a given user.

It will look for an user configuration file as follows:

  • first, searchs for the user settings file name in the system application settings singleton
  • if not found, use the file name defined by the macro TERRALIB_USER_SETTINGS_FILE
  • then it check for this file in the current application dir under the folder TERRALIB_CONFIG_DIR
  • if not found, it checks for in the user data dir (plataform dependent!)
  • and finally it uses a location defined by an environment variable TERRALIB_DIR_ENVVAR and a sub-dir defined by the macro TERRALIB_CONFIG_DIR

Definition at line 56 of file UserApplicationSettings.h.

Member Typedef Documentation

◆ LockRead

typedef ObjectLevelLockingPolicy<::boost::lock_guard< ::boost::recursive_mutex > > te::common::ObjectLevelLockable< ApplicationSettings , ::boost::recursive_mutex , ::boost::lock_guard< ::boost::recursive_mutex > , ::boost::lock_guard< ::boost::recursive_mutex > >::LockRead
inherited

Definition at line 205 of file ThreadingPolicies.h.

◆ LockWrite

typedef ObjectLevelLockingPolicy<::boost::lock_guard< ::boost::recursive_mutex > > te::common::ObjectLevelLockable< ApplicationSettings , ::boost::recursive_mutex , ::boost::lock_guard< ::boost::recursive_mutex > , ::boost::lock_guard< ::boost::recursive_mutex > >::LockWrite
inherited

Definition at line 206 of file ThreadingPolicies.h.

◆ VolatileType

typedef volatile ApplicationSettings te::common::ObjectLevelLockable< ApplicationSettings , ::boost::recursive_mutex , ::boost::lock_guard< ::boost::recursive_mutex > , ::boost::lock_guard< ::boost::recursive_mutex > >::VolatileType
inherited

Definition at line 204 of file ThreadingPolicies.h.

Constructor & Destructor Documentation

◆ UserApplicationSettings()

te::common::UserApplicationSettings::UserApplicationSettings ( )
protected

It initializes the singleton.

◆ ~UserApplicationSettings()

te::common::UserApplicationSettings::~UserApplicationSettings ( )
protected

Destructor.

Member Function Documentation

◆ changed()

void te::common::ApplicationSettings::changed ( )
inlineinherited

This method can be used by clients to inform manually that the internal state has changed.

This method is useful when accessing the internal settings structure.

Note
Thread-safe depending on ThreadingPolicy.

Definition at line 238 of file ApplicationSettings.h.

References te::common::ApplicationSettings::m_dirty.

◆ getAllSettings() [1/2]

const boost::property_tree::ptree & te::common::ApplicationSettings::getAllSettings ( ) const
inlineinherited

It return a reading reference to the internal settings.

Returns
A read reference to the internal settings.
Note
Take care when keeping a reference to this property in a multi-thread environment.

Definition at line 245 of file ApplicationSettings.h.

References te::common::ApplicationSettings::m_settings.

◆ getAllSettings() [2/2]

boost::property_tree::ptree & te::common::ApplicationSettings::getAllSettings ( )
inlineinherited

It return a reference to the internal settings.

Returns
A reference to the internal settings.
Note
Depending on the ThreadingPolicy you can synchronize the read/write from/to the settings. The client of this method will be responsible for informing changes. Release any lock before calling the update method or any other thread-safe method if you are not using a recursive mutex in the threading policy.

Definition at line 250 of file ApplicationSettings.h.

References te::common::ApplicationSettings::m_settings.

◆ getInstance()

UserApplicationSettings & te::common::Singleton< UserApplicationSettings >::getInstance ( )
inlinestaticinherited

It returns a reference to the singleton instance.

Returns
A reference to the singleton instance.

Definition at line 126 of file Singleton.h.

◆ getValue()

std::string te::common::ApplicationSettings::getValue ( const std::string &  key)
inlineinherited

It returns the value for a given key or empty.

Parameters
keyThe key used to identify the searched value.
Returns
The value for a given key or empty.
Note
Thread-safe depending on ThreadingPolicy.

Definition at line 190 of file ApplicationSettings.h.

References te::common::ApplicationSettings::m_settings.

◆ load()

void te::common::UserApplicationSettings::load ( const std::string &  fileName)

It tries to find a default config file based on system macros and default condigurations.

It loads the setting from the given file.

Parameters
fileNameIt must be the full path to the settings file.

◆ setValue()

void te::common::ApplicationSettings::setValue ( const std::string &  key,
const std::string &  value 
)
inlineinherited

It stores the value according to the key.

Parameters
keyThe key used to identify the given value. The key must follow the same rules as XML elements and they can be subclassified using a dot notation: setValue(key.subkey.subsubkey, value).
valueThe value to be stored, any valid string.
Note
If you want to store a binary value you can encode it as an hex-string.
Thread-safe depending on ThreadingPolicy.

Definition at line 182 of file ApplicationSettings.h.

References te::common::ApplicationSettings::m_dirty, and te::common::ApplicationSettings::m_settings.

◆ update()

void te::common::ApplicationSettings::update ( )
inlineinherited

It updates the application settings.

Note
This function is called automatically from ApplicationSettings's destructor.
If application settings is empty it discards the config file.
Thread-safe depending on ThreadingPolicy.

Definition at line 216 of file ApplicationSettings.h.

References te::common::ApplicationSettings::m_dirty, te::common::ApplicationSettings::m_file, te::common::ApplicationSettings::m_settings, and te::core::FileSystem::remove().

Referenced by te::common::ApplicationSettings::~ApplicationSettings().

Friends And Related Function Documentation

◆ te::common::Singleton< UserApplicationSettings >

Definition at line 60 of file UserApplicationSettings.h.

Member Data Documentation

◆ m_dirty

bool te::common::ApplicationSettings::m_dirty
protectedinherited

A dirty bit to indicate wheter the clients have made changes in the settings since the last update.

Definition at line 168 of file ApplicationSettings.h.

Referenced by te::common::ApplicationSettings::changed(), te::common::ApplicationSettings::load(), te::common::ApplicationSettings::setValue(), and te::common::ApplicationSettings::update().

◆ m_file

std::string te::common::ApplicationSettings::m_file
protectedinherited

The settings file name.

Definition at line 167 of file ApplicationSettings.h.

Referenced by te::common::ApplicationSettings::load(), and te::common::ApplicationSettings::update().

◆ m_settings

boost::property_tree::ptree te::common::ApplicationSettings::m_settings
protectedinherited

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