00001 // YosokumoDIF.h 00002 00003 #ifndef YOSOKUMODIF_H 00004 #define YOSOKUMODIF_H 00005 00006 #include <string> 00007 00008 #include "Block.h" 00009 #include "Catalog.h" 00010 #include "Cell.h" 00011 #include "Message.h" 00012 #include "Panel.h" 00013 #include "Predictor.h" 00014 #include "Role.h" 00015 #include "Roster.h" 00016 #include "ServiceException.h" 00017 #include "Specimen.h" 00018 #include "Study.h" 00019 00020 namespace Yosokumo 00021 { 00022 /** 00023 * Defines methods which transform bytes obtained from HTTP requests into 00024 * Yosokumo C++ objects (such as <code>Catalog</code> and <code>Study</code>) 00025 * and vice versa. Each class implementing this interface handles a different 00026 * DIF, e.g., XML and Google Protocol Buffers. 00027 */ 00028 00029 class YosokumoDIF 00030 { 00031 protected: 00032 ServiceException exception; 00033 00034 public: 00035 00036 YosokumoDIF(); 00037 00038 virtual ~YosokumoDIF(); 00039 00040 /** 00041 * Return a content type string for use in Accept and Content-Type HTTP 00042 * header lines. For example, "application/yosokumo+protobuf". 00043 * 00044 * @return a content type string for use in Accept and other HTTP headers. 00045 */ 00046 virtual std::string getContentType() = 0; 00047 00048 /** 00049 * Test if an exception has occurred. 00050 * 00051 * @return <code>true</code> means there is an exception. 00052 * <code>false</code> means there is no exception. 00053 */ 00054 bool isException(); 00055 00056 /** 00057 * Test if really an exception. 00058 * 00059 * @param e the exception to be tested. 00060 * 00061 * @return <code>true</code> means e is an exception. 00062 * <code>false</code> means e is not an exception. 00063 */ 00064 static bool isException(const ServiceException &e); 00065 00066 /** 00067 * Return a <code>ServiceException</code> from the code-decode process. 00068 * 00069 * @param e if there is an exception, it is placed here. 00070 * 00071 * @return <code>true</code> means there is an exception, and it has been 00072 * placed in e. 00073 * <code>false</code> means there is no exception, e is unchanged. 00074 */ 00075 bool getException(ServiceException &e); 00076 00077 /** 00078 * Clear the exception. 00079 */ 00080 void clearException(); 00081 00082 /** 00083 * Make a Yosokumo <code>Catalog</code> object out of the bytes of an HTTP 00084 * Entity. 00085 * 00086 * @param catalogAsBytes a catalog as bytes from an HTTP Entity. 00087 * @param catalog the output catalog created from the bytes. 00088 * 00089 * @return <code>true</code> means everything worked out fine. 00090 * <code>false</code> means there was a problem; the output 00091 * catalog may be incomplete. Call getException() for details. 00092 */ 00093 virtual bool makeCatalogFromBytes( 00094 const std::vector<uint8_t> &catalogAsBytes, 00095 Catalog &catalog) = 0; 00096 00097 /** 00098 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Catalog</code> 00099 * object. 00100 * 00101 * @param catalog a Yosokumo <code>Catalog</code> object. 00102 * @param catalogAsBytes the output bytes created from the catalog. 00103 * 00104 * @return <code>true</code> means everything worked out fine. 00105 * <code>false</code> means there was a problem; the output 00106 * bytes may be incomplete. Call getException() for details. 00107 */ 00108 virtual bool makeBytesFromCatalog( 00109 const Catalog &catalog, 00110 std::vector<uint8_t> &catalogAsBytes) = 0; 00111 00112 /** 00113 * Make a Yosokumo <code>Study</code> object out of the bytes of an HTTP 00114 * Entity. 00115 * 00116 * @param studyAsBytes a study as bytes from an HTTP Entity. 00117 * @param study the output study created from the bytes. 00118 * 00119 * @return <code>true</code> means everything worked out fine. 00120 * <code>false</code> means there was a problem; the output 00121 * study may be incomplete. Call getException() for details. 00122 */ 00123 virtual bool makeStudyFromBytes( 00124 const std::vector<uint8_t> &studyAsBytes, 00125 Study &study) = 0; 00126 00127 /** 00128 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Study</code> 00129 * object. 00130 * 00131 * @param study a Yosokumo <code>Study</code> object. 00132 * @param studyAsBytes the output bytes created from the study. 00133 * 00134 * @return <code>true</code> means everything worked out fine. 00135 * <code>false</code> means there was a problem; the output 00136 * bytes may be incomplete. Call getException() for details. 00137 */ 00138 virtual bool makeBytesFromStudy( 00139 const Study &study, 00140 std::vector<uint8_t> &studyAsBytes) = 0; 00141 00142 /** 00143 * Make a Yosokumo <code>Study</code> name out of the bytes of an HTTP 00144 * Entity. 00145 * 00146 * @param studyNameAsBytes a study name as bytes from an HTTP Entity. 00147 * @param name the output study name created from the bytes. 00148 * 00149 * @return <code>true</code> means everything worked out fine. 00150 * <code>false</code> means there was a problem; the output study 00151 * name may be incomplete. Call getException() for details. 00152 */ 00153 virtual bool makeStudyNameFromBytes( 00154 const std::vector<uint8_t> &studyNameAsBytes, 00155 std::string &name) = 0; 00156 00157 /** 00158 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Study</code> 00159 * name. 00160 * 00161 * @param name a Yosokumo <code>Study</code> name. 00162 * @param studyNameAsBytes the output bytes created from the study name. 00163 * 00164 * @return <code>true</code> means everything worked out fine. 00165 * <code>false</code> means there was a problem; the output 00166 * bytes may be incomplete. Call getException() for details. 00167 */ 00168 virtual bool makeBytesFromStudyName( 00169 const std::string &name, 00170 std::vector<uint8_t> &studyNameAsBytes) = 0; 00171 00172 /** 00173 * Make a Yosokumo <code>Study</code> status out of the bytes of an HTTP 00174 * Entity. 00175 * 00176 * @param studyStatusAsBytes a study status as bytes from an HTTP Entity. 00177 * @param status the output study status created from the bytes. 00178 * 00179 * @return <code>true</code> means everything worked out fine. 00180 * <code>false</code> means there was a problem; the output study 00181 * status may be incomplete. Call getException() for details. 00182 */ 00183 virtual bool makeStudyStatusFromBytes( 00184 const std::vector<uint8_t> &studyStatusAsBytes, 00185 Study::Status &status) = 0; 00186 00187 /** 00188 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Study</code> 00189 * status. 00190 * 00191 * @param status a Yosokumo <code>Study</code> status. 00192 * @param studyStatusAsBytes the output bytes created from the study status. 00193 * 00194 * @return <code>true</code> means everything worked out fine. 00195 * <code>false</code> means there was a problem; the output 00196 * bytes may be incomplete. Call getException() for details. 00197 */ 00198 virtual bool makeBytesFromStudyStatus( 00199 const Study::Status status, 00200 std::vector<uint8_t> &studyStatusAsBytes) = 0; 00201 00202 /** 00203 * Make a Yosokumo <code>Study</code> visibility out of the bytes of an 00204 * HTTP Entity. 00205 * 00206 * @param studyVisibilityAsBytes a study visibility as bytes from an 00207 * HTTP Entity. 00208 * @param visibility the output study visibility created from the bytes. 00209 * 00210 * @return <code>true</code> means everything worked out fine. 00211 * <code>false</code> means there was a problem; the output study 00212 * visibility may be incomplete. Call getException() for details. 00213 */ 00214 virtual bool makeStudyVisibilityFromBytes( 00215 const std::vector<uint8_t> &studyVisibilityAsBytes, 00216 Study::Visibility &visibility) = 0; 00217 00218 /** 00219 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Study</code> 00220 * visibility. 00221 * 00222 * @param visibility a Yosokumo <code>Study</code> visibility. 00223 * @param studyVisibilityAsBytes the output bytes created from the study 00224 * visibility. 00225 */ 00226 virtual bool makeBytesFromStudyVisibility( 00227 const Study::Visibility visibility, 00228 std::vector<uint8_t> &studyVisibilityAsBytes) = 0; 00229 00230 00231 /** 00232 * Make a Yosokumo <code>Panel</code> object out of the bytes of an HTTP 00233 * Entity. 00234 * 00235 * @param panelAsBytes a panel as bytes from an HTTP Entity. 00236 * @param panel the output panel created from the bytes. 00237 * 00238 * @return <code>true</code> means everything worked out fine. 00239 * <code>false</code> means there was a problem; the output 00240 * panel may be incomplete. Call getException() for details. 00241 */ 00242 virtual bool makePanelFromBytes( 00243 const std::vector<uint8_t> &panelAsBytes, 00244 Panel &panel) = 0; 00245 00246 /** 00247 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Panel</code> 00248 * object. 00249 * 00250 * @param panel a Yosokumo <code>Panel</code> object. 00251 * @param panelAsBytes the output bytes created from the panel. 00252 * 00253 * @return <code>true</code> means everything worked out fine. 00254 * <code>false</code> means there was a problem; the output 00255 * bytes may be incomplete. Call getException() for details. 00256 */ 00257 virtual bool makeBytesFromPanel( 00258 const Panel &panel, 00259 std::vector<uint8_t> &panelAsBytes) = 0; 00260 00261 /** 00262 * Make a Yosokumo <code>Role</code> object out of the bytes of an HTTP 00263 * Entity. 00264 * 00265 * @param roleAsBytes a role as bytes from an HTTP Entity. 00266 * @param role the output role created from the bytes. 00267 * 00268 * @return <code>true</code> means everything worked out fine. 00269 * <code>false</code> means there was a problem; the output 00270 * role may be incomplete. Call getException() for details. 00271 */ 00272 virtual bool makeRoleFromBytes( 00273 const std::vector<uint8_t> &roleAsBytes, 00274 Role &role) = 0; 00275 00276 /** 00277 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Role</code> 00278 * object. 00279 * 00280 * @param role a Yosokumo <code>Role</code> object. 00281 * @param roleAsBytes the output bytes created from the role. 00282 * 00283 * @return <code>true</code> means everything worked out fine. 00284 * <code>false</code> means there was a problem; the output 00285 * bytes may be incomplete. Call getException() for details. 00286 */ 00287 virtual bool makeBytesFromRole( 00288 const Role &role, 00289 std::vector<uint8_t> &roleAsBytes) = 0; 00290 00291 /** 00292 * Make a Yosokumo <code>Roster</code> object out of the bytes of an HTTP 00293 * Entity. 00294 * 00295 * @param rosterAsBytes a roster as bytes from an HTTP Entity. 00296 * @param roster the output roster created from the bytes. 00297 * 00298 * @return <code>true</code> means everything worked out fine. 00299 * <code>false</code> means there was a problem; the output 00300 * roster may be incomplete. Call getException() for details. 00301 */ 00302 virtual bool makeRosterFromBytes( 00303 const std::vector<uint8_t> &rosterAsBytes, 00304 Roster &roster) = 0; 00305 00306 /** 00307 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Roster</code> 00308 * object. 00309 * 00310 * @param roster a Yosokumo <code>Roster</code> object. 00311 * @param rosterAsBytes the output bytes created from the roster. 00312 * 00313 * @return <code>true</code> means everything worked out fine. 00314 * <code>false</code> means there was a problem; the output 00315 * bytes may be incomplete. Call getException() for details. 00316 */ 00317 virtual bool makeBytesFromRoster( 00318 const Roster &roster, 00319 std::vector<uint8_t> &rosterAsBytes) = 0; 00320 00321 /** 00322 * Make a Yosokumo <code>Predictor</code> object out of the bytes of an 00323 * HTTP Entity. 00324 * 00325 * @param predictorAsBytes a predictor as bytes from an HTTP Entity. 00326 * @param predictor the output predictor created from the bytes. 00327 * 00328 * @return <code>true</code> means everything worked out fine. 00329 * <code>false</code> means there was a problem; the output 00330 * predictor may be incomplete. Call getException() for details. 00331 */ 00332 virtual bool makePredictorFromBytes( 00333 const std::vector<uint8_t> &predictorAsBytes, 00334 Predictor &predictor) = 0; 00335 00336 /** 00337 * Make the bytes for an HTTP Entity out of a Yosokumo 00338 * <code>Predictor</code> object. 00339 * 00340 * @param predictor a Yosokumo <code>Predictor</code> object. 00341 * @param predictorAsBytes the output bytes created from the predictor. 00342 * 00343 * @return <code>true</code> means everything worked out fine. 00344 * <code>false</code> means there was a problem; the output 00345 * bytes may be incomplete. Call getException() for details. 00346 */ 00347 virtual bool makeBytesFromPredictor( 00348 const Predictor &predictor, 00349 std::vector<uint8_t> &predictorAsBytes) = 0; 00350 00351 /** 00352 * Make a Yosokumo <code>Cell</code> object out of the bytes of an 00353 * HTTP Entity. 00354 * 00355 * @param cellAsBytes a cell as bytes from an HTTP Entity. 00356 * @param cell the output cell created from the bytes. 00357 * 00358 * @return <code>true</code> means everything worked out fine. 00359 * <code>false</code> means there was a problem; the output 00360 * cell may be incomplete. Call getException() for details. 00361 */ 00362 virtual bool makeCellFromBytes( 00363 const std::vector<uint8_t> &cellAsBytes, 00364 Cell &cell) = 0; 00365 00366 /** 00367 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Cell</code> 00368 * object. 00369 * 00370 * @param cell a Yosokumo <code>Cell</code> object. 00371 * @param cellAsBytes the output bytes created from the cell. 00372 * 00373 * @return <code>true</code> means everything worked out fine. 00374 * <code>false</code> means there was a problem; the output 00375 * bytes may be incomplete. Call getException() for details. 00376 */ 00377 virtual bool makeBytesFromCell( 00378 const Cell &cell, 00379 std::vector<uint8_t> &cellAsBytes) = 0; 00380 00381 /** 00382 * Make a Yosokumo <code>Specimen</code> object out of the bytes of an 00383 * HTTP Entity. 00384 * 00385 * @param specimenAsBytes a specimen as bytes from an HTTP Entity. 00386 * @param specimen the output specimen created from the bytes. 00387 * 00388 * @return <code>true</code> means everything worked out fine. 00389 * <code>false</code> means there was a problem; the output 00390 * specimen may be incomplete. Call getException() for details. 00391 */ 00392 virtual bool makeSpecimenFromBytes( 00393 const std::vector<uint8_t> &specimenAsBytes, 00394 Specimen &specimen) = 0; 00395 00396 /** 00397 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Specimen</code> 00398 * object. 00399 * 00400 * @param specimen a Yosokumo <code>Specimen</code> object. 00401 * @param specimenAsBytes the output bytes created from the specimen. 00402 * 00403 * @return <code>true</code> means everything worked out fine. 00404 * <code>false</code> means there was a problem; the output 00405 * bytes may be incomplete. Call getException() for details. 00406 */ 00407 virtual bool makeBytesFromSpecimen( 00408 const Specimen &specimen, 00409 std::vector<uint8_t> &specimenAsBytes) = 0; 00410 00411 /** 00412 * Make a Yosokumo <code>Block</code> object out of the bytes of an 00413 * HTTP Entity. 00414 * 00415 * @param blockAsBytes a block as bytes from an HTTP Entity. 00416 * @param block the output block created from the bytes. 00417 * 00418 * @return <code>true</code> means everything worked out fine. 00419 * <code>false</code> means there was a problem; the output 00420 * block may be incomplete. Call getException() for details. 00421 */ 00422 virtual bool makeBlockFromBytes( 00423 const std::vector<uint8_t> &blockAsBytes, 00424 Block &block) = 0; 00425 00426 /** 00427 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Block</code> 00428 * object. 00429 * 00430 * @param block a Yosokumo <code>Block</code> object. 00431 * @param blockAsBytes the output bytes created from the block. 00432 * 00433 * @return <code>true</code> means everything worked out fine. 00434 * <code>false</code> means there was a problem; the output 00435 * bytes may be incomplete. Call getException() for details. 00436 */ 00437 virtual bool makeBytesFromBlock( 00438 const Block &block, 00439 std::vector<uint8_t> &blockAsBytes) = 0; 00440 00441 00442 /** 00443 * Make a Yosokumo <code>Message</code> object out of the bytes of an HTTP 00444 * Entity. 00445 * 00446 * @param messageAsBytes a message as bytes from an HTTP Entity. 00447 * @param message the output message created from the bytes. 00448 */ 00449 virtual bool makeMessageFromBytes( 00450 const std::vector<uint8_t> &messageAsBytes, 00451 Message &message) = 0; 00452 00453 /** 00454 * Make the bytes for an HTTP Entity out of a Yosokumo <code>Message</code> 00455 * object. 00456 * 00457 * @param message a Yosokumo <code>Message</code> object. 00458 * @param messageAsBytes the output bytes created from the message. 00459 * 00460 * @return <code>true</code> means everything worked out fine. 00461 * <code>false</code> means there was a problem; the output 00462 * bytes may be incomplete. Call getException() for details. 00463 */ 00464 virtual bool makeBytesFromMessage( 00465 const Message &message, 00466 std::vector<uint8_t> &messageAsBytes) = 0; 00467 00468 }; // end class YosokumoDIF 00469 00470 } // end namespace Yosokumo 00471 00472 #endif // YOSOKUMODIF_H 00473 00474 // end YosokumoDIF.h