00001 // Roster.h 00002 00003 #ifndef ROSTER_H 00004 #define ROSTER_H 00005 00006 #include <string> 00007 #include <map> 00008 00009 #include "Role.h" 00010 00011 namespace Yosokumo 00012 { 00013 /** 00014 * For each study, a list of users that have a role on the study. A roster 00015 * has these attributes: 00016 * <ul> 00017 * <li>an identifier and a name of the study to which the roster belongs 00018 * <li>a collection of all the roles associated with the study, indexed by 00019 * user identifier 00020 * </ul> 00021 * 00022 * @author Roger House 00023 * @version 0.9 00024 */ 00025 class Roster 00026 { 00027 std::string studyIdentifier; 00028 std::string studyName; 00029 00030 std::string rosterLocation; 00031 00032 // At present the roleCollection map is implemented as an STL map 00033 // because this implementation has O(ln n) performance for insert, remove, 00034 // and find, and O(1) for "next". The latter is used to iterate 00035 // over the map, and thus we do not want it to be expensive. 00036 00037 typedef std::map<std::string, Role> RoleMap; 00038 00039 RoleMap roleCollection; 00040 00041 public: 00042 00043 /** 00044 * For iterating over roles in a roster. 00045 */ 00046 typedef RoleMap::iterator RoleIterator; 00047 typedef RoleMap::const_iterator RoleConstIterator; 00048 00049 00050 // Constructors 00051 00052 /** 00053 * Initializes a newly created <code>Roster</code> object with default 00054 * attributes. 00055 */ 00056 Roster(); 00057 00058 /** 00059 * Initializes a newly created <code>Roster</code> object with attributes 00060 * specified by the input parameters. 00061 * 00062 * @param studyIdentifier the identifier of the study the roster is for. 00063 * @param studyName the name of the study the roster is for. 00064 */ 00065 Roster(const std::string &studyIdentifier, const std::string &studyName); 00066 00067 00068 // Equality operators 00069 00070 /** 00071 * Equality operator - compare two <code>Roster</code> for equality. 00072 * 00073 * @param rhs the righthand side of the equality. 00074 * 00075 * @return <code>true</code> if and only if <code>this</code> 00076 * <code>Roster</code> and the righthand side 00077 * <code>Roster</code> are identically equal. 00078 */ 00079 bool operator==(const Roster &rhs) const; 00080 00081 /** 00082 * Inequality operator - compare two <code>Roster</code> for inequality. 00083 * 00084 * @param rhs the righthand side of the inequality. 00085 * 00086 * @return <code>true</code> if and only if <code>this</code> 00087 * <code>Roster</code> and the righthand side 00088 * <code>Roster</code> are not identically equal. 00089 */ 00090 bool operator!=(const Roster &rhs) const; 00091 00092 00093 // Setters and getters 00094 00095 /** 00096 * Set the study identifier. 00097 * 00098 * @param id the identifier of the study to which the roster belongs. 00099 * May be null. 00100 */ 00101 void setStudyIdentifier(const std::string &id); 00102 00103 /** 00104 * Return the study identifier. 00105 * 00106 * @return the identifier of the study to which the roster belongs. 00107 * May be null. 00108 */ 00109 std::string getStudyIdentifier() const; 00110 00111 /** 00112 * Set the study name. 00113 * 00114 * @param name the name of the study to which the roster belongs. 00115 * May be null. 00116 */ 00117 void setStudyName(const std::string &name); 00118 00119 /** 00120 * Return the study name. 00121 * 00122 * @return the name of the study to which the roster belongs. May be null. 00123 */ 00124 std::string getStudyName() const; 00125 00126 /** 00127 * Set the roster location. 00128 * 00129 * @param loc the location to assign to this roster. May be null. 00130 */ 00131 void setRosterLocation(const std::string &loc); 00132 00133 /** 00134 * Return the roster location. 00135 * 00136 * @return the location of this roster. May be null. 00137 */ 00138 std::string getRosterLocation() const; 00139 00140 // Access to the role collection 00141 // 00142 // That a map is used to implement the role collection is hidden 00143 // from the Roster client, as much as this makes sense. 00144 00145 /** 00146 * Add a role to the roster. In all cases the <code>Role</code> parameter 00147 * is added to the roster. The return value distinguishes two 00148 * possibilities. 00149 * 00150 * @param newRole the <code>Role</code> to add to the roster. 00151 * @param oldRole where to save an existing role with the same user 00152 * id as newRole. 00153 * 00154 * @return <code>true</code> means there was no role already in the 00155 * roster with the same user identifier as newRole. The 00156 * contents of oldRole are unchanged. 00157 * <code>false</code> means there was a role with the same user 00158 * identifier already in the roster, and it has been replaced 00159 * by the newRole. The old role is saved in oldRole. 00160 * In both cases, newRole has been added to the roster. 00161 */ 00162 bool addRole(const Role &newRole, Role &oldRole); 00163 00164 /** 00165 * Add a role to the roster. In all cases the <code>Role</code> parameter 00166 * is added to the roster. The return value distinguishes two 00167 * possibilities. 00168 * 00169 * @param newRole the <code>Role</code> to add to the roster. 00170 * 00171 * @return <code>true</code> means there was no role already in the 00172 * roster with the same user identifier as newRole. 00173 * <code>false</code> means there was a role with the same user 00174 * identifier already in the roster, and it has been replaced 00175 * by the newRole. The old role is no longer available. 00176 * In both cases, newRole has been added to the roster. 00177 */ 00178 bool addRole(const Role &newRole); 00179 00180 /** 00181 * Remove a role from the roster. 00182 * 00183 * @param userIdentifier the user identifier of the <code>Role</code> to 00184 * remove from the roster. 00185 * @return <code>false</code> means there was no role in the roster with 00186 * the user identifier specified by the parameter; the roster 00187 * is left unchanged. 00188 * <code>true</code> means that there was a role in the roster 00189 * with the user identifier specified by the parameter; the 00190 * role has been removed from the roster. 00191 */ 00192 bool removeRole(const std::string &userIdentifier); 00193 00194 /** 00195 * Remove all roles from the roster. After a call of this method, 00196 * the roster is empty, i.e., it contains no roles. 00197 * 00198 */ 00199 void clearRoles(); 00200 00201 /** 00202 * Return a role from the roster. 00203 * 00204 * @param userIdentifier the identifier of the <code>Role</code> to 00205 * get from the roster. 00206 * @param foundRole where to place the found <code>Role</code>. 00207 * 00208 * @return <code>false</code> means there is no role in the roster with 00209 * the user identifier specified by the parameter. In this 00210 * case foundRole is unchanged. 00211 * <code>true</code> means that there is a role in the roster 00212 * with the user identifier specified by the parameter. 00213 * foundRound contains the found role. 00214 */ 00215 bool getRole(const std::string &userIdentifier, Role &foundRole) const; 00216 00217 /** 00218 * Test if a role is in the roster. 00219 * 00220 * @param userIdentifier the identifier of the <code>Role</code> to 00221 * test for. 00222 * @return <code>false</code> means there is no role in the roster with 00223 * the user identifier specified by the parameter. 00224 * <code>true</code> means that there is a role in the roster 00225 * with the user identifier specified by the parameter. 00226 */ 00227 bool containsRole(std::string userIdentifier) const; 00228 00229 /** 00230 * Return the number of roles in the roster. 00231 * 00232 * @return the number of roles in the roster. 00233 */ 00234 int size() const; 00235 00236 /** 00237 * Return <code>true</code> if the roster contains no roles. 00238 * 00239 * @return <code>true</code> if the roster contains no roles. 00240 * <code>false</code> otherwise. 00241 */ 00242 bool isEmpty() const; 00243 00244 /** 00245 * Return an iterator referring to the first role in the roster. This 00246 * method can be used with the end() method to iterate over all roles in 00247 * a roster like this: 00248 * <pre> 00249 * Roster roster; 00250 * ... 00251 * RoleIterator iter; 00252 * 00253 * for (iter = roster.begin(); iter != roster.end(); ++iter) 00254 * { 00255 * Role role = iter->second; 00256 * process role 00257 * } 00258 * </pre> 00259 * 00260 * @return an iterator referring to the first role in the roster. 00261 */ 00262 RoleIterator begin(); 00263 RoleConstIterator begin() const; 00264 00265 /** 00266 * Return an iterator referring to the past-the-end role in the roster. 00267 * See begin() for an example of how to use end() to iterate over roles. 00268 * 00269 * @return an iterator referring to the past-the-end role in the roster. 00270 */ 00271 RoleIterator end(); 00272 RoleConstIterator end() const; 00273 00274 00275 // Utility 00276 00277 /** 00278 * Return a string representation of this <code>Roster</code>. Note that 00279 * for a role in the roster only the role identifier is represented 00280 * as a string, not the entire role. 00281 * 00282 * @return the string representation of this <code>Roster</code>. 00283 */ 00284 std::string toString() const; 00285 00286 /** 00287 * Return a string representation of this <code>Roster</code>. Note that 00288 * for a role in the roster only the role identifier is represented 00289 * as a string, not the entire role. 00290 * 00291 * @param showAll specifies if internal data members should be shown. 00292 * @return the string representation of this <code>Roster</code>. 00293 */ 00294 std::string toStringInternal(bool showAll) const; 00295 00296 }; // end class Roster 00297 00298 } // end namespace Yosokumo 00299 00300 #endif // ROSTER_H 00301 00302 // end Roster.h