00001 // Study.h 00002 00003 #ifndef STUDY_H 00004 #define STUDY_H 00005 00006 #include <stdint.h> 00007 #include <string> 00008 00009 namespace Yosokumo 00010 { 00011 00012 /** 00013 * A container for all resources associated with an analytic project. A 00014 * study has these attributes: 00015 * <ul> 00016 * <li>a study identifier and a study name 00017 * <li>a type, a status, and a visibility 00018 * <li>an identifier and a name of the user who owns the study 00019 * <li>references to the table, model, panel, and roster for the study 00020 * </ul> 00021 * 00022 * @author Roger House 00023 * @version 0.9 00024 */ 00025 class Study 00026 { 00027 public: 00028 00029 /** 00030 * Indicates the quality of the predictands associated with subjects in 00031 * the study. The <code>Type</code> determines the type of the predictive 00032 * model that will be built for the study. The type attribute may not 00033 * be changed after it has been set at study creation. If the type 00034 * attribute is not included in the posted study document, the default 00035 * value is <code>NUMBER</code>. 00036 */ 00037 enum Type 00038 { 00039 /** 00040 * the predictand is categorical and nominal. 00041 */ 00042 CLASS, 00043 /** 00044 * the predictand is categorical, but also ordinal. 00045 */ 00046 RANK, 00047 /** 00048 * the predictand is continuous and ratio. 00049 */ 00050 NUMBER, 00051 /** 00052 * the predictand represents a probability given 00053 * as a continuous value between zero and one inclusive. 00054 */ 00055 CHANCE 00056 }; 00057 00058 /** 00059 * Describes the state of the study, whether it is running, on standby, 00060 * or stopped. The <code>Status</code> can be changed at any time. If the 00061 * status attribute is not included in the posted study document, the 00062 * default status is <code>RUNNING</code>. 00063 */ 00064 enum Status 00065 { 00066 /** 00067 * the service is accepting data into the study's table, analyzing 00068 * the data to improve the study's predictive model and estimating 00069 * predictands based on the model. 00070 */ 00071 RUNNING, 00072 /** 00073 * the service is no longer accepting or analyzing data, but is still 00074 * estimating predictands for the study based on the current model. 00075 */ 00076 STANDBY, 00077 /** 00078 * the service is neither accepting nor analyzing data, and is not 00079 * estimating predictands for the study. 00080 */ 00081 STOPPED 00082 }; 00083 00084 /** 00085 * Tells whether unidentified users can get estimated predictands from 00086 * the model of the study. The visibility of a study can be changed at 00087 * any time. If the visibility is not included in the posted study 00088 * document, the default visibility is <code>PRIVATE</code>. 00089 */ 00090 enum Visibility 00091 { 00092 /** 00093 * only users that are authenticated and authorized may make a Get 00094 * Model request for the study. 00095 */ 00096 PRIVATE, 00097 /** 00098 * any web client may make a Get Model request for the study. 00099 */ 00100 PUBLIC 00101 }; 00102 00103 private: 00104 00105 std::string studyIdentifier; 00106 std::string studyName ; 00107 std::string studyLocation ; 00108 00109 Type type ; 00110 Status status ; 00111 Visibility visibility ; 00112 00113 std::string ownerIdentifier; 00114 std::string ownerName ; 00115 00116 std::string tableLocation ; 00117 std::string modelLocation ; 00118 std::string panelLocation ; 00119 std::string rosterLocation ; 00120 00121 // Panel info 00122 00123 std::string nameControlLocation ; 00124 std::string statusControlLocation ; 00125 std::string visibilityControlLocation; 00126 00127 uint64_t blockCount ; 00128 uint64_t cellCount ; 00129 uint64_t prospectCount; 00130 00131 std::string creationTime ; 00132 std::string latestBlockTime ; 00133 std::string latestProspectTime; 00134 00135 public: 00136 00137 // Constructors 00138 00139 /** 00140 * Initializes a newly created <code>Study</code> object with default 00141 * attributes. 00142 * <ul> 00143 * <li>identifier = "" 00144 * <li>name = "" 00145 * <li>type = NUMBER 00146 * <li>status = RUNNING 00147 * <li>visibility = PRIVATE 00148 * </ul> 00149 * The type of a Study cannot be changed after construction. 00150 */ 00151 Study(); 00152 00153 /** 00154 * Initializes a newly created <code>Study</code> object with attributes 00155 * specified by the input parameters. 00156 * 00157 * @param studyName the name of the study. 00158 * @param type the type of the study. 00159 * @param status the status of the study. 00160 * @param visibility the visibility of the study. 00161 * 00162 * The type of a Study cannot be changed after construction. 00163 */ 00164 Study 00165 ( 00166 const std::string &studyName, 00167 Type type, 00168 Status status, 00169 Visibility visibility 00170 ); 00171 00172 /** 00173 * Copy constructor - initializes a newly created <code>Study</code> 00174 * object with a copy of another <code>Study</code> object. 00175 * 00176 * @param rhs the <code>Study</code> to make a copy of. 00177 */ 00178 Study(const Study &rhs); 00179 00180 00181 /** 00182 * Destructor - destroy a <code>Study</code> object. 00183 */ 00184 virtual ~Study(); 00185 00186 /** 00187 * Assignment operator - assign one <code>Study</code> to another. 00188 * 00189 * @param rhs the righthand side of the assignment. 00190 * 00191 * @return a reference to <code>this</code> Study. 00192 */ 00193 Study& operator=(const Study& rhs); 00194 00195 00196 // Equality operators 00197 00198 /** 00199 * Equality operator - compare two <code>Study</code> for equality. 00200 * 00201 * @param rhs the righthand side of the equality. 00202 * 00203 * @return <code>true</code> if and only if <code>this</code> 00204 * <code>Study</code> and the righthand side 00205 * <code>Study</code> are identically equal. 00206 */ 00207 bool operator==(const Study &rhs) const; 00208 00209 /** 00210 * Inequality operator - compare two <code>Study</code> for inequality. 00211 * 00212 * @param rhs the righthand side of the inequality. 00213 * 00214 * @return <code>true</code> if and only if <code>this</code> 00215 * <code>Study</code> and the righthand side 00216 * <code>Study</code> are not identically equal. 00217 */ 00218 bool operator!=(const Study &rhs) const; 00219 00220 00221 /** 00222 * Initialize the data members of a study. 00223 */ 00224 void initStudy(); 00225 00226 /** 00227 * Make a copy of a study. 00228 * 00229 * @param t the study to copy to (destination). 00230 * @param s the study to copy from (source). 00231 * @return a copy of s. 00232 */ 00233 static void copyStudy(Study &t, const Study &s); 00234 00235 // Setters and getters 00236 00237 /** 00238 * Set the study identifier. 00239 * 00240 * @param id the identifier to assign to this study. This is the 00241 * unique identification of the study. May be null. 00242 */ 00243 void setStudyIdentifier(const std::string &id); 00244 00245 /** 00246 * Return the study identifier. 00247 * 00248 * @return the identifier of this study, which is the unique 00249 * identification of the study. May be null. 00250 */ 00251 std::string getStudyIdentifier() const; 00252 00253 /** 00254 * Set the study name. 00255 * 00256 * @param name the name to assign to this study. May be null. 00257 */ 00258 void setStudyName(const std::string &name); 00259 00260 /** 00261 * Return the study name. 00262 * 00263 * @return the name of this study. May be null. 00264 */ 00265 std::string getStudyName() const; 00266 00267 /** 00268 * Set the study location. 00269 * 00270 * @param loc the location to assign to this study. May be null. 00271 */ 00272 void setStudyLocation(const std::string &loc); 00273 00274 /** 00275 * Return the study location. 00276 * 00277 * @return the location of this study. May be null. 00278 */ 00279 std::string getStudyLocation() const; 00280 00281 /** 00282 * Set the study type. 00283 * 00284 * @param t the type to assign to this study. 00285 */ 00286 void setType(Type t); 00287 00288 /** 00289 * Return the study type. 00290 * 00291 * @return the type of this study. 00292 */ 00293 Type getType() const; 00294 00295 /** 00296 * Set the study status. 00297 * 00298 * @param s the status to assign to this study. 00299 */ 00300 void setStatus(Status s); 00301 00302 /** 00303 * Return the study status. 00304 * 00305 * @return the status of this study. 00306 */ 00307 Status getStatus() const; 00308 00309 /** 00310 * Set the study visibility. 00311 * 00312 * @param v the type to assign to this study. 00313 */ 00314 void setVisibility(Visibility v); 00315 00316 /** 00317 * Return the study visibility. 00318 * 00319 * @return the visibility of this study. 00320 */ 00321 Visibility getVisibility() const; 00322 00323 /** 00324 * Set the owner identifier. 00325 * 00326 * @param id the identifier of the owner of this study. May be null. 00327 */ 00328 void setOwnerIdentifier(const std::string &id); 00329 00330 /** 00331 * Return the owner identifier. 00332 * 00333 * @return the identifier of the owner of this study. May be null. 00334 */ 00335 std::string getOwnerIdentifier() const; 00336 00337 /** 00338 * Set the owner name. 00339 * 00340 * @param name the name to assign to the owner of this study. 00341 * May be null. 00342 */ 00343 void setOwnerName(const std::string &name); 00344 00345 /** 00346 * Return the owner name. 00347 * 00348 * @return the name of the owner of this study. May be null. 00349 */ 00350 std::string getOwnerName() const; 00351 00352 /** 00353 * Set the table location. 00354 * 00355 * @param loc the location of the table for this study. May be null. 00356 */ 00357 void setTableLocation(const std::string &loc); 00358 00359 /** 00360 * Return the table location. 00361 * 00362 * @return the location of the table for this study. May be null. 00363 */ 00364 std::string getTableLocation() const; 00365 00366 /** 00367 * Set the model location. 00368 * 00369 * @param loc the location of the model for this study. May be null. 00370 */ 00371 void setModelLocation(const std::string &loc); 00372 00373 /** 00374 * Return the model location. 00375 * 00376 * @return the location of the model for this study. May be null. 00377 */ 00378 std::string getModelLocation() const; 00379 00380 /** 00381 * Set the panel location. 00382 * 00383 * @param loc the location of the panel for this study. May be null. 00384 */ 00385 void setPanelLocation(const std::string &loc); 00386 00387 /** 00388 * Return the panel location. 00389 * 00390 * @return the location of the panel for this study. May be null. 00391 */ 00392 std::string getPanelLocation() const; 00393 00394 /** 00395 * Set the roster location. 00396 * 00397 * @param loc the location of the roster for this study. May be null. 00398 */ 00399 void setRosterLocation(const std::string &loc); 00400 00401 /** 00402 * Return the roster location. 00403 * 00404 * @return the location of the roster for this study. May be null. 00405 */ 00406 std::string getRosterLocation() const; 00407 00408 // Panel setters and getters 00409 00410 /** 00411 * Set the name control location. 00412 * 00413 * @param nameControlLocation the URI to use to change the 00414 * name of the study. 00415 */ 00416 void setNameControlLocation(const std::string &nameControlLocation); 00417 00418 /** 00419 * Return the name control location. 00420 * 00421 * @return the URI to use to change the name of the study. 00422 */ 00423 std::string getNameControlLocation() const; 00424 00425 00426 /** 00427 * Set the status control location. 00428 * 00429 * @param statusControlLocation the URI to use to change the 00430 * status of the study. 00431 */ 00432 void setStatusControlLocation(const std::string &statusControlLocation); 00433 00434 /** 00435 * Return the status control location. 00436 * 00437 * @return the URI to use to change the status of the study. 00438 */ 00439 std::string getStatusControlLocation() const; 00440 00441 00442 /** 00443 * Set the visibility control location. 00444 * 00445 * @param visibilityControlLocation the URI to use to change the 00446 * visibility of the study. 00447 */ 00448 void setVisibilityControlLocation( 00449 const std::string &visibilityControlLocation); 00450 00451 /** 00452 * Return the visibility control location. 00453 * 00454 * @return the URI to use to change the visibility of the study. 00455 */ 00456 std::string getVisibilityControlLocation() const; 00457 00458 /** 00459 * Set the block count. 00460 * 00461 * @param blockCount the number of posted blocks that have been 00462 * accepted into the study table. 00463 */ 00464 void setBlockCount(uint64_t blockCount); 00465 00466 /** 00467 * Return the block count. 00468 * 00469 * @return the number of posted blocks that have been accepted into 00470 * the study table. 00471 */ 00472 uint64_t getBlockCount() const; 00473 00474 /** 00475 * Set the cell count. 00476 * 00477 * @param cellCount the total number of cells contained in the blocks 00478 * reported in the block count. 00479 */ 00480 void setCellCount(uint64_t cellCount); 00481 00482 /** 00483 * Return the cell count. 00484 * 00485 * @return the total number of cells contained in the blocks reported in 00486 * the block count. 00487 */ 00488 uint64_t getCellCount() const; 00489 00490 /** 00491 * Set the prospect count. 00492 * 00493 * @param prospectCount the total number of specimens contained in 00494 * all Post Model and Get Model requests for 00495 * the study. 00496 */ 00497 void setProspectCount(uint64_t prospectCount); 00498 00499 /** 00500 * Return the prospect count. 00501 * 00502 * @return the total number of specimens contained in all Post Model 00503 * and Get Model requests for the study. 00504 */ 00505 uint64_t getProspectCount() const; 00506 00507 /** 00508 * Set the creation time. 00509 * 00510 * @param creationTime the UTC time the study was created. 00511 */ 00512 void setCreationTime(const std::string &creationTime); 00513 00514 /** 00515 * Return the creation time. 00516 * 00517 * @return the UTC time the study was created. 00518 */ 00519 std::string getCreationTime() const; 00520 00521 /** 00522 * Set the latest block time. 00523 * 00524 * @param latestBlockTime the UTC time that the service accepted 00525 * the most recent block into the study table. 00526 */ 00527 void setLatestBlockTime(const std::string &latestBlockTime); 00528 00529 /** 00530 * Return the latest block time. 00531 * 00532 * @return the UTC time that the service accepted the most recent block 00533 * into the study table. 00534 */ 00535 std::string getLatestBlockTime() const; 00536 00537 /** 00538 * Set the latest prospect time. 00539 * 00540 * @param latestProspectTime the UTC time of the most recent Post 00541 * Model or Get Model request. 00542 */ 00543 void setLatestProspectTime(const std::string &latestProspectTime); 00544 00545 /** 00546 * Return the latest prospect time. 00547 * 00548 * @return the UTC time of the most recent Post Model or Get Model request. 00549 */ 00550 std::string getLatestProspectTime() const; 00551 00552 // Utility 00553 00554 /** 00555 * Return a string representation of this <code>Study</code>. 00556 * 00557 * @return the string representation of this <code>Study</code>. 00558 */ 00559 std::string toString(); 00560 00561 }; // end class Study 00562 00563 } // end namespace Yosokumo 00564 00565 #endif // STUDY_H 00566 00567 // end Study.h