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 */