Yosokumo::YosokumoRequest Class Reference

Implements all HTTP requests to the Yosokumo web service. More...

#include <YosokumoRequest.h>

Collaboration diagram for Yosokumo::YosokumoRequest:
Collaboration graph
[legend]

List of all members.

Public Types

typedef int HttpRequestBase
typedef int HttpRequest

Public Member Functions

 YosokumoRequest (const Credentials &credentials, const std::string &hostName, int port, const std::string &contentType)
 Initializes a newly created YosokumoRequest object with attributes specified by the input parameters.
void initForOperation ()
 Initialize for an HTTP operation.
void setCredentials (Credentials credentials)
 Set the credentials.
void setAuxHeader (const std::string &name, const std::string &value)
 Set the auxiliary header.
void setTrace (bool traceOn)
 Set the trace flag.
bool getTrace ()
 Return the trace flag.
int getStatusCode ()
 Return the status code from an HTTP response.
void getEntity (std::vector< uint8_t > &putEntityHere)
 Get the entity from an HTTP response.
bool isException ()
 Test if an exception has occurred.
ServiceException getException ()
 Return the exception from an HTTP process.
bool getFromServer (const std::string &resourceUri)
 Issue an HTTP GET request.
bool postToServer (const std::string &resourceUri, const std::vector< uint8_t > &entityToPost)
 Issue an HTTP POST request.
bool deleteFromServer (const std::string &resourceUri)
 Issue an HTTP DELETE request.
bool putToServer (const std::string &resourceUri, const std::vector< uint8_t > &entityToPut)
 Issue an HTTP PUT request.
bool makeRequest (HttpRequestBase httpRequest, const std::string &traceName, const std::vector< uint8_t > &entityToSend=emptyEntity)
 Make an HTTP request.
bool getResponse (HttpRequestBase httpRequest, const std::string &traceName)
 Execute an HTTP request and process the response.
std::string normalizeResourceUri (const std::string &resourceUri, const std::string &hostName, int port)
 Normalize a resource URI.
std::string makeDigest (HttpRequestBase request)
 Make a digest of an HTTP request.
std::string makeRequestString (HttpRequestBase r)
 Make a string from an HTTP request.
void appendHeaderValue (HttpRequest r, const std::string &headerName, std::string &s)
 Append an HTTP header value.

Private Attributes

bool trace
Credentials credentials
std::string hostName
int port
std::string contentType
std::string auxHeaderName
std::string auxHeaderValue
int statusCode
std::vector< uint8_t > entity
ServiceException exception

Static Private Attributes

static std::vector< uint8_t > emptyEntity

Detailed Description

Implements all HTTP requests to the Yosokumo web service.

These are the basic methods:

These above methods all return false in case of a problem. The caller can then use these methods to determine the cause of the failure:

Author:
Roger House
Version:
0.9

Definition at line 34 of file YosokumoRequest.h.


Member Typedef Documentation

Definition at line 203 of file YosokumoRequest.h.

Definition at line 202 of file YosokumoRequest.h.


Constructor & Destructor Documentation

YosokumoRequest::YosokumoRequest ( const Credentials credentials,
const std::string &  hostName,
int  port,
const std::string &  contentType 
)

Initializes a newly created YosokumoRequest object with attributes specified by the input parameters.

Parameters:
credentials specifies user id and key for authentication.
hostName is the name of the Yosokumo server.
port is the port to use to access the Yosokumo service.
contentType is the content type to use in HTTP communications with the Yosokumo server (e.g., application/yosokumo+protobuf).

Definition at line 11 of file YosokumoRequest.cpp.

References emptyEntity, initForOperation(), and trace.


Member Function Documentation

void YosokumoRequest::appendHeaderValue ( HttpRequest  r,
const std::string &  headerName,
std::string &  s 
)

Append an HTTP header value.

This is a helper method for makeRequestString.

Parameters:
r is the input HTTP request.
headerName is the name of the header whose value is wanted.
s is the string to append the header value to.

Definition at line 373 of file YosokumoRequest.cpp.

Referenced by makeRequestString().

bool YosokumoRequest::deleteFromServer ( const std::string &  resourceUri  ) 

Issue an HTTP DELETE request.

Parameters:
resourceUri is the URI of the resource to delete.
Returns:
false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() for more information.

