Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members

scim_config_base.h

Go to the documentation of this file.
00001 /** @file scim_config_base.h
00002  *  @brief scim::ConfigBase Interface.
00003  *
00004  *  Provide a unified interface to access the configuration data.
00005  *  All of SCIM objects should use this interface if they have any
00006  *  configuration data.
00007  */
00008 
00009 /*
00010  * Smart Common Input Method
00011  * 
00012  * Copyright (c) 2004 James Su <suzhe@turbolinux.com.cn>
00013  * Copyright (c) 2003 James Su <suzhe@turbolinux.com.cn>
00014  * Copyright (c) 2002 James Su <suzhe@turbolinux.com.cn>
00015  *
00016  *
00017  * This library is free software; you can redistribute it and/or
00018  * modify it under the terms of the GNU Lesser General Public
00019  * License as published by the Free Software Foundation; either
00020  * version 2 of the License, or (at your option) any later version.
00021  *
00022  * This library is distributed in the hope that it will be useful,
00023  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00024  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00025  * GNU Lesser General Public License for more details.
00026  *
00027  * You should have received a copy of the GNU Lesser General Public
00028  * License along with this program; if not, write to the
00029  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
00030  * Boston, MA  02111-1307  USA
00031  *
00032  * $Id: scim_config_base.h,v 1.19 2004/07/02 14:06:38 suzhe Exp $
00033  */
00034 
00035 #ifndef __SCIM_CONFIG_BASE_H
00036 #define __SCIM_CONFIG_BASE_H
00037 
00038 namespace scim {
00039 /**
00040  * @addtogroup Config
00041  * The base classes for config modules
00042  * @{
00043  */
00044 
00045 /**
00046  * @brief An exception class to hold Config related errors.
00047  *
00048  * scim::ConfigBase and its derived classes must throw
00049  * scim::ConfigError object when error.
00050  */
00051 class ConfigError: public Exception
00052 {
00053 public:
00054     ConfigError (const String& what_arg)
00055         : Exception (String("scim::Config: ") + what_arg) { }
00056 };
00057 
00058 class ConfigBase;
00059 /**
00060  * @typedef typedef Pointer <ConfigBase> ConfigPointer;
00061  *
00062  * A smart pointer for scim::ConfigBase and its derived classes.
00063  */
00064 typedef Pointer <ConfigBase> ConfigPointer;
00065 
00066 /**
00067  * @typedef typedef Slot1<void, const ConfigPointer &> ConfigSlotVoid;
00068  *
00069  * The slot type to connect to the coresponding signal.
00070  */
00071 typedef Slot1<void, const ConfigPointer &> ConfigSlotVoid;
00072 
00073 /**
00074  * @typedef typedef Signal1<void, const ConfigPointer &> ConfigSignalVoid;
00075  *
00076  * The signal type to connect with the ConfigSlotVoid slot type.
00077  */
00078 typedef Signal1<void, const ConfigPointer &> ConfigSignalVoid;
00079 
00080 /**
00081  * @brief The interface class to access the configuration data.
00082  *
00083  * This is an interface class to access the configuration data.
00084  * All of the SCIM objects which have configuration data should 
00085  * use this interface to store and load them.
00086  */
00087 class ConfigBase : public ReferencedObject
00088 {
00089     String           m_app_name;
00090     ConfigSignalVoid m_signal_reload;
00091 
00092 public:
00093     /**
00094      * @name Constructor and Destructor.
00095      * @{
00096      */
00097 
00098     /**
00099      * @brief Contrustor
00100      * @param app_name - the name of the running application, default is "scim".
00101      */
00102     ConfigBase (const String& app_name = String ("scim"));
00103 
00104     /**
00105      * @brief Virtual destructor 
00106      * empty but ensures that dtor of all derived classes is virtual
00107      */
00108     virtual ~ConfigBase ();
00109 
00110     /**
00111      * @}
00112      */
00113 
00114     /**
00115      * @name Pure virtual methods which should be implemented in derived classes.
00116      * @{
00117      */
00118 
00119     /**
00120      * @brief Check if this Config object is valid.
00121      * @return true if its valid and ready to work.
00122      */
00123     virtual bool valid () const = 0;
00124 
00125     /**
00126      * @brief Read a string from the given key.
00127      * @param key - the key to be read.
00128      * @param ret - the result will be stored into *ret.
00129      * @return true if the string is read successfully, otherwise return false.
00130      */
00131     virtual bool read (const String& key, String *ret) const = 0;
00132 
00133     /**
00134      * @brief Read an int value from the given key.
00135      * @param key - the key to be read.
00136      * @param ret - the result will be stored into *ret.
00137      * @return true if the value is read successfully, otherwise return false.
00138      */
00139     virtual bool read (const String& key, int *ret) const = 0;
00140 
00141     /**
00142      * @brief Read a double value from the given key.
00143      * @param key - the key to be read.
00144      * @param ret - the result will be stored into *ret.
00145      * @return true if the value is read successfully, otherwise return false.
00146      */
00147     virtual bool read (const String& key, double *ret) const = 0;
00148 
00149     /**
00150      * @brief Read a bool value from the given key.
00151      * @param key - the key to be read.
00152      * @param ret - the result will be stored into *ret.
00153      * @return true if the value is read successfully, otherwise return false.
00154      */
00155     virtual bool read (const String& key, bool *ret) const = 0;
00156 
00157     /**
00158      * @brief Read a string list from the given key.
00159      * @param key - the key to be read.
00160      * @param ret - the result will be stored into *ret.
00161      * @return true if the string list is read successfully, otherwise return false.
00162      */
00163     virtual bool read (const String& key, std::vector <String> *ret) const = 0;
00164 
00165     /**
00166      * @brief Read an int list from the given key.
00167      * @param key - the key to be read.
00168      * @param ret - the result will be stored into *ret.
00169      * @return true if the int list is read successfully, otherwise return false.
00170      */
00171     virtual bool read (const String& key, std::vector <int> *ret) const = 0;
00172 
00173     /**
00174      * @brief Write a string to the given key.
00175      * @param key   - the key to be written.
00176      * @param value - the string to be written to the key.
00177      * @return true if success, otherwise false.
00178      */
00179     virtual bool write (const String& key, const String& value) = 0;
00180 
00181     /**
00182      * @brief Write an int value to the given key.
00183      * @param key   - the key to be written.
00184      * @param value - the int value to be written to the key.
00185      * @return true if success, otherwise false.
00186      */
00187     virtual bool write (const String& key, int value) = 0;
00188 
00189     /**
00190      * @brief Write a double value to the given key.
00191      * @param key   - the key to be written.
00192      * @param value - the double value to be written to the key.
00193      * @return true if success, otherwise false.
00194      */
00195     virtual bool write (const String& key, double value) = 0;
00196 
00197     /**
00198      * @brief Write a bool value to the given key.
00199      * @param key   - the key to be written.
00200      * @param value - the bool value to be written to the key.
00201      * @return true if success, otherwise false.
00202      */
00203     virtual bool write (const String& key, bool value) = 0;
00204 
00205     /**
00206      * @brief Write a string list to the given key.
00207      * @param key   - the key to be written.
00208      * @param value - the string list to be written to the key.
00209      * @return true if success, otherwise false.
00210      */
00211     virtual bool write (const String& key, const std::vector <String>& value) = 0;
00212 
00213     /**
00214      * @brief Write an int list to the given key.
00215      * @param key   - the key to be written.
00216      * @param value - the int list to be written to the key.
00217      * @return true if success, otherwise false.
00218      */
00219     virtual bool write (const String& key, const std::vector <int>& value) = 0;
00220 
00221     /**
00222      * @brief Permanently writes all changes.
00223      * @return true if success.
00224      */
00225     virtual bool flush() = 0;
00226 
00227     /**
00228      * @brief Erase a key and its value
00229      * @param key - the key to be erased.
00230      * @return true if success.
00231      */
00232     virtual bool erase (const String& key) = 0;
00233 
00234     /**
00235      * @brief Reload the configurations from storage.
00236      *
00237      * All modified keys after the last flush maybe lost.
00238      *
00239      * The derived method should call this base method
00240      * after reload the configurations successfully,
00241      * in order to emit the reload signal.
00242      * 
00243      * The derived method should have some machanism to avoid
00244      * reload again if there is no update after
00245      * the previous reload.
00246      *
00247      * @return true if success.
00248      */
00249     virtual bool reload () = 0;
00250 
00251     /**
00252      * @}
00253      */
00254 
00255     /**
00256      * @name Other helper methods.
00257      * @{
00258      */
00259 
00260     /**
00261      * @brief Read a string from the given key with a default fallback value.
00262      *
00263      * If failed to read from the given key, then return the given default value.
00264      *
00265      * @param key    - the key to be read.
00266      * @param defVal - the default value to be return if failed to read.
00267      * @return The result string.
00268      */
00269     String read (const String& key, const String& defVal = String ()) const;
00270 
00271     /**
00272      * @brief Read an int value from the given key with a default fallback value.
00273      *
00274      * If failed to read from the given key, then return the given default value.
00275      *
00276      * @param key    - the key to be read.
00277      * @param defVal - the default value to be return if failed to read.
00278      * @return The result int value.
00279      */
00280     int read (const String& key, int defVal) const;
00281 
00282     /**
00283      * @brief Read a double value from the given key with a default fallback value.
00284      *
00285      * If failed to read from the given key, then return the given default value.
00286      *
00287      * @param key    - the key to be read.
00288      * @param defVal - the default value to be return if failed to read.
00289      * @return The result double value.
00290      */
00291     double read (const String& key, double defVal) const;
00292 
00293     /**
00294      * @brief Read a bool value from the given key with a default fallback value.
00295      *
00296      * If failed to read from the given key, then return the given default value.
00297      *
00298      * @param key    - the key to be read.
00299      * @param defVal - the default value to be return if failed to read.
00300      * @return The result bool value.
00301      */
00302     bool read (const String& key, bool defVal) const;
00303 
00304     /**
00305      * @brief Read a string list from the given key with a default fallback value.
00306      *
00307      * If failed to read from the given key, then return the given default value.
00308      *
00309      * @param key    - the key to be read.
00310      * @param defVal - the default value to be return if failed to read.
00311      * @return The result string list.
00312      */
00313     std::vector <String> read (const String& key, const std::vector <String>& defVal) const;
00314 
00315     /**
00316      * @brief Read an int list from the given key with a default fallback value.
00317      *
00318      * If failed to read from the given key, then return the given default value.
00319      *
00320      * @param key    - the key to be read.
00321      * @param defVal - the default value to be return if failed to read.
00322      * @return The result int list.
00323      */
00324     std::vector <int> read (const String& key, const std::vector <int>& defVal) const;
00325 
00326     /**
00327      * @brief Get the application's name.
00328      * @return the name of the current application.
00329      */
00330     const String& get_app_name() const;
00331 
00332     /**
00333      * @brief Set the name of the current application.
00334      * @param name - the name of the current application.
00335      */
00336     void set_app_name (const String& name);
00337 
00338     /**
00339      * @brief connect the given slot to the reload signal.
00340      * @param slot - the given slot to be connected.
00341      * @return the Connection object, can be used to disconnect this slot.
00342      */
00343     Connection signal_connect_reload (ConfigSlotVoid *slot);
00344 
00345     /** @} */ 
00346 
00347 public:
00348     /**
00349      * @brief Set the default global Config object.
00350      * 
00351      * There is only one global Config object in an application.
00352      * All other objects should use it by default.
00353      *
00354      * @param p_config - a smart pointer to the Config object.
00355      * @return a smart pointer to the old default Config object.
00356      */
00357     static ConfigPointer set (const ConfigPointer &p_config);
00358 
00359     /**
00360      * @brief Get the default global Config object.
00361      * 
00362      * The default global Config object can be set with function ConfigBase::set.
00363      * If there is no default object set, a new object can be created if needed.
00364      *
00365      * @param create_on_demand - if it's true then a new object will be created,
00366      *                           if there is no one available.
00367      * @param default_module   - the Config module should be used to create the 
00368      *                           default Config object. If omitted, then use the
00369      *                           default module defined in global config file.
00370      * @return a smart pointer to the default global Config object.
00371      */
00372     static ConfigPointer get (bool create_on_demand = true,
00373                               const String &default_module = String (""));
00374 };
00375 
00376 /**
00377  * @brief A dummy implementation of interface class scim::ConfigBase.
00378  *
00379  * The read methods will just return false and the default value (if available).
00380  * The write methods will do nothing.
00381  */
00382 class DummyConfig : public ConfigBase
00383 {
00384 
00385 public:
00386     DummyConfig (const String& app_name = String ("scim"));
00387 
00388     virtual ~DummyConfig ();
00389 
00390     virtual bool valid () const;
00391 
00392     virtual bool read (const String& key, String *ret) const;
00393     virtual bool read (const String& key, int *ret) const;
00394     virtual bool read (const String& key, double *ret) const;
00395     virtual bool read (const String& key, bool *ret) const;
00396     virtual bool read (const String& key, std::vector <String> *ret) const;
00397     virtual bool read (const String& key, std::vector <int> *ret) const;
00398 
00399     virtual bool write (const String& key, const String& value);
00400     virtual bool write (const String& key, int value);
00401     virtual bool write (const String& key, double value);
00402     virtual bool write (const String& key, bool value);
00403     virtual bool write (const String& key, const std::vector <String>& value);
00404     virtual bool write (const String& key, const std::vector <int>& value);
00405 
00406     virtual bool flush();
00407 
00408     virtual bool erase (const String& key );
00409 
00410     virtual bool reload ();
00411 };
00412 
00413 /** @} */
00414 
00415 } // namespace scim
00416 
00417 #endif //__SCIM_CONFIG_BASE_H
00418 /*
00419 vi:ts=4:nowrap:ai:expandtab
00420 */

Generated on Tue Apr 19 00:10:59 2005 for scim by  doxygen 1.4.1