Base class for requests made to a ClientService. More...

#include "client/service/client_service.h"

Public Member Functions
	ClientServiceRequest (const ClientService service, AuthorizationCredential credential, const HttpRequest::HttpMethod &method, const StringPiece &uri_template)
	Construct a new request.
virtual	~ClientServiceRequest ()
	Standard instance destructor.
void	DestroyWhenDone ()
	Tell instance to self-destruct (destroy itself) once it is safe to.
virtual util::Status	Execute ()
	Ask the service to execute the request synchronously.
virtual void	ExecuteAsync (HttpRequestCallback *callback)
	Ask the service to execute the request asynchronously.
HttpRequest *	mutable_http_request ()
	Returns the underlying HttpRequest.
const HttpRequest *	http_request () const
	Returns the underlying HttpReqeust.
HttpResponse *	http_response ()
	Returns the underlying response.
Protected Member Functions
virtual util::Status	PrepareHttpRequest (HttpRequestCallback *callback=NULL)
	Fills out the mutable_http_request() owned by this instance with the information specified by this request.
virtual util::Status	PrepareUrl (const StringPiece &templated_url, string *prepared_url)
	Resolves the templated URL into the actual URL to use.
virtual util::Status	AppendVariable (const StringPiece &variable_name, const UriTemplateConfig &config, string *target)
	Appends the variable value to the target string.
virtual util::Status	AppendOptionalQueryParameters (string *target)
	Appends the optional query parameters to the url.
util::Status	ExecuteAndParseResponse (SerializableJson *data)
	Execute the request synchronously.
bool	get_use_media_download () const
	Accessor for the use_media_download attribute.
void	set_use_media_download (bool use)
	Setter for the use_media_download attribute.