Definition at line 100 of file YosokumoRequest.cpp.

References hostName, makeRequest(), normalizeResourceUri(), and port.

void YosokumoRequest::getEntity ( std::vector< uint8_t > &  putEntityHere  ) 

Get the entity from an HTTP response.

Parameters:
putEntityHere specifies where to store the entity from an HTTP response.

Definition at line 66 of file YosokumoRequest.cpp.

References entity.

ServiceException YosokumoRequest::getException (  ) 

Return the exception from an HTTP process.

Returns:
an exception from an HTTP response.

Definition at line 76 of file YosokumoRequest.cpp.

References exception.

bool YosokumoRequest::getFromServer ( const std::string &  resourceUri  ) 

Issue an HTTP GET request.

Parameters:
resourceUri is the URI of the resource to get.
Returns:
false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() to obtain the data returned from the server.

Definition at line 83 of file YosokumoRequest.cpp.

References hostName, makeRequest(), normalizeResourceUri(), and port.

bool YosokumoRequest::getResponse ( HttpRequestBase  httpRequest,
const std::string &  traceName 
)

Execute an HTTP request and process the response.

Parameters:
httpRequest is an HTTP request, ready to be executed
traceName is the name of the request to be used in trace output.
Returns:
false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() for more information.

Definition at line 194 of file YosokumoRequest.cpp.

References entity, exception, statusCode, and trace.

Referenced by makeRequest().

int YosokumoRequest::getStatusCode (  ) 

Return the status code from an HTTP response.

Returns:
the status code from an HTTP response.

Definition at line 61 of file YosokumoRequest.cpp.

References statusCode.

bool YosokumoRequest::getTrace (  ) 

Return the trace flag.

Returns:
the current setting of the trace flag.

Definition at line 56 of file YosokumoRequest.cpp.

References trace.

void YosokumoRequest::initForOperation (  ) 

Initialize for an HTTP operation.

Init various data fields to prepare for execution of a service request.

Definition at line 29 of file YosokumoRequest.cpp.

References auxHeaderName, auxHeaderValue, entity, exception, and statusCode.

Referenced by YosokumoRequest().

bool YosokumoRequest::isException (  ) 

Test if an exception has occurred.

Returns:
true means there is an exception. false means there is no exception.

Definition at line 71 of file YosokumoRequest.cpp.

References exception.

std::string YosokumoRequest::makeDigest ( HttpRequestBase  request  ) 

Make a digest of an HTTP request.

Parameters:
request is the HTTP request to digest.
Returns:
null means there was a problem; exception is set. Otherwise the return value is a digest of the input request.

Definition at line 326 of file YosokumoRequest.cpp.

References credentials, exception, Yosokumo::Credentials::getKey(), makeRequestString(), and trace.

Referenced by makeRequest().

bool YosokumoRequest::makeRequest ( HttpRequestBase  httpRequest,
const std::string &  traceName,
const std::vector< uint8_t > &  entityToSend = emptyEntity 
)

Make an HTTP request.

This is the workhorse method which does all the work of making an HTTP request and processing the response.

Parameters:
httpRequest is HttpGet, HttpPut, HttpPost, or HttpDelete.
entityToSend is an entity to put to the server.
traceName is the name of the request to be used in trace output.
Returns:
false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() for more information.

Definition at line 120 of file YosokumoRequest.cpp.

References auxHeaderName, auxHeaderValue, contentType, credentials, entity, exception, getResponse(), Yosokumo::Credentials::getUserId(), hostName, makeDigest(), statusCode, Yosokumo::Credentials::toString(), and trace.

Referenced by deleteFromServer(), getFromServer(), postToServer(), and putToServer().

std::string YosokumoRequest::makeRequestString ( HttpRequestBase  r  ) 

Make a string from an HTTP request.

This string is used for Yosokumo authentication.

Parameters:
r is the input HTTP request.
Returns:
is a string containing a number of fields from r.

Definition at line 353 of file YosokumoRequest.cpp.

References appendHeaderValue().

Referenced by makeDigest().

std::string YosokumoRequest::normalizeResourceUri ( const std::string &  resourceUri,
const std::string &  hostName,
int  port 
)

Normalize a resource URI.

There are several cases:

  • The input URI begins with "http://" but the next part of the URI is not the host name: Return the URI as is.
  • The input URI begins with "http://"+hostname: Return the URI with ":"+port inserted after the host name.
  • The input URI begins with the host name: Return the URI with "http://" prepended.
  • None of the above: Return the URI with "http://"+hostName+":"+port prepended.

One reason this method exists is that the HttpClient classes HttpGet, HttpPost, etc., require that the resource URIs passed to their constructors have the "http://"+hostName prefix, despite the fact that the HTTP request lines created by these classes strip the prefix and use only the resource URI. This normalization method allows the programmer to use only the URI, or the fully-prefixed URI, whichever is more convenient.

Parameters:
resourceUri the input URI to normalize.
hostName the host name to use.
port the port to use.
Returns:
a normalized version of the input URI.

Definition at line 295 of file YosokumoRequest.cpp.

References Yosokumo::startsWith().

Referenced by deleteFromServer(), getFromServer(), postToServer(), and putToServer().

bool YosokumoRequest::postToServer ( const std::string &  resourceUri,
const std::vector< uint8_t > &  entityToPost 
)

Issue an HTTP POST request.

Parameters:
resourceUri is the URI of the resource to post to.
entityToPost is the entity to post to the server.
Returns:
false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() to obtain the data returned from the server.

Definition at line 91 of file YosokumoRequest.cpp.

References hostName, makeRequest(), normalizeResourceUri(), and port.

bool YosokumoRequest::putToServer ( const std::string &  resourceUri,
const std::vector< uint8_t > &  entityToPut 
)

Issue an HTTP PUT request.

Parameters:
resourceUri is the URI where to put the resource.
entityToPut is the entity to put to the server.
Returns:
false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() for more information.

Definition at line 108 of file YosokumoRequest.cpp.

References hostName, makeRequest(), normalizeResourceUri(), and port.

void YosokumoRequest::setAuxHeader ( const std::string &  name,
const std::string &  value 
)

Set the auxiliary header.

Some HTTP requests use an auxiliary header such as "x-yosokumo-full-entries: on" for Get Catalog.

Parameters:
name is the name of the auxiliary header, e.g., "x-yosokumo-full-entries".
value is the value of the auxiliary header, e.g., "on".

Definition at line 43 of file YosokumoRequest.cpp.

References auxHeaderName, and auxHeaderValue.

void YosokumoRequest::setCredentials ( Credentials  credentials  ) 

Set the credentials.

Parameters:
credentials to use in HTTP communications to authorize the user on the Yokosumo server.

Definition at line 38 of file YosokumoRequest.cpp.

void YosokumoRequest::setTrace ( bool  traceOn  ) 

Set the trace flag.

When trace is on, text is written to cout showing the progress of HTTP requests and reponses.

Parameters:
traceOn is the value to assign to the trace flag.

Definition at line 51 of file YosokumoRequest.cpp.

References trace.


Member Data Documentation

Definition at line 44 of file YosokumoRequest.h.

Referenced by initForOperation(), makeRequest(), and setAuxHeader().

Definition at line 45 of file YosokumoRequest.h.

Referenced by initForOperation(), makeRequest(), and setAuxHeader().

Definition at line 42 of file YosokumoRequest.h.

Referenced by makeRequest().

Definition at line 39 of file YosokumoRequest.h.

Referenced by makeDigest(), and makeRequest().

std::vector< uint8_t > YosokumoRequest::emptyEntity [static, private]

Definition at line 51 of file YosokumoRequest.h.

Referenced by YosokumoRequest().

std::vector<uint8_t> Yosokumo::YosokumoRequest::entity [private]

Definition at line 48 of file YosokumoRequest.h.

Referenced by getEntity(), getResponse(), initForOperation(), and makeRequest().

std::string Yosokumo::YosokumoRequest::hostName [private]

Definition at line 41 of file YosokumoRequest.h.

Referenced by deleteFromServer(), getFromServer(), postToServer(), and putToServer().

Definition at line 47 of file YosokumoRequest.h.

Referenced by getResponse(), getStatusCode(), initForOperation(), and makeRequest().


The documentation for this class was generated from the following files:
Generated on Mon May 13 09:19:12 2013 for C++ Yosokumo API by  doxygen 1.6.3