Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | 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.14 2004/03/01 09:41:57 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  * @brief The interface class to access the configuration data.
00068  *
00069  * This is an interface class to access the configuration data.
00070  * All of the SCIM objects which have configuration data should 
00071  * use this interface to store and load them.
00072  */
00073 class ConfigBase : public ReferencedObject
00074 {
00075     String m_app_name;
00076 
00077 public:
00078     /**
00079      * @name Constructor and Destructor.
00080      * @{
00081      */
00082 
00083     /**
00084      * @brief Contrustor
00085      * @param app_name - the name of the running application, default is "scim".
00086      */
00087     ConfigBase (const String& app_name = String ("scim"));
00088 
00089     /**
00090      * @brief Virtual destructor 
00091      * empty but ensures that dtor of all derived classes is virtual
00092      */
00093     virtual ~ConfigBase ();
00094 
00095     /**
00096      * @}
00097      */
00098 
00099     /**
00100      * @name Pure virtual methods which should be implemented in derived classes.
00101      * @{
00102      */
00103 
00104     /**
00105      * @brief Check if this Config object is valid.
00106      * @return true if its valid and ready to work.
00107      */
00108     virtual bool valid () const = 0;
00109 
00110     /**
00111      * @brief Read a string from the given key.
00112      * @param key - the key to be read.
00113      * @param ret - the result will be stored into *ret.
00114      * @return true if the string is read successfully, otherwise return false.
00115      */
00116     virtual bool read (const String& key, String *ret) const = 0;
00117 
00118     /**
00119      * @brief Read an int value from the given key.
00120      * @param key - the key to be read.
00121      * @param ret - the result will be stored into *ret.
00122      * @return true if the value is read successfully, otherwise return false.
00123      */
00124     virtual bool read (const String& key, int *ret) const = 0;
00125 
00126     /**
00127      * @brief Read a double value from the given key.
00128      * @param key - the key to be read.
00129      * @param ret - the result will be stored into *ret.
00130      * @return true if the value is read successfully, otherwise return false.
00131      */
00132     virtual bool read (const String& key, double *ret) const = 0;
00133 
00134     /**
00135      * @brief Read a bool value from the given key.
00136      * @param key - the key to be read.
00137      * @param ret - the result will be stored into *ret.
00138      * @return true if the value is read successfully, otherwise return false.
00139      */
00140     virtual bool read (const String& key, bool *ret) const = 0;
00141 
00142     /**
00143      * @brief Read a string list from the given key.
00144      * @param key - the key to be read.
00145      * @param ret - the result will be stored into *ret.
00146      * @return true if the string list is read successfully, otherwise return false.
00147      */
00148     virtual bool read (const String& key, std::vector <String> *ret) const = 0;
00149 
00150     /**
00151      * @brief Read an int list from the given key.
00152      * @param key - the key to be read.
00153      * @param ret - the result will be stored into *ret.
00154      * @return true if the int list is read successfully, otherwise return false.
00155      */
00156     virtual bool read (const String& key, std::vector <int> *ret) const = 0;
00157 
00158     /**
00159      * @brief Write a string to the given key.
00160      * @param key   - the key to be written.
00161      * @param value - the string to be written to the key.
00162      * @return true if success, otherwise false.
00163      */
00164     virtual bool write (const String& key, const String& value) = 0;
00165 
00166     /**
00167      * @brief Write an int value to the given key.
00168      * @param key   - the key to be written.
00169      * @param value - the int value to be written to the key.
00170      * @return true if success, otherwise false.
00171      */
00172     virtual bool write (const String& key, int value) = 0;
00173 
00174     /**
00175      * @brief Write a double value to the given key.
00176      * @param key   - the key to be written.
00177      * @param value - the double value to be written to the key.
00178      * @return true if success, otherwise false.
00179      */
00180     virtual bool write (const String& key, double value) = 0;
00181 
00182     /**
00183      * @brief Write a bool value to the given key.
00184      * @param key   - the key to be written.
00185      * @param value - the bool value to be written to the key.
00186      * @return true if success, otherwise false.
00187      */
00188     virtual bool write (const String& key, bool value) = 0;
00189 
00190     /**
00191      * @brief Write a string list to the given key.
00192      * @param key   - the key to be written.
00193      * @param value - the string list to be written to the key.
00194      * @return true if success, otherwise false.
00195      */
00196     virtual bool write (const String& key, const std::vector <String>& value) = 0;
00197 
00198     /**
00199      * @brief Write an int list to the given key.
00200      * @param key   - the key to be written.
00201      * @param value - the int list to be written to the key.
00202      * @return true if success, otherwise false.
00203      */
00204     virtual bool write (const String& key, const std::vector <int>& value) = 0;
00205 
00206     /**
00207      * @brief Permanently writes all changes.
00208      * @return true if success.
00209      */
00210     virtual bool flush() = 0;
00211 
00212     /**
00213      * @brief Erase a key and its value
00214      * @param key - the key to be erased.
00215      * @return true if success.
00216      */
00217     virtual bool erase (const String& key) = 0;
00218 
00219     /**
00220      * @}
00221      */
00222 
00223     /**
00224      * @name Other helper methods.
00225      * @{
00226      */
00227 
00228     /**
00229      * @brief Read a string from the given key with a default fallback value.
00230      *
00231      * If failed to read from the given key, then return the given default value.
00232      *
00233      * @param key    - the key to be read.
00234      * @param defVal - the default value to be return if failed to read.
00235      * @return The result string.
00236      */
00237     String read (const String& key, const String& defVal = String ()) const;
00238 
00239     /**
00240      * @brief Read an int value from the given key with a default fallback value.
00241      *
00242      * If failed to read from the given key, then return the given default value.
00243      *
00244      * @param key    - the key to be read.
00245      * @param defVal - the default value to be return if failed to read.
00246      * @return The result int value.
00247      */
00248     int read (const String& key, int defVal) const;
00249 
00250     /**
00251      * @brief Read a double value from the given key with a default fallback value.
00252      *
00253      * If failed to read from the given key, then return the given default value.
00254      *
00255      * @param key    - the key to be read.
00256      * @param defVal - the default value to be return if failed to read.
00257      * @return The result double value.
00258      */
00259     double read (const String& key, double defVal) const;
00260 
00261     /**
00262      * @brief Read a bool value from the given key with a default fallback value.
00263      *
00264      * If failed to read from the given key, then return the given default value.
00265      *
00266      * @param key    - the key to be read.
00267      * @param defVal - the default value to be return if failed to read.
00268      * @return The result bool value.
00269      */
00270     bool read (const String& key, bool defVal) const;
00271 
00272     /**
00273      * @brief Read a string list from the given key with a default fallback value.
00274      *
00275      * If failed to read from the given key, then return the given default value.
00276      *
00277      * @param key    - the key to be read.
00278      * @param defVal - the default value to be return if failed to read.
00279      * @return The result string list.
00280      */
00281     std::vector <String> read (const String& key, const std::vector <String>& defVal) const;
00282 
00283     /**
00284      * @brief Read an int list from the given key with a default fallback value.
00285      *
00286      * If failed to read from the given key, then return the given default value.
00287      *
00288      * @param key    - the key to be read.
00289      * @param defVal - the default value to be return if failed to read.
00290      * @return The result int list.
00291      */
00292     std::vector <int> read (const String& key, const std::vector <int>& defVal) const;
00293 
00294     /**
00295      * @brief Get the application's name.
00296      * @return the name of the current application.
00297      */
00298     const String& get_app_name() const;
00299 
00300     /**
00301      * @brief Set the name of the current application.
00302      * @param name - the name of the current application.
00303      */
00304     void set_app_name (const String& name);
00305 
00306     /** @} */ 
00307 
00308 public:
00309     /**
00310      * @brief Set the default global Config object.
00311      * 
00312      * There is only one global Config object in an application.
00313      * All other objects should use it by default.
00314      *
00315      * @param p_config - a smart pointer to the Config object.
00316      * @return a smart pointer to the old default Config object.
00317      */
00318     static ConfigPointer set (const ConfigPointer &p_config);
00319 
00320     /**
00321      * @brief Get the default global Config object.
00322      * 
00323      * The default global Config object can be set with function ConfigBase::set.
00324      * If there is no default object set, a new object can be created if needed.
00325      *
00326      * @param create_on_demand - if it's true then a new object will be created,
00327      *                           if there is no one available.
00328      * @param default_module   - the Config module should be used to create the 
00329      *                           default Config object. Default is "simple" module.
00330      * @return a smart pointer to the default global Config object.
00331      */
00332     static ConfigPointer get (bool create_on_demand = true,
00333                                 const String &default_module = String ("simple"));
00334 };
00335 
00336 /**
00337  * @brief A dummy implementation of interface class scim::ConfigBase.
00338  *
00339  * The read methods will just return false and the default value (if available).
00340  * The write methods will do nothing.
00341  */
00342 class DummyConfig : public ConfigBase
00343 {
00344 
00345 public:
00346     DummyConfig (const String& app_name = String ("scim"));
00347 
00348     virtual ~DummyConfig ();
00349 
00350     virtual bool valid () const;
00351 
00352     virtual bool read (const String& key, String *ret) const;
00353     virtual bool read (const String& key, int *ret) const;
00354     virtual bool read (const String& key, double *ret) const;
00355     virtual bool read (const String& key, bool *ret) const;
00356     virtual bool read (const String& key, std::vector <String> *ret) const;
00357     virtual bool read (const String& key, std::vector <int> *ret) const;
00358 
00359     virtual bool write (const String& key, const String& value);
00360     virtual bool write (const String& key, int value);
00361     virtual bool write (const String& key, double value);
00362     virtual bool write (const String& key, bool value);
00363     virtual bool write (const String& key, const std::vector <String>& value);
00364     virtual bool write (const String& key, const std::vector <int>& value);
00365 
00366     virtual bool flush();
00367 
00368     virtual bool erase (const String& key );
00369 
00370 };
00371 
00372 /** @} */
00373 
00374 } // namespace scim
00375 
00376 #endif //__SCIM_CONFIG_BASE_H
00377 /*
00378 vi:ts=4:nowrap:ai:expandtab
00379 */

Generated on Fri May 7 17:27:25 2004 for scim by doxygen 1.3.6