Static Protected Member Functions
static util::Status	ParseResponse (HttpResponse response, SerializableJson data)
	Parse the response payload (i.e.

Detailed Description

Base class for requests made to a ClientService.

This class is based on a Command Pattern. The instance is given the service endpoint to invoke and is given the arguments to invoke with as expected by that endpoint. When its Execute() method is called, it will invoke the command and wait for the response. The caller can get any response data as well as the overall status from the request instance.

When using the code generator to create custom APIs for a given service, the code generator will subclass these requests for each endpoint API. The specialized subclasses will contain higher level methods for setting the various arguments and parameters that are available to use. Those class instances are created using the ClientService instance (i.e. the ClientService acts as a ClientSrviceRequet factory. Therefore this class is not typically explicitly instantiated. Lower level code may use this class directly since it is concrete and fully capable.

You should not explicitly destroy this class (or derived classes) when making asynchronous requests unless you know that the request has completely finished executing (its underlying HttpRequest is done). It is safest to use DestroyWhenDone() instead. Otherwise code on the stack may still be referencing the instance after it is destroyed, and your program will crash.

Requests are given a service and RFC 6570 URI Template to invoke within that service. The purpose of the URI template is to ultimately provide the URL within the service. The request instance can resolve the parameters in the template. This is described in more detail with the PrepareUrl() method.

Constructor & Destructor Documentation

ClientServiceRequest	(	const ClientService *	service,
		AuthorizationCredential *	credential,
		const HttpRequest::HttpMethod &	method,
		const StringPiece &	uri_template
	)

Construct a new request.

Parameters:

[in]	service	The service to send the request to
[in]	credential	If not NULL, the credentials to invoke with
[in]	method	The HTTP method when making the HTTP request
[in]	uri_template	The URI template specifying the url to invoke

See also:: DestroyWhenDone; Execute; ExecuteAsync

virtual ~ClientServiceRequest ( ) [virtual]

Standard instance destructor.

Precondition:: The HttpRequestState must be HttpRequestState::done()

See also:: DestroyWhenDone

Member Function Documentation

virtual util::Status AppendOptionalQueryParameters ( string * target ) [protected, virtual]

Appends the optional query parameters to the url.

This method is called by the default PrepareHttpReqeuest to add the optional parameters that might not be explicitly stated in the URI template that was bound to the request.

The base method simply returns success. Specialized requests should add any optional query parameters that have been added into the request.

virtual util::Status AppendVariable	(	const StringPiece &	variable_name,
		const UriTemplateConfig &	config,
		string *	target
	)		`[protected, virtual]`

Appends the variable value to the target string.

This method should use UriTemplate for the actual string append once it locally determines what the value shoudl be.

Parameters:

[in]	variable_name	The name of the variable to append
[in]	config	A pass through parameter needed when asking UriTemplate to append the strings. The value of this paraemter is determined internally by the methods within this class that invoke this method.
[out]	target	The string to append to.

void DestroyWhenDone ( )

Tell instance to self-destruct (destroy itself) once it is safe to.

This is the preferred means to destroy instances that are used asynchronously. The instance will remain active until after the callback (if any) has finished running and after any signaling has been performed to HttpResponse::WaitUntilDone().

This method will destroy the object immediately if it is safe to do so.

virtual util::Status Execute ( ) [virtual]

Ask the service to execute the request synchronously.

The response data will be in the embedded HttpRequest

Returns:: status indicating the overall status of performing the request.

Note:: HTTP failures (e.g. 4xx HTTP codes) are considered errors as are transport level errors (e.g. unknown host). Finer grained status information is available from the underlying HttpRequest.

See also:: ExecuteAsync; ExecuteAndParseResponse; mutable_http_request; http_response

util::Status ExecuteAndParseResponse ( SerializableJson * data ) [protected]

Execute the request synchronously.

If the response suggests success then load the response payload into the provided data parameter.

Parameters:

[out] data The data will be cleared if the Execute was not successful.

Returns:: success if the Execute was successful and the response payload could be loaded into the data object. Otherwise it will fail. If you want to distinguish execute failures from response handling failures then you will need to look at the http_response() details.

This method is protected since it does not make sense on methods that do not return json data objects. For those that do, their specialized classes can expose this method by adding a public method that delegates to this implementation.

virtual void ExecuteAsync ( HttpRequestCallback * callback ) [virtual]

Ask the service to execute the request asynchronously.

Parameters:

[in] callback If not NULL then run this once the request is done.

The callback will be called once the HttpRequest::done() criteria are satisfied on the underlying HttpRequest. This is always the case, even on fundamental transport errors such as unknown host or if the request is invalid.

The callback can check the HttpRequest details, including its HttpResponse to get status and response details. These will be valid while the callback is running, but will no longer be valid once the request is destroyed.

Warning:: The callback might be called from another thread than this one. For normal execution flows where the request can be sent to the service, the callback will be invoked from the bound executor's context. If there is a fundamental problem with the request or it could not be queued then it may (but not necessarily) be called from the current context before the method returns.; If DestroyWhenDone() has been called before invoking this method then the instance might complete and thus be destroyed before this method returns. This is ok, but you will have no way of knowing this without recording extra state in your callback.

See also:: Execute; mutable_http_request

bool get_use_media_download ( ) const [inline, protected]

Accessor for the use_media_download attribute.

This attribute should only be exposed by methods that support it.

Returns:: true if the request should use HTTP media download.

const HttpRequest* http_request ( ) const [inline]

Returns the underlying HttpReqeust.

The request is set and managed by this instance. The request provides access to its current HttpRequestState, response status, and the actual response.

HttpResponse* http_response ( ) [inline]

Returns the underlying response.

The response is set and managed by this instance (actually by the instance's request). It is only valid over the lifetime of this instance so be sure to look at any values before you destroy the request.

HttpRequest* mutable_http_request ( ) [inline]

Returns the underlying HttpRequest.

The request is set and managed by this instance. The options on the request can be tuned. The request is owned by this instance so you should not set its destroy_when_done attribute. Use DestroyWhenDone on this instance instead if desired.

static util::Status ParseResponse	(	HttpResponse *	response,
		SerializableJson *	data
	)		`[static, protected]`

Parse the response payload (i.e.

its body_reader) as a data instance.

Parameters:

[in,out]	response	The response to parse is modified as it is read.
[out]	data	The data to parse into

Returns:: Failure if the response has no data or cannot be parsed.

See also:: HttpResponse::body_reader()

virtual util::Status PrepareHttpRequest ( HttpRequestCallback * callback = NULL ) [protected, virtual]

Fills out the mutable_http_request() owned by this instance with the information specified by this request.

The base class implementation calls PrepareUrl and snd sets the url on the underlying request. Specialized classes may have other needs, such as setting the requset payload.

Parameters:

callback [in] If not NULL then this will be called on failure.

virtual util::Status PrepareUrl	(	const StringPiece &	templated_url,
		string *	prepared_url
	)		`[protected, virtual]`

Resolves the templated URL into the actual URL to use.

The base class implementation assumes that the content was set in the constructor. It uses UriTemplate to handle URL parameters and expects that specialized subclasses will override the ApendVariable method to resolve the values for the variables that this method finds in the template.

Parameters:

[in]	templated_url	An RFC 6570 formatted URL.
[out]	prepared_url	The templated_url after resolving the variables.

Note:: Conceptually this method is const. However technically it is not because so it can used as a callback method where the mechanism does not permit non-const methods.

void set_use_media_download ( bool use ) [inline, protected]

Setter for the use_media_download attribute.

This attribute should only be exposed by methods that support it.

Parameters:

[in] use True if HTTP should use media download.

The documentation for this class was generated from the following file:

googleapis/client/service/client_service.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation