WordContext.h

00001 //
00002 // WordContext.h
00003 //
00004 // NAME
00005 // 
00006 // read configuration and setup mifluz context.
00007 //
00008 // SYNOPSIS
00009 // 
00010 // #include <mifluz.h>
00011 // 
00012 // WordContext context;
00013 // 
00014 // DESCRIPTION
00015 // 
00016 // The WordContext object must be the first object created.
00017 // All other objects (WordList, WordReference, WordKey and WordRecord)
00018 // are allocated via the corresponding methods of WordContext (List,
00019 // Word, Key and Record respectively). 
00020 //
00021 // The WordContext object contains a <b>Configuration</b> object 
00022 // that holds the configuration parameters used by the instance. 
00023 // If a configuration parameter is changed, the <i>ReInitialize</b> 
00024 // method should be called to take them in account.
00025 //
00026 // CONFIGURATION
00027 // 
00028 // wordlist_monitor {true|false} (default false)
00029 // If true create a <i>WordMonitor</i> instance to gather statistics and 
00030 // build reports.
00031 //
00032 // wordlist_multi {true|false} (default false)
00033 // If true the <b>List</b> method creates a <b>WordListMulti</b> instance,
00034 // if false it creates a <b>WordListOne</b> instance.
00035 //
00036 // ENVIRONMENT
00037 //
00038 // <b>MIFLUZ_CONFIG</b> file name of configuration file read by
00039 // WordContext(3). Defaults to <b>~/.mifluz.</b> or <b>/usr/etc/mifluz.conf</b>
00040 //
00041 // END
00042 //
00043 // Part of the ht://Dig package <http://www.htdig.org/>
00044 // Copyright (c) 1999, 2000, 2001 The ht://Dig Group
00045 // For copyright details, see the file COPYING in your distribution
00046 // or the GNU General Public License version 2 or later
00047 // <http://www.gnu.org/copyleft/gpl.html>
00048 //
00049 // $Id: WordContext_8h-source.html,v 1.1 2008年06月08日 10:12:59 sebdiaz Exp $
00050 //
00051 #ifndef _WordContext_h_
00052 #define _WordContext_h_
00053 
00054 #ifndef SWIG
00055 #include "Configuration.h"
00056 #include "WordType.h"
00057 #include "WordKeyInfo.h"
00058 #include "WordRecordInfo.h"
00059 #include "WordDBInfo.h"
00060 #include "WordMonitor.h"
00061 #endif /* SWIG */
00062 
00063 class WordRecord;
00064 class WordKey;
00065 class WordReference;
00066 class WordList;
00067 
00068 //
00069 // Short hand for calling Initialize for all classes
00070 // Word* that have a single instance (WordType, WordKeyInfo, WordRecordInfo).
00071 //
00072 class WordContext
00073 {
00074 public:
00075 #ifndef SWIG
00076 //-
00077 // Constructor. Read the configuration parameters from the
00078 // environment. If the environment variable <b>MIFLUZ_CONFIG</b> is
00079 // set to a pathname, read it as a configuration file. If
00080 // <b>MIFLUZ_CONFIG</b> is not set, try to read the <i>~/.mifluz</b>
00081 // configuration file or <i>/usr/etc/mifluz.conf</i>. See the mifluz
00082 // manual page for a complete list of the configuration attributes.
00083 //
00084 WordContext() {
00085 Clear();
00086 Initialize();
00087 }
00088 //-
00089 // Constructor. The <b>config</b> argument must contain all the configuration
00090 // parameters, no configuration file is loaded from the environment.
00091 //
00092 WordContext(const Configuration &config) {
00093 Clear();
00094 Initialize(config);
00095 }
00096 #endif /* SWIG */
00097 //-
00098 // Constructor. The <b>array</b> argument holds configuration parameters
00099 // that will override their equivalent in the configuration file read 
00100 // from the environment.
00101 //
00102 WordContext(const ConfigDefaults *array) {
00103 Clear();
00104 Initialize(array);
00105 }
00106 #ifndef SWIG
00107 ~WordContext() {
00108 Finish();
00109 }
00110 
00111 //-
00112 // Initialize the WordContext object. This method is called by 
00113 // every constructor.
00114 //
00115 // When calling <b>Initialize</b> a second time, one must ensure
00116 // that all WordList and WordCursor objects have been
00117 // destroyed. WordList and WordCursor internal state depends on the
00118 // current WordContext that will be lost by a second call. 
00119 // <br>
00120 // For those interested by the internals, the <b>Initialize</b> function
00121 // maintains a Berkeley DB environment (DB_ENV) in the following way:
00122 //
00123 // First invocation:
00124 // <pre>
00125 // Initialize -> new DB_ENV (thru WordDBInfo)
00126 // </pre>
00127 //
00128 // Second invocation:
00129 // <pre>
00130 // Initialize -> delete DB_ENV -> new DB_ENV (thru WordDBInfo)
00131 // </pre>
00132 //
00133 void Initialize(const Configuration &config);
00134 //-
00135 // Initialize the WordContext object.
00136 // Build a <i>Configuration</i> object from the file pointed to by the 
00137 // MIFLUZ_CONFIG environment variable or ~/.mifluz or /usr/etc/mifluz.conf.
00138 // The <b>config_defaults</b> argument, if provided, is passed to
00139 // the <i>Configuration</i> object using the <b>Defaults</b> method.
00140 // The <b>Initialize(const Configuration &)</b> method is then called
00141 // with the <i>Configuration</i> object.
00142 // Return OK if success, NOTOK otherwise.
00143 // Refer to the <i>Configuration</i> description for more information.
00144 //
00145 //
00146 int Initialize(const ConfigDefaults* config_defaults = 0);
00147 #endif /* SWIG */
00148 //-
00149 // Destroy internal state except the <i>Configuration</i> object and
00150 // rebuild it. May be used when the configuration is changed to
00151 // take these changes in account.
00152 // Return OK if success, NOTOK otherwise.
00153 //
00154 int ReInitialize();
00155 
00156 //
00157 // Accessors
00158 //
00159 #ifndef SWIG
00160 //-
00161 // Return the <b>WordType</b> data member of the current object as a const. 
00162 //
00163 const WordType& GetType() const { return *type; }
00164 #endif /* SWIG */
00165 //-
00166 // Return the <b>WordType</b> data member of the current object. 
00167 //
00168 WordType& GetType() { return *type; }
00169 
00170 #ifndef SWIG
00171 //-
00172 // Return the <b>WordKeyInfo</b> data member of the current object
00173 // as a const.
00174 //
00175 const WordKeyInfo& GetKeyInfo() const { return *key_info; }
00176 #endif /* SWIG */
00177 //-
00178 // Return the <b>WordKeyInfo</b> data member of the current object. 
00179 //
00180 WordKeyInfo& GetKeyInfo() { return *key_info; }
00181 
00182 #ifndef SWIG
00183 //-
00184 // Return the <b>WordRecordInfo</b> data member of the current
00185 // object as a const.
00186 //
00187 const WordRecordInfo& GetRecordInfo() const { return *record_info; }
00188 #endif /* SWIG */
00189 //-
00190 // Return the <b>WordRecordInfo</b> data member of the current object. 
00191 //
00192 WordRecordInfo& GetRecordInfo() { return *record_info; }
00193 
00194 #ifndef SWIG
00195 //-
00196 // Return the <b>WordDBInfo</b> data member of the current object as
00197 // a const.
00198 //
00199 const WordDBInfo& GetDBInfo() const { return *db_info; }
00200 #endif /* SWIG */
00201 //-
00202 // Return the <b>WordDBInfo</b> data member of the current object. 
00203 //
00204 WordDBInfo& GetDBInfo() { return *db_info; }
00205 
00206 #ifndef SWIG
00207 //-
00208 // Return the <b>WordMonitor</b> data member of the current object
00209 // as a const. The pointer may be NULL if the word_monitor
00210 // attribute is false.
00211 //
00212 const WordMonitor* GetMonitor() const { return monitor; }
00213 #endif /* SWIG */
00214 //-
00215 // Return the <b>WordMonitor</b> data member of the current object.
00216 // The pointer may be NULL if the word_monitor attribute is false.
00217 //
00218 WordMonitor* GetMonitor() { return monitor; }
00219 
00220 #ifndef SWIG
00221 //-
00222 // Return the <b>Configuration</b> data member of the current object
00223 // as a const.
00224 //
00225 const Configuration& GetConfiguration() const { return *configuration; }
00226 #endif /* SWIG */
00227 //-
00228 // Return the <b>Configuration</b> data member of the current object. 
00229 //
00230 Configuration& GetConfiguration() { return *configuration; }
00231 
00232 #ifndef SWIG
00233 //
00234 // Builders
00235 //
00236 //-
00237 // Return a new <b>WordList</b> object, using the 
00238 // WordList(WordContext*) constructor. It is the responsibility of the
00239 // caller to delete this object before the WordContext object is
00240 // deleted. Refer to the <b>wordlist_multi</b> configuration parameter
00241 // to know the exact type of the object created.
00242 //
00243 WordList* List();
00244 
00245 //-
00246 // Return a new <b>WordReference</b> object, using the
00247 // WordReference(WordContext*) constructor. It is the responsibility of the
00248 // caller to delete this object before the WordContext object is
00249 // deleted.
00250 //
00251 WordReference* Word();
00252 //-
00253 // Return a new <b>WordReference</b> object, using the
00254 // WordReference(WordContext*, const String&, const& String)
00255 // constructor. It is the responsibility of the
00256 // caller to delete this object before the WordContext object is
00257 // deleted.
00258 //
00259 WordReference* Word(const String& key0, const String& record0);
00260 //-
00261 // Return a new <b>WordReference</b> object, using the
00262 // WordReference(WordContext*, const String&)
00263 // constructor. It is the responsibility of the
00264 // caller to delete this object before the WordContext object is
00265 // deleted.
00266 //
00267 WordReference* Word(const String& word);
00268 
00269 //-
00270 // Return a new <b>WordRecord</b> object, using the
00271 // WordRecord(WordContext*) constructor. It is the responsibility of the
00272 // caller to delete this object before the WordContext object is
00273 // deleted.
00274 //
00275 WordRecord* Record();
00276 
00277 //-
00278 // Return a new <b>WordKey</b> object, using the
00279 // WordKey(WordContext*) constructor. It is the responsibility of the
00280 // caller to delete this object before the WordContext object is
00281 // deleted.
00282 //
00283 WordKey* Key();
00284 //-
00285 // Return a new <b>WordKey</b> object, using the
00286 // WordKey(WordContext*, const String&) constructor. It is the
00287 // responsibility of the caller to delete this object before the
00288 // WordContext object is deleted.
00289 //
00290 WordKey* Key(const String& word);
00291 //-
00292 // Return a new <b>WordKey</b> object, using the
00293 // WordKey(WordContext*, const WordKey&) constructor. It is the
00294 // responsibility of the caller to delete this object before the
00295 // WordContext object is deleted.
00296 //
00297 WordKey* Key(const WordKey& other);
00298 //-
00299 // Return the full pathname of the configuration file. The configuration
00300 // file lookup first searches for the file pointed by the 
00301 // <b>MIFLUZ_CONFIG</b> environment variable then <b>~/.mifluz</b> and
00302 // finally <b>/usr/etc/mifluz.conf</b>. If no configuration file is found,
00303 // return the empty string.
00304 //
00305 static String ConfigFile();
00306 
00307 private:
00308 void Clear() {
00309 type = 0;
00310 key_info = 0;
00311 record_info = 0;
00312 db_info = 0;
00313 monitor = 0;
00314 configuration = 0;
00315 }
00316 void Finish();
00317 
00318 WordType* type;
00319 WordKeyInfo* key_info;
00320 WordRecordInfo* record_info;
00321 WordDBInfo* db_info;
00322 WordMonitor* monitor;
00323 Configuration* configuration;
00324 #endif /* SWIG */
00325 };
00326 
00327 #endif // _WordContext_h_