1 #ifndef CORELIB___NCBI_CONFIG__HPP
2 #define CORELIB___NCBI_CONFIG__HPP
3 
4 /*  $Id: ncbi_config.hpp 574926 2018-11-20 20:23:54Z ucko $
5  * ===========================================================================
6  *
7  *                            PUBLIC DOMAIN NOTICE
8  *               National Center for Biotechnology Information
9  *
10  *  This software/database is a "United States Government Work" under the
11  *  terms of the United States Copyright Act.  It was written as part of
12  *  the author's official duties as a United States Government employee and
13  *  thus cannot be copyrighted.  This software/database is freely available
14  *  to the public for use. The National Library of Medicine and the U.S.
15  *  Government have not placed any restriction on its use or reproduction.
16  *
17  *  Although all reasonable efforts have been taken to ensure the accuracy
18  *  and reliability of the software and data, the NLM and the U.S.
19  *  Government do not and cannot warrant the performance or results that
20  *  may be obtained by using this software or data. The NLM and the U.S.
21  *  Government disclaim all warranties, express or implied, including
22  *  warranties of performance, merchantability or fitness for any particular
23  *  purpose.
24  *
25  *  Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors:  Anatoliy Kuznetsov
30  *
31  */
32 
33 /// @file ncbi_config.hpp
34 /// Parameters initialization model
35 
36 #include <corelib/ncbi_tree.hpp>
37 
38 BEGIN_NCBI_SCOPE
39 
40 /** @addtogroup ModuleConfig
41  *
42  * @{
43  */
44 
45 
46 /////////////////////////////////////////////////////////////////////////////
47 ///
48 /// CConfigException --
49 ///
50 /// Exception generated by configuration API
51 
52 class NCBI_XNCBI_EXPORT CConfigException : public CCoreException
53 {
54 public:
55     enum EErrCode {
56         eParameterMissing,      ///< Missing mandatory parameter
57         eSynonymDuplicate,
58         eInvalidParameter,      ///< Invalid parameter value
59     };
60 
61     /// Translate from the error code value to its string representation.
62     virtual const char* GetErrCodeString(void) const override;
63 
64     // Standard exception boilerplate code.
65     NCBI_EXCEPTION_DEFAULT(CConfigException, CCoreException);
66 };
67 
68 
69 
70 class IRegistry;
71 
72 class NCBI_XNCBI_EXPORT CConfig
73 {
74 public:
75     /// Instantiation parameters tree.
76     ///
77     /// Plug-in instantiation model is based on class factories.
78     /// Recursive class factory calls are modeled as tree, where specific
79     /// subtree is responsible for CF parameters
80     ///
81     typedef CTreePair<string, string>  TParamValue;
82     typedef TParamValue::TPairTreeNode TParamTree;
83 
84 public:
85     /// Optionally takes ownership on passed param_tree
86     CConfig(TParamTree* param_tree, EOwnership own = eTakeOwnership);
87 
88     /// Construct, take no tree ownership
89     CConfig(const TParamTree* param_tree);
90 
91     /// Take registry and create a config tree out of it
92     CConfig(const IRegistry& reg);
93     ~CConfig();
94 
95     /// Defines how to behave when parameter is missing
96     enum EErrAction {
97         eErr_Throw,    ///< Throw an exception on error
98         eErr_NoThrow   ///< Return default value on error
99     };
100 
101     /// Utility function to get an element of parameter tree
102     /// Throws an exception when mandatory parameter is missing
103     /// (or returns the default value)
104     ///
105     /// @param driver_name
106     ///    Name of the module requesting parameter (used in diagnostics)
107     /// @param params
108     ///    Parameters tree
109     /// @param param_name
110     ///    Name of the parameter
111     /// @param mandatory
112     ///    Error action
113     /// @param default_value
114     ///    Default value for missing parameters
115     string GetString(const string&  driver_name,
116                      const string&  param_name,
117                      EErrAction     on_error,
118                      const string&  default_value,
119                      const list<string>* synonyms = NULL);
120 
121     /// This version always defaults to the empty string so that it
122     /// can safely return a reference.  (default_value may be
123     /// temporary in some cases.)
124     const string& GetString(const string&  driver_name,
125                             const string&  param_name,
126                             EErrAction     on_error,
127                             const list<string>* synonyms = NULL);
128 
129     /// Utility function to get an integer element of parameter tree
130     /// Throws an exception when mandatory parameter is missing
131     /// (or returns the default value)
132     ///
133     /// @param driver_name
134     ///    Name of the module requesting parameter (used in diagnostics)
135     /// @param params
136     ///    Parameters tree
137     /// @param param_name
138     ///    Name of the parameter
139     /// @param mandatory
140     ///    Error action
141     /// @param default_value
142     ///    Default value for missing parameters
143     /// @sa ParamTree_GetString
144     int GetInt(const string&  driver_name,
145                const string&  param_name,
146                EErrAction     on_error,
147                int            default_value,
148                const list<string>* synonyms = NULL);
149 
150     /// Utility function to get an integer element of parameter tree
151     /// Throws an exception when mandatory parameter is missing
152     /// (or returns the default value)
153     /// This function understands KB, MB, GB qualifiers at the end of the string
154     ///
155     /// @param driver_name
156     ///    Name of the module requesting parameter (used in diagnostics)
157     /// @param params
158     ///    Parameters tree
159     /// @param param_name
160     ///    Name of the parameter
161     /// @param mandatory
162     ///    Error action
163     /// @param default_value
164     ///    Default value for missing parameters
165     /// @sa ParamTree_GetString
166     Uint8 GetDataSize(const string&  driver_name,
167                       const string&  param_name,
168                       EErrAction     on_error,
169                       unsigned int   default_value,
170                       const list<string>* synonyms = NULL);
171 
172     /// Utility function to get an integer element of parameter tree
173     /// Throws an exception when mandatory parameter is missing
174     /// (or returns the default value)
175     ///
176     /// @param driver_name
177     ///    Name of the module requesting parameter (used in diagnostics)
178     /// @param params
179     ///    Parameters tree
180     /// @param param_name
181     ///    Name of the parameter
182     /// @param mandatory
183     ///    Error action
184     /// @param default_value
185     ///    Default value for missing parameters
186     /// @sa ParamTree_GetString
187     bool GetBool(const string&  driver_name,
188                  const string&  param_name,
189                  EErrAction     on_error,
190                  bool           default_value,
191                  const list<string>* synonyms = NULL);
192 
193     /// Utility function to get a double element of parameter tree
194     /// Throws an exception when mandatory parameter is missing
195     /// (or returns the default value)
196     ///
197     /// @param driver_name
198     ///    Name of the module requesting parameter (used in diagnostics)
199     /// @param params
200     ///    Parameters tree
201     /// @param param_name
202     ///    Name of the parameter
203     /// @param mandatory
204     ///    Error action
205     /// @param default_value
206     ///    Default value for missing parameters
207     /// @sa ParamTree_GetString
208     double GetDouble(const string&  driver_name,
209                      const string&  param_name,
210                      EErrAction     on_error,
211                      double         default_value,
212                      const list<string>* synonyms = NULL);
213 
GetTree() const214     const TParamTree* GetTree() const { return m_ParamTree.get(); }
215 
216     /// Reconstruct param tree from the application registry
217     /// @param reg
218     ///     Application registry (loaded from the INI file)
219     /// @return
220     ///     Reconstructed tree (caller is responsible for deletion)
221     static TParamTree* ConvertRegToTree(const IRegistry&  reg);
222 
223     /// Overloading of getters for generic programming
Get(const string & d,const string & p,EErrAction e,const string & v,const list<string> * s=NULL)224     string Get(const string& d, const string& p, EErrAction e, const string& v,
225             const list<string>* s = NULL)
226     { return GetString(d, p, e, v, s); }
227 
Get(const string & d,const string & p,EErrAction e,int v,const list<string> * s=NULL)228     int Get(const string& d, const string& p, EErrAction e, int v,
229             const list<string>* s = NULL)
230     { return GetInt(d, p, e, v, s); }
231 
Get(const string & d,const string & p,EErrAction e,bool v,const list<string> * s=NULL)232     bool Get(const string& d, const string& p, EErrAction e, bool v,
233             const list<string>* s = NULL)
234     { return GetBool(d, p, e, v, s); }
235 
Get(const string & d,const string & p,EErrAction e,double v,const list<string> * s=NULL)236     double Get(const string& d, const string& p, EErrAction e, double v,
237             const list<string>* s = NULL)
238     { return GetDouble(d, p, e, v, s); }
239 
240 private:
241     CConfig(const CConfig&);
242     CConfig& operator=(const CConfig&);
243 
244 protected:
245     const string& x_GetString(const string&  driver_name,
246                               const string&  param_name,
247                               EErrAction     on_error,
248                               const string&  default_value,
249                               const list<string>* synonyms);
250 
251 protected:
252     AutoPtr<TParamTree> m_ParamTree;
253 };
254 
255 /* @} */
256 
257 
258 END_NCBI_SCOPE
259 
260 #endif  /* CORELIB___NCBI_CONFIG__HPP */
261