org.opensocial

Class Request

java.lang.Object

org.opensocial.Request

public class Request
extends Object

OpenSocial data request; encapsulates all information required to execute a request including RESTful URL template, RPC method name, and any parameters required by the provider. Typically, Request objects aren't instantiated by clients directly but are instead returned by service class methods. Requests are executed by passing them into a Client's send method.

Author:

Jason Cooper

Field Summary

Fields

Modifier and Type	Field and Description
static String	ALBUM_ID
static String	APP_ID
static String	FRIEND_ID
static String	GROUP_ID
static String	GUID
static String	HISTORY
static String	ITEM_ID
static String	MOOD_ID
static String	P_ID
static String	SELECTOR

Constructor Summary

Constructors

Constructor and Description
Request(String restUrlTemplate, String rpcMethod, String restMethod) Creates and returns a new Request configured with the passed RESTful URL template, RPC method name, and HTTP method.

Method Summary

Methods

Modifier and Type	Method and Description
void	addComponent(String name, String value) Sets the request component with the specified name to the specified value.
void	addParameter(String name, String value) Adds an extended request parameter, e.g. count or startIndex, to be passed as query parameters in the URL if executed using REST or in the request body if executed via a RPC.
void	addParameters(Map<String,String> parameters) Adds extended request parameters for each name-value pair in the passed Map.
void	addRestPayloadParameter(String name, Object value) Adds a new parameter with the specified name and value to the set of parameters used by the Client to generate the JSON payload for a REST request; this method should not be called by clients directly unless custom requests are being executed.
<T extends Model> void	addRestPayloadParameters(T modelObject) For each property in the passed model object, adds a new parameter to the set of parameters used by the Client to generate the JSON payload for a REST request ; this method should not be called by clients directly unless custom requests are being executed.
void	addRestQueryStringParameter(String name, String value) Adds a new parameter with the specified name and value to the set of parameters used by the Client to generate the query string that gets appended to the RESTful URL; this method should not be called by clients directly unless custom requests are being executed.
void	addRpcPayloadParameter(String name, Object value) Adds a new parameter with the specified name and value to the set of parameters used by the Client to generate the JSON payload for a RPC request; this method should not be called by clients directly unless custom requests are being executed.
void	addRpcQueryStringParameter(String name, String value) Adds a new parameter with the specified name and value to the set of parameters used by the Client to generate the query string that gets appended to the RPC endpoint; this method should not be called by clients directly unless custom requests are being executed.
String	getComponent(String name) Returns the request component with the specified name, e.g. guid or groupId, or null if no request component with the specified name exists.
String	getContentType() Returns the request's custom content (MIME) type if provided; if null, the Client will set the Content-Type request header to a default type specified in the Provider class passed into it, usually application/json.
byte[]	getCustomPayload() Returns the request's custom payload if provided; if not null, this value overrides the JSON payload generated by the Client.
Class<? extends Model>	getModelClass() Returns the model class that developers use to access response data after a request has been successfully executed.
String	getRestMethod() Returns the associated HTTP method for REST requests, e.g.
Map<String,Object>	getRestPayloadParameters() Returns the set of name-value pairs used by the Client to generate the JSON payload for a RESTful request; guaranteed not to be null.
Map<String,String>	getRestQueryStringParameters() Returns the set of name-value pairs used by the Client to generate the query string that gets appended to the RESTful URL; guaranteed not to be null.
String	getRestUrlTemplate() Returns the RESTful URL template for the requested resource type, e.g.
String	getRpcMethod() Returns the associated RPC method name, e.g. people.get.
Map<String,Object>	getRpcPayloadParameters() Returns the set of name-value pairs used by the Client to generate the JSON payload for a RPC request; guaranteed not to be null.
Map<String,String>	getRpcQueryStringParameters() Returns the set of name-value pairs used by the Client to generate the query string that gets appended to the RPC endpoint; guaranteed not to be null.
void	setAppId(String appId) Sets the request's appid component which is passed as a parameter when the request is executed.
void	setContentType(String contentType) Sets a custom content (MIME) type which is later used as the value of the Content-Type request header when the request is executed; leave null except when passing a custom payload such as binary image data.
void	setCountParameter(int count) Sets the "count" extended request parameter to the specified value; used to specify the page size for a paged collection.
void	setCustomPayload(byte[] payload) Sets the payload to pass in the corresponding HTTP request's body as POST data when the request is executed, overriding the JSON payload generated by the Client; leave null except when uploading special content, e.g. binary image data, and make sure to call setContentType as well.
void	setFieldsParameter(String[] fields) Sets the "fields" extended request parameter to the specified value; used to specify which field names to include in the representation or in the members of a collection.
void	setGroupId(String groupId) Sets the request's groupId component which is passed as a parameter when the request is executed.
void	setGuid(String guid) Sets the request's guid component which is passed as a parameter when the request is executed.
void	setModelClass(Class<? extends Model> modelClass) Sets the model class that developers will use to access response data after a request has been successfully executed; this method should not be called by clients directly unless custom requests are being executed.
void	setPId(String pid) Sets the request's pId (person ID) component which is passed as a parameter when the request is executed.
void	setRestUrlTemplate(String template) Sets the REST URL template for this request.
void	setSelector(String selector) Sets the request's selector component which is passed as a parameter when the request is executed.
void	setStartIndexParameter(int startIndex) Sets the "startIndex" extended request parameter to the specified value; used to specify the index into a paged collection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GUID

public static final String GUID

See Also:

Constant Field Values

GROUP_ID

public static final String GROUP_ID

See Also:

Constant Field Values

SELECTOR

public static final String SELECTOR

See Also:

Constant Field Values

APP_ID

public static final String APP_ID

See Also:

Constant Field Values

P_ID

public static final String P_ID

See Also:

Constant Field Values

ALBUM_ID

public static final String ALBUM_ID

See Also:

Constant Field Values

ITEM_ID

public static final String ITEM_ID

See Also:

Constant Field Values

MOOD_ID

public static final String MOOD_ID

See Also:

Constant Field Values

FRIEND_ID

public static final String FRIEND_ID

See Also:

Constant Field Values

HISTORY

public static final String HISTORY

See Also:

Constant Field Values

Constructor Detail

Request

public Request(String restUrlTemplate,
       String rpcMethod,
       String restMethod)

Creates and returns a new Request configured with the passed RESTful URL template, RPC method name, and HTTP method.

Parameters:

restUrlTemplate - RESTful URL template to use when executing request using REST

rpcMethod - RPC method name to use when executing request via a RPC

restMethod - HTTP method to use when executing request using REST

Method Detail

getRpcMethod

public String getRpcMethod()

Returns the associated RPC method name, e.g. people.get.

getRestMethod

public String getRestMethod()

Returns the associated HTTP method for REST requests, e.g. GET or POST.

getRestUrlTemplate

public String getRestUrlTemplate()

Returns the RESTful URL template for the requested resource type, e.g. people/{guid}/{selector}/{pid}.

getContentType

public String getContentType()

Returns the request's custom content (MIME) type if provided; if null, the Client will set the Content-Type request header to a default type specified in the Provider class passed into it, usually application/json.

getCustomPayload

public byte[] getCustomPayload()

Returns the request's custom payload if provided; if not null, this value overrides the JSON payload generated by the Client.

getComponent

public String getComponent(String name)

Returns the request component with the specified name, e.g. guid or groupId, or null if no request component with the specified name exists.

Parameters:

name - Name of the request component to return.

getRpcPayloadParameters

public Map<String,Object> getRpcPayloadParameters()

Returns the set of name-value pairs used by the Client to generate the JSON payload for a RPC request; guaranteed not to be null.

getRestPayloadParameters

public Map<String,Object> getRestPayloadParameters()

Returns the set of name-value pairs used by the Client to generate the JSON payload for a RESTful request; guaranteed not to be null.

getRpcQueryStringParameters

public Map<String,String> getRpcQueryStringParameters()

Returns the set of name-value pairs used by the Client to generate the query string that gets appended to the RPC endpoint; guaranteed not to be null.

getRestQueryStringParameters

public Map<String,String> getRestQueryStringParameters()

Returns the set of name-value pairs used by the Client to generate the query string that gets appended to the RESTful URL; guaranteed not to be null.

getModelClass

public Class<? extends Model> getModelClass()

Returns the model class that developers use to access response data after a request has been successfully executed.

setRestUrlTemplate

public void setRestUrlTemplate(String template)

Sets the REST URL template for this request.

Parameters:

template - REST URL template for this request

setGuid

public void setGuid(String guid)

Sets the request's guid component which is passed as a parameter when the request is executed.

Parameters:

guid - GUID (OpenSocial user ID) to set or "@me" for the current viewer

setAppId

public void setAppId(String appId)

Sets the request's appid component which is passed as a parameter when the request is executed.

Parameters:

appId - application ID to set or "@app" for the current application

setGroupId

public void setGroupId(String groupId)

Sets the request's groupId component which is passed as a parameter when the request is executed.

Parameters:

groupId - OpenSocial group ID to set, usually "@self" or "@friends"

setSelector

public void setSelector(String selector)

Sets the request's selector component which is passed as a parameter when the request is executed.

Parameters:

selector - OpenSocial selector to set, usually "@self" or "@friends"

setPId

public void setPId(String pid)

Sets the request's pId (person ID) component which is passed as a parameter when the request is executed.

Parameters:

pid - OpenSocial pId to set

setContentType

public void setContentType(String contentType)

Sets a custom content (MIME) type which is later used as the value of the Content-Type request header when the request is executed; leave null except when passing a custom payload such as binary image data.

Parameters:

contentType - custom Content-Type request header value to set

setCustomPayload

public void setCustomPayload(byte[] payload)

Sets the payload to pass in the corresponding HTTP request's body as POST data when the request is executed, overriding the JSON payload generated by the Client; leave null except when uploading special content, e.g. binary image data, and make sure to call setContentType as well.

Parameters:

payload - custom request payload to set

addComponent

public void addComponent(String name,
                String value)

Sets the request component with the specified name to the specified value.

Parameters:

name - name of request component to set

value - new value of specified request component

addParameter

public void addParameter(String name,
                String value)

Adds an extended request parameter, e.g. count or startIndex, to be passed as query parameters in the URL if executed using REST or in the request body if executed via a RPC.

Parameters:

name - name of the extended parameter to set

value - value of the specified extended parameter

addParameters

public void addParameters(Map<String,String> parameters)

Adds extended request parameters for each name-value pair in the passed Map.

Parameters:

parameters - Map of name-value pairs to pass as extended request parameters

See Also:

addParameter(String, String)

setCountParameter

public void setCountParameter(int count)

Sets the "count" extended request parameter to the specified value; used to specify the page size for a paged collection.

Parameters:

count - new value of "count" extended request parameter

See Also:

addParameter(String, String), setStartIndexParameter(int)

setStartIndexParameter

public void setStartIndexParameter(int startIndex)

Sets the "startIndex" extended request parameter to the specified value; used to specify the index into a paged collection.

Parameters:

startIndex - new value of "startIndex" extended request parameter

See Also:

addParameter(String, String), setCountParameter(int)

setFieldsParameter

public void setFieldsParameter(String[] fields)

Sets the "fields" extended request parameter to the specified value; used to specify which field names to include in the representation or in the members of a collection.

Parameters:

fields - array of field names to pass as extended request parameter

See Also:

addParameter(String, String)

addRpcPayloadParameter

public void addRpcPayloadParameter(String name,
                          Object value)

Adds a new parameter with the specified name and value to the set of parameters used by the Client to generate the JSON payload for a RPC request; this method should not be called by clients directly unless custom requests are being executed.

Parameters:

name - name of RPC payload parameter to set

value - value of the specified RPC payload parameter, usually of type String, List, or Map

addRestPayloadParameter

public void addRestPayloadParameter(String name,
                           Object value)

Adds a new parameter with the specified name and value to the set of parameters used by the Client to generate the JSON payload for a REST request; this method should not be called by clients directly unless custom requests are being executed.

Parameters:

name - name of REST payload parameter to set

value - value of the specified REST payload parameter, usually of type String, List, or Map

addRestPayloadParameters

public <T extends Model> void addRestPayloadParameters(T modelObject)

For each property in the passed model object, adds a new parameter to the set of parameters used by the Client to generate the JSON payload for a REST request ; this method should not be called by clients directly unless custom requests are being executed.

Parameters:

modelObject - Map of name-value pairs to pass as REST payload parameters

addRpcQueryStringParameter

public void addRpcQueryStringParameter(String name,
                              String value)

Adds a new parameter with the specified name and value to the set of parameters used by the Client to generate the query string that gets appended to the RPC endpoint; this method should not be called by clients directly unless custom requests are being executed.

Parameters:

name - name of the RPC query string parameter to set

value - value of the specified RPC query string parameter

addRestQueryStringParameter

public void addRestQueryStringParameter(String name,
                               String value)

Adds a new parameter with the specified name and value to the set of parameters used by the Client to generate the query string that gets appended to the RESTful URL; this method should not be called by clients directly unless custom requests are being executed.

Parameters:

name - name of the REST query string parameter to set

value - value of the specified REST query string parameter

setModelClass

public void setModelClass(Class<? extends Model> modelClass)

Sets the model class that developers will use to access response data after a request has been successfully executed; this method should not be called by clients directly unless custom requests are being executed.

Parameters:

modelClass - class extending Model to use to access response data