00001 // Catalog.h 00002 00003 #ifndef CATALOG_H 00004 #define CATALOG_H 00005 00006 #include <string> 00007 #include <map> 00008 00009 #include "Study.h" 00010 00011 namespace Yosokumo 00012 { 00013 /** 00014 * An index to all the studies on which a given user has a role. A catalog 00015 * has these attributes: 00016 * <ul> 00017 * <li>an identifier and a name of the user to whom the catalog belongs 00018 * <li>a collection of all the studies for which the user has a role, indexed 00019 * by study identifier 00020 * </ul> 00021 * 00022 * @author Roger House 00023 * @version 0.9 00024 */ 00025 00026 class Catalog 00027 { 00028 /** 00029 * Identifier of the user to whom the catalog belongs. 00030 */ 00031 std::string userIdentifier; 00032 00033 /** 00034 * User name of the user to whom the catalog belongs. 00035 */ 00036 std::string userName; 00037 00038 /** 00039 * URI of the catalog. 00040 */ 00041 std::string catalogLocation; 00042 00043 // At present the studyCollection map is implemented as an STL map 00044 // because this implementation has O(ln n) performance for insert, remove, 00045 // and find, and O(1) for "next". The latter is used to iterate 00046 // over the map, and thus we do not want it to be expensive. 00047 00048 typedef std::map<std::string, Study> StudyMap; 00049 00050 /** 00051 * Collection of studies comprising the catalog. 00052 */ 00053 StudyMap studyCollection; 00054 00055 public: 00056 00057 /* 00058 * For iterating over studies in a catalog. 00059 */ 00060 00061 typedef StudyMap::iterator StudyIterator; 00062 typedef StudyMap::const_iterator StudyConstIterator; 00063 00064 00065 // Constructors 00066 00067 /** 00068 * Initializes a newly created <code>Catalog</code> object with default 00069 * attributes. 00070 * <ul> 00071 * <li>user identifier "ABCDEF0123456789" 00072 * <li>user name "" 00073 * </ul> 00074 */ 00075 Catalog(); 00076 00077 /** 00078 * Initializes a newly created <code>Catalog</code> object with attributes 00079 * specified by the input parameters. 00080 * 00081 * @param userIdentifier the unique identifier for the user. 00082 * @param userName the name of the user. 00083 */ 00084 Catalog( 00085 const std::string &userIdentifier, const std::string &userName); 00086 00087 /** 00088 * Copy constructor - initializes a newly created <code>Catalog</code> 00089 * object with a copy of another <code>Catalog</code> object. 00090 * 00091 * @param rhs the <code>Catalog</code> to make a copy of. 00092 */ 00093 Catalog(const Catalog &rhs); 00094 00095 /** 00096 * Destructor - destroy a <code>Catalog</code> object. 00097 */ 00098 virtual ~Catalog(); 00099 00100 /** 00101 * Assignment operator - assign one <code>Catalog</code> to another. 00102 * 00103 * @param rhs the righthand side of the assignment. 00104 * 00105 * @return a reference to <code>this</code> Catalog. 00106 */ 00107 Catalog &operator=(const Catalog& rhs); 00108 00109 // Equality operators 00110 00111 /** 00112 * Equality operator - compare two <code>Catalog</code> for equality. 00113 * 00114 * @param rhs the righthand side of the equality. 00115 * 00116 * @return <code>true</code> if and only if <code>this</code> 00117 * <code>Catalog</code> and the righthand side 00118 * <code>Catalog</code> are identically equal. 00119 */ 00120 bool operator==(const Catalog &rhs) const; 00121 00122 /** 00123 * Inequality operator - compare two <code>Catalog</code> for inequality. 00124 * 00125 * @param rhs the righthand side of the inequality. 00126 * 00127 * @return <code>true</code> if and only if <code>this</code> 00128 * <code>Catalog</code> and the righthand side 00129 * <code>Catalog</code> are not identically equal. 00130 */ 00131 bool operator!=(const Catalog &rhs) const; 00132 00133 // Copy catalog 00134 00135 /** 00136 * Make a copy of a catalog. 00137 * 00138 * @param t the catalog to copy to (destination). 00139 * @param s the catalog to copy from (source). 00140 * @return a copy of s. 00141 */ 00142 static void copyCatalog(Catalog &t, const Catalog &s); 00143 00144 00145 // Setters and getters 00146 00147 /** 00148 * Set the user identifier. 00149 * 00150 * @param id the identifier of the user to whom the catalog belongs. 00151 * May be null. 00152 */ 00153 void setUserIdentifier(const std::string &id); 00154 00155 /** 00156 * Return the user identifier. 00157 * 00158 * @return the identifier of the user to whom the catalog belongs. 00159 * May be null. 00160 */ 00161 std::string getUserIdentifier() const; 00162 00163 /** 00164 * Set the user name. 00165 * 00166 * @param name the name of the user to whom the catalog belongs. 00167 * May be null. 00168 */ 00169 void setUserName(const std::string &name); 00170 00171 /** 00172 * Return the user name. 00173 * 00174 * @return the name of the user to whom the catalog belongs. May be null. 00175 */ 00176 std::string getUserName() const; 00177 00178 /** 00179 * Set the catalog location. 00180 * 00181 * @param loc the location of this catalog. May be null. 00182 */ 00183 void setCatalogLocation(const std::string &loc); 00184 00185 /** 00186 * Return the catalog location. 00187 * 00188 * @return the location of this catalog. May be null. 00189 */ 00190 std::string getCatalogLocation() const; 00191 00192 // Access to the study collection 00193 // 00194 // That a map is used to implement the study collection is hidden 00195 // from the Catalog client, as much as this makes sense. 00196 00197 /** 00198 * Add a study to the catalog. In all cases the <code>Study</code> 00199 * parameter is added to the catalog. The return value distinguishes two 00200 * possibilities. 00201 * 00202 * @param newStudy the <code>Study</code> to add to the catalog. 00203 * @param oldStudy where to save an existing study with the same study 00204 * id as newStudy. 00205 * 00206 * @return <code>true</code> means there was no study already in the 00207 * catalog with the same study identifier as newStudy. The 00208 * contents of oldStudy are unchanged. 00209 * <code>false</code> means there was a study with the same study 00210 * identifier already in the catalog, and it has been replaced 00211 * by the newStudy. The old study is saved in oldStudy. 00212 * In both cases, newStudy has been added to the catalog. 00213 */ 00214 bool addStudy(const Study &newStudy, Study &oldStudy); 00215 00216 /** 00217 * Add a study to the catalog. In all cases the <code>Study</code> 00218 * parameter is added to the catalog. The return value distinguishes two 00219 * possibilities. 00220 * 00221 * @param newStudy the <code>Study</code> to add to the catalog. 00222 * 00223 * @return <code>true</code> means there was no study already in the 00224 * catalog with the same study identifier as newStudy. 00225 * <code>false</code> means there was a study with the same study 00226 * identifier already in the catalog, and it has been replaced 00227 * by the newStudy. The old study is no longer available. 00228 * In both cases, newStudy has been added to the catalog. 00229 */ 00230 bool addStudy(const Study &newStudy); 00231 00232 /** 00233 * Remove a study from the catalog. 00234 * 00235 * @param studyIdentifier the study identifier of the <code>Study</code> 00236 * to remove from the catalog. 00237 * 00238 * @return <code>false</code> means there was no study in the catalog with 00239 * the study identifier specified by the parameter; the 00240 * catalog is left unchanged. 00241 * <code>true</code> means that there was a study in the 00242 * catalog with the study identifier specified by the 00243 * parameter; the study has been removed from the catalog. 00244 */ 00245 bool removeStudy(const std::string &studyIdentifier); 00246 00247 /** 00248 * Remove all studies from the catalog. After a call of this method, 00249 * the catalog is empty, i.e., it contains no studies. 00250 * 00251 */ 00252 void clearStudies(); 00253 00254 /** 00255 * Return a study from the catalog. 00256 * 00257 * @param studyIdentifier the identifier of the <code>Study</code> to 00258 * get from the catalog. 00259 * @param foundStudy where to place the found <code>Study</code>. 00260 * 00261 * @return <code>false</code> means there is no study in the catalog with 00262 * the study identifier specified by the parameter. In this 00263 * case foundStudy is unchanged. 00264 * <code>true</code> means that there is a study in the catalog 00265 * with the study identifier specified by the parameter. 00266 * foundRound contains the found study. 00267 */ 00268 bool getStudy(const std::string &studyIdentifier, Study &foundStudy) const; 00269 00270 /** 00271 * Test if a study is in the catalog. 00272 * 00273 * @param studyIdentifier the identifier of the <code>Study</code> to 00274 * test for. 00275 * @return <code>false</code> means there is no study in the catalog with the 00276 * identifier specified by the parameter. 00277 * <code>true</code> means that there is a study in the catalog 00278 * with the identifier specified by the parameter. 00279 */ 00280 bool containsStudy(const std::string &studyIdentifier) const; 00281 00282 /** 00283 * Return the number of studies in the catalog. 00284 * 00285 * @return the number of studies in the catalog. 00286 */ 00287 int size() const; 00288 00289 /** 00290 * Return <code>true</code> if the catalog contains no studies. 00291 * 00292 * @return <code>true</code> if the catalog contains no studies. 00293 * <code>false</code> otherwise. 00294 */ 00295 bool isEmpty() const; 00296 00297 /** 00298 * Return an iterator referring to the first study in the catalog. This 00299 * method can be used with the end() method to iterate over all studys in 00300 * a catalog like this: 00301 * <pre> 00302 * Catalog catalog; 00303 * ... 00304 * StudyIterator iter; 00305 * 00306 * for (iter = catalog.begin(); iter != catalog.end(); ++iter) 00307 * { 00308 * Study study = iter->second; 00309 * process study 00310 * } 00311 * </pre> 00312 * 00313 * @return an iterator referring to the first study in the catalog. 00314 */ 00315 StudyIterator begin(); 00316 StudyConstIterator begin() const; 00317 00318 /** 00319 * Return an iterator referring to the past-the-end study in the catalog. 00320 * See begin() for an example of how to use end() to iterate over studys. 00321 * 00322 * @return an iterator referring to the past-the-end study in the catalog. 00323 */ 00324 StudyIterator end(); 00325 StudyConstIterator end() const; 00326 00327 // Utility 00328 00329 /** 00330 * Return a string representation of this <code>Catalog</code>. Note that 00331 * for a study in the catalog only the study identifier and study name 00332 * are represented as a string, not the entire study. 00333 * 00334 * @return the string representation of this <code>Catalog</code>. 00335 */ 00336 std::string toString() const; 00337 00338 /** 00339 * Return a string representation of this <code>Catalog</code>. Note that 00340 * for a study in the catalog only the study identifier and study name 00341 * are represented as a string, not the entire study. 00342 * 00343 * @param showAll specifies if internal data members should be shown. 00344 * @return the string representation of this <code>Catalog</code>. 00345 */ 00346 std::string toStringInternal(bool showAll) const; 00347 00348 }; // end class Catalog 00349 00350 } // end namespace Yosokumo 00351 00352 #endif // CATALOG_H 00353 00354 // end Catalog.h