00001 // YosokumoRequest.h 00002 00003 #ifndef YOSOKUMOREQUEST_H 00004 #define YOSOKUMOREQUEST_H 00005 00006 #include "YosokumoDIF.h" 00007 #include "Credentials.h" 00008 00009 #include <vector> 00010 00011 namespace Yosokumo 00012 { 00013 /** 00014 * Implements all HTTP requests to the Yosokumo web service. These are the 00015 * basic methods: 00016 * <ul> 00017 * <li>getFromServer() 00018 * <li>postToServer() 00019 * <li>deleteFromServer() 00020 * <li>putToServer() 00021 * </ul> 00022 * These above methods all return false in case of a problem. The caller can 00023 * then use these methods to determine the cause of the failure: 00024 * <ul> 00025 * <li>getStatusCode() 00026 * <li>getEntity() 00027 * <li>isException() 00028 * <li>getException() 00029 * </ul> 00030 * @author Roger House 00031 * @version 0.9 00032 */ 00033 00034 class YosokumoRequest 00035 { 00036 private: 00037 bool trace; // Set true to get debug trace 00038 00039 Credentials credentials; 00040 std::string hostName; 00041 int port; 00042 std::string contentType; 00043 00044 std::string auxHeaderName; // Auxiliary header name 00045 std::string auxHeaderValue; // and value 00046 00047 int statusCode; 00048 std::vector<uint8_t> entity; 00049 ServiceException exception; 00050 00051 static std::vector<uint8_t> emptyEntity; // Only used as default value 00052 00053 public: 00054 /** 00055 * Initializes a newly created <code>YosokumoRequest</code> object with 00056 * attributes specified by the input parameters. 00057 * 00058 * @param credentials specifies user id and key for authentication. 00059 * @param hostName is the name of the Yosokumo server. 00060 * @param port is the port to use to access the Yosokumo service. 00061 * @param contentType is the content type to use in HTTP communications 00062 * with the Yosokumo server (e.g., application/yosokumo+protobuf). 00063 */ 00064 YosokumoRequest( 00065 const Credentials &credentials, 00066 const std::string &hostName, 00067 int port, 00068 const std::string &contentType); 00069 00070 /** 00071 * Initialize for an HTTP operation. Init various data fields to prepare 00072 * for execution of a service request. 00073 */ 00074 void initForOperation(); 00075 00076 /** 00077 * Set the credentials. 00078 * 00079 * @param credentials to use in HTTP communications to authorize the 00080 * user on the Yokosumo server. 00081 */ 00082 void setCredentials(Credentials credentials); 00083 00084 /** 00085 * Set the auxiliary header. Some HTTP requests use an auxiliary header 00086 * such as "x-yosokumo-full-entries: on" for Get Catalog. 00087 * 00088 * @param name is the name of the auxiliary header, e.g., 00089 * "x-yosokumo-full-entries". 00090 * @param value is the value of the auxiliary header, e.g., "on". 00091 */ 00092 void setAuxHeader(const std::string &name, const std::string &value); 00093 00094 /** 00095 * Set the trace flag. When trace is on, text is written to cout 00096 * showing the progress of HTTP requests and reponses. 00097 * 00098 * @param traceOn is the value to assign to the trace flag. 00099 */ 00100 void setTrace(bool traceOn); 00101 00102 /** 00103 * Return the trace flag. 00104 * 00105 * @return the current setting of the trace flag. 00106 */ 00107 bool getTrace(); 00108 00109 /** 00110 * Return the status code from an HTTP response. 00111 * 00112 * @return the status code from an HTTP response. 00113 */ 00114 int getStatusCode(); 00115 00116 /** 00117 * Get the entity from an HTTP response. 00118 * 00119 * @param putEntityHere specifies where to store the entity from 00120 * an HTTP response. 00121 */ 00122 void getEntity(std::vector<uint8_t> &putEntityHere); 00123 00124 /** 00125 * Test if an exception has occurred. 00126 * 00127 * @return <code>true</code> means there is an exception. 00128 * <code>false</code> means there is no exception. 00129 */ 00130 bool isException(); 00131 00132 /** 00133 * Return the exception from an HTTP process. 00134 * 00135 * @return an exception from an HTTP response. 00136 */ 00137 ServiceException getException(); 00138 00139 /** 00140 * Issue an HTTP GET request. 00141 * 00142 * @param resourceUri is the URI of the resource to get. 00143 * 00144 * @return <code>false</code> means there was a problem (call 00145 * <code>getStatusCode()</code>, <code>getEntity()</code>, and 00146 * <code>getException()</code> for more information). 00147 * <code>true</code> means the request was successful. Call 00148 * <code>getStatusCode()</code> and <code>getEntity()</code> 00149 * to obtain the data returned from the server. 00150 */ 00151 bool getFromServer(const std::string &resourceUri); 00152 00153 /** 00154 * Issue an HTTP POST request. 00155 * 00156 * @param resourceUri is the URI of the resource to post to. 00157 * @param entityToPost is the entity to post to the server. 00158 * 00159 * @return <code>false</code> means there was a problem (call 00160 * <code>getStatusCode()</code>, <code>getEntity()</code>, and 00161 * <code>getException()</code> for more information). 00162 * <code>true</code> means the request was successful. Call 00163 * <code>getStatusCode()</code> and <code>getEntity()</code> 00164 * to obtain the data returned from the server. 00165 */ 00166 bool postToServer( 00167 const std::string &resourceUri, 00168 const std::vector<uint8_t> &entityToPost); 00169 00170 /** 00171 * Issue an HTTP DELETE request. 00172 * 00173 * @param resourceUri is the URI of the resource to delete. 00174 * 00175 * @return <code>false</code> means there was a problem (call 00176 * <code>getStatusCode()</code>, <code>getEntity()</code>, and 00177 * <code>getException()</code> for more information). 00178 * <code>true</code> means the request was successful. Call 00179 * <code>getStatusCode()</code> and <code>getEntity()</code> 00180 * for more information. 00181 */ 00182 bool deleteFromServer(const std::string &resourceUri); 00183 00184 /** 00185 * Issue an HTTP PUT request. 00186 * 00187 * @param resourceUri is the URI where to put the resource. 00188 * @param entityToPut is the entity to put to the server. 00189 * 00190 * @return <code>false</code> means there was a problem (call 00191 * <code>getStatusCode()</code>, <code>getEntity()</code>, and 00192 * <code>getException()</code> for more information). 00193 * <code>true</code> means the request was successful. Call 00194 * <code>getStatusCode()</code> and <code>getEntity()</code> 00195 * for more information. 00196 */ 00197 bool putToServer( 00198 const std::string &resourceUri, 00199 const std::vector<uint8_t> &entityToPut); 00200 00201 //??? Very temporary defs 00202 typedef int HttpRequestBase; 00203 typedef int HttpRequest; 00204 00205 /** 00206 * Make an HTTP request. This is the workhorse method which does all the 00207 * work of making an HTTP request and processing the response. 00208 * 00209 * @param httpRequest is HttpGet, HttpPut, HttpPost, or HttpDelete. 00210 * @param entityToSend is an entity to put to the server. 00211 * @param traceName is the name of the request to be used in trace output. 00212 * 00213 * @return <code>false</code> means there was a problem (call 00214 * <code>getStatusCode()</code>, <code>getEntity()</code>, and 00215 * <code>getException()</code> for more information). 00216 * <code>true</code> means the request was successful. Call 00217 * <code>getStatusCode()</code> and <code>getEntity()</code> 00218 * for more information. 00219 */ 00220 bool makeRequest( 00221 HttpRequestBase httpRequest, 00222 const std::string &traceName, 00223 const std::vector<uint8_t> &entityToSend = emptyEntity); 00224 00225 /** 00226 * Execute an HTTP request and process the response. 00227 * 00228 * @param httpRequest is an HTTP request, ready to be executed 00229 * @param traceName is the name of the request to be used in trace output. 00230 * @return <code>false</code> means there was a problem (call 00231 * <code>getStatusCode()</code>, <code>getEntity()</code>, and 00232 * <code>getException()</code> for more information). 00233 * <code>true</code> means the request was successful. Call 00234 * <code>getStatusCode()</code> and <code>getEntity()</code> 00235 * for more information. 00236 */ 00237 bool getResponse(HttpRequestBase httpRequest, const std::string &traceName); 00238 00239 /** 00240 * Normalize a resource URI. There are several cases: 00241 * <ul> 00242 * <li>The input URI begins with <code>"http://"</code> but the next part of 00243 * the URI is not the host name: Return the URI as is. 00244 * <li>The input URI begins with <code>"http://"</code>+hostname: Return the 00245 * URI with <code>":"+port</code> inserted after the host name. 00246 * <li>The input URI begins with the host name: Return the URI with 00247 * <code>"http://"</code> prepended. 00248 * <li>None of the above: Return the URI with 00249 * <code>"http://"+hostName+":"+port</code> prepended. 00250 * </ul> 00251 * One reason this method exists is that the HttpClient classes HttpGet, 00252 * HttpPost, etc., require that the resource URIs passed to their 00253 * constructors have the <code>"http://"+hostName</code> prefix, despite the 00254 * fact that the HTTP request lines created by these classes strip the 00255 * prefix and use only the resource URI. This normalization method 00256 * allows the programmer to use only the URI, or the fully-prefixed 00257 * URI, whichever is more convenient. 00258 * 00259 * @param resourceUri the input URI to normalize. 00260 * @param hostName the host name to use. 00261 * @param port the port to use. 00262 * 00263 * @return a normalized version of the input URI. 00264 */ 00265 std::string normalizeResourceUri( 00266 const std::string &resourceUri, 00267 const std::string &hostName, 00268 int port); 00269 00270 /** 00271 * Make a digest of an HTTP request. 00272 * 00273 * @param request is the HTTP request to digest. 00274 * @return <code>null</code> means there was a problem; <code>exception</code> 00275 * is set. Otherwise the return value is a digest of the 00276 * input request. 00277 */ 00278 std::string makeDigest(HttpRequestBase request); 00279 00280 /** 00281 * Make a string from an HTTP request. This string is used for Yosokumo 00282 * authentication. 00283 * 00284 * @param r is the input HTTP request. 00285 * @return is a string containing a number of fields from r. 00286 */ 00287 std::string makeRequestString(HttpRequestBase r); 00288 00289 /** 00290 * Append an HTTP header value. This is a helper method for 00291 * makeRequestString. 00292 * 00293 * @param r is the input HTTP request. 00294 * @param headerName is the name of the header whose value is wanted. 00295 * @param s is the string to append the header value to. 00296 */ 00297 void appendHeaderValue( 00298 HttpRequest r, 00299 const std::string &headerName, 00300 std::string &s); 00301 00302 }; // end YosokumoRequest 00303 00304 } // end namespace Yosokumo 00305 00306 #endif // YOSOKUMOREQUEST_H 00307 00308 // end YosokumoRequest.h 00309