com.geoloqi.android.sdk
Class LQSession

java.lang.Object
  com.geoloqi.android.sdk.LQSession

All Implemented Interfaces:

LQBuild

public class LQSession
extends java.lang.Object
implements LQBuild

LQSession represents a client session for communicating directly with the Geoloqi REST API. It provides convenience methods for making raw API requests on a background thread.

Several factory methods are also provided for obtaining an instance of LQSession.

Creating a new instance of LQSession will allow you to make API requests as a specific user. It will not change the session used by LQTracker. To update the saved session (sign-in a different user) see LQService.setSavedSession(com.geoloqi.android.sdk.LQSession).

Copyright (c) 2011 Geoloqi Inc. All rights reserved.

Author:

Tristan Waddington, Josh Yaganeh

Nested Class Summary

static interface

LQSession.OnRunApiRequestListener Interface definition for a callback to be invoked when runApiRequest(org.apache.http.client.methods.HttpRequestBase, com.geoloqi.android.sdk.LQSession.OnRunApiRequestListener) completes.

Field Summary

Fields inherited from interface com.geoloqi.android.sdk.LQBuild

LQ_SDK_BUILD, LQ_SDK_NAME, LQ_SDK_VERSION

Constructor Summary

LQSession(android.content.Context context)
Create a new instance of LQSession.

Method Summary

static void	createAnonymousUserAccount(LQSession.OnRunApiRequestListener listener, android.os.Handler handler, android.content.Context context) Create a new Geoloqi anonymous user account.
static void	createAnonymousUserAccount(java.lang.String key, java.lang.String[] layerIds, java.lang.String[] groupTokens, LQSession.OnRunApiRequestListener listener, android.os.Handler handler, android.content.Context context) Create a new Geoloqi anonymous user account.
static void	createUserAccount(java.lang.String username, java.lang.String password, LQSession.OnRunApiRequestListener listener, android.os.Handler handler, android.content.Context context) Create a new Geoloqi user account with the provided username and password.
static void	createUserAccount(java.lang.String username, java.lang.String password, java.lang.String[] layerIds, java.lang.String[] groupTokens, LQSession.OnRunApiRequestListener listener, android.os.Handler handler, android.content.Context context) Create a new Geoloqi user account with the provided username and password and, if provided, subscribe the created user to the specified layers and groups.
static java.lang.String	formatTimestamp(long time) Format a Unix timestamp as an ISO 8601 date String.
java.lang.String	getAccessToken() Get the access token for the session's user.
java.lang.String	getDisplayName() Get the display name of the session's user.
java.lang.String	getUserId() Get the user ID of the session's user.
java.lang.String	getUsername() Get the username of the session's user.
boolean	isAnonymous() True if the session is anonymous; false if otherwise.
static void	requestSession(java.lang.String username, java.lang.String password, LQSession.OnRunApiRequestListener listener, android.os.Handler handler, android.content.Context context) Request a new session that has been authenticated with the credentials of an existing Geoloqi user.
void	runApiRequest(org.apache.http.client.methods.HttpRequestBase request, LQSession.OnRunApiRequestListener listener) Run a raw HttpRequest on a background thread.
void	runGetRequest(java.lang.String path, LQSession.OnRunApiRequestListener listener) Send a GET request to the Geoloqi API.
void	runGetRequest(java.lang.String path, java.util.Map<java.lang.String,java.lang.String> args, org.apache.http.Header[] headers, LQSession.OnRunApiRequestListener listener) Send a GET request to the Geoloqi API.
void	runPostRequest(java.lang.String path, org.json.JSONArray json, org.apache.http.Header[] headers, LQSession.OnRunApiRequestListener listener) Send a POST request to the Geoloqi API with a "Content-Type" value of "application/json".
void	runPostRequest(java.lang.String path, org.json.JSONArray json, LQSession.OnRunApiRequestListener listener) Send a POST request to the Geoloqi API with a "Content-Type" value of "application/json".
void	runPostRequest(java.lang.String path, org.json.JSONObject json, org.apache.http.Header[] headers, LQSession.OnRunApiRequestListener listener) Send a POST request to the Geoloqi API with a "Content-Type" value of "application/json".
void	runPostRequest(java.lang.String path, org.json.JSONObject json, LQSession.OnRunApiRequestListener listener) Send a POST request to the Geoloqi API with a "Content-Type" value of "application/json".
void	runPostRequest(java.lang.String path, org.apache.http.entity.StringEntity entity, org.apache.http.Header[] headers, LQSession.OnRunApiRequestListener listener) Send a POST request to the Geoloqi API with a "Content-Type" value of "application/json".
void	sendGcmPushToken(java.lang.String token, LQSession.OnRunApiRequestListener listener) Perform an asynchronous request to send the device's push token to the server.
void	sendPushToken(java.lang.String token, LQSession.OnRunApiRequestListener listener) Deprecated.
void	setAccessToken(java.lang.String accessToken) Set the access token for the session's user.
void	setClientCredentials(java.lang.String clientId, java.lang.String clientSecret) Set the application's client ID and secret.
void	setDisplayName(java.lang.String displayName) Set the display name for the session's user.
void	setHandler(android.os.Handler handler) Set the Handler that will be used to run any callback listeners.
void	setIsAnonymous(boolean isAnonymous) Mark this as an anonymous user session.
void	setUserId(java.lang.String id) Set the user ID for the session's user.
void	setUsername(java.lang.String username) Set the username for the session's user.
static java.lang.String	urlencode(java.util.Map<java.lang.String,java.lang.String> args) Encode a Map of query arguments for use in a GET request.

Methods inherited from class java.lang.Object

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

Constructor Detail

LQSession

public LQSession(android.content.Context context)

Create a new instance of LQSession.

You'll need to call setAccessToken(java.lang.String) or setClientCredentials(java.lang.String, java.lang.String) before making an API request.

Parameters:

context -

Method Detail

createAnonymousUserAccount

public static void createAnonymousUserAccount(java.lang.String key,
                                              java.lang.String[] layerIds,
                                              java.lang.String[] groupTokens,
                                              LQSession.OnRunApiRequestListener listener,
                                              android.os.Handler handler,
                                              android.content.Context context)

Create a new Geoloqi anonymous user account. Subscribe the created user to the specified layers and groups.

Parameters:

key - An optional unique identifier for the user. Repeated API calls to user/create_anon with the same key value will not create a new account.

layerIds - An optional array of one or more layer IDs the user should be subscribed to when created.

groupTokens - An optional array of one or more group tokens the user should be added to when created.

listener - the callback to be invoked when the request completes.

handler - a Handler to run the callback listener.

context -

createAnonymousUserAccount

public static void createAnonymousUserAccount(LQSession.OnRunApiRequestListener listener,
                                              android.os.Handler handler,
                                              android.content.Context context)

Create a new Geoloqi anonymous user account.

Parameters:

listener - the callback to be invoked when the request completes.

handler - a Handler to run the callback listener.

context -

createUserAccount

public static void createUserAccount(java.lang.String username,
                                     java.lang.String password,
                                     java.lang.String[] layerIds,
                                     java.lang.String[] groupTokens,
                                     LQSession.OnRunApiRequestListener listener,
                                     android.os.Handler handler,
                                     android.content.Context context)

Create a new Geoloqi user account with the provided username and password and, if provided, subscribe the created user to the specified layers and groups. The Geoloqi API will return an error if a user with the provided username already exists.

Parameters:

username -

password -

layerIds -

groupTokens -

listener - the callback to be invoked when the request completes.

handler - a Handler to run the callback listener.

context -

createUserAccount

public static void createUserAccount(java.lang.String username,
                                     java.lang.String password,
                                     LQSession.OnRunApiRequestListener listener,
                                     android.os.Handler handler,
                                     android.content.Context context)

Create a new Geoloqi user account with the provided username and password. The Geoloqi API will return an error if a user with the provided username already exists.

Parameters:

username -

password -

listener - the callback to be invoked when the request completes.

handler - a Handler to run the callback listener.

context -

requestSession

public static void requestSession(java.lang.String username,
                                  java.lang.String password,
                                  LQSession.OnRunApiRequestListener listener,
                                  android.os.Handler handler,
                                  android.content.Context context)

Request a new session that has been authenticated with the credentials of an existing Geoloqi user.

Parameters:

username -

password -

listener - the callback to be invoked when the request completes.

handler - a Handler to run the callback listener.

context -

setHandler

public void setHandler(android.os.Handler handler)

Set the Handler that will be used to run any callback listeners.

Parameters:

handler -

setClientCredentials

public void setClientCredentials(java.lang.String clientId,
                                 java.lang.String clientSecret)

Set the application's client ID and secret.

The application credentials should only be used when creating user accounts and making other app-level API requests.

Parameters:

clientId -

clientSecret -

setAccessToken

public void setAccessToken(java.lang.String accessToken)

Set the access token for the session's user.

Parameters:

accessToken -

getAccessToken

public java.lang.String getAccessToken()

Get the access token for the session's user.

setDisplayName

public void setDisplayName(java.lang.String displayName)

Set the display name for the session's user.

Parameters:

displayName -

getDisplayName

public java.lang.String getDisplayName()

Get the display name of the session's user.

setUsername

public void setUsername(java.lang.String username)

Set the username for the session's user.

Parameters:

username -

getUsername

public java.lang.String getUsername()

Get the username of the session's user.

setUserId

public void setUserId(java.lang.String id)

Set the user ID for the session's user.

Parameters:

id -

getUserId

public java.lang.String getUserId()

Get the user ID of the session's user.

setIsAnonymous

public void setIsAnonymous(boolean isAnonymous)

Mark this as an anonymous user session.

Parameters:

isAnonymous -

isAnonymous

public boolean isAnonymous()

True if the session is anonymous; false if otherwise.

sendGcmPushToken

public void sendGcmPushToken(java.lang.String token,
                             LQSession.OnRunApiRequestListener listener)

Perform an asynchronous request to send the device's push token to the server.

Parameters:

token -

listener -

sendPushToken

@Deprecated
public void sendPushToken(java.lang.String token,
                                     LQSession.OnRunApiRequestListener listener)

Deprecated.

This method is deprecated.
This function is only relevant for applications using the legacy C2DM push system.

Perform an asynchronous request to send the device's push token to the server.

Parameters:

token - the push token.

listener -

See Also:

sendGcmPushToken(java.lang.String, com.geoloqi.android.sdk.LQSession.OnRunApiRequestListener)

runGetRequest

public void runGetRequest(java.lang.String path,
                          LQSession.OnRunApiRequestListener listener)

Send a GET request to the Geoloqi API.

Parameters:

path - the API path (example: "account/profile").

listener -

runGetRequest

public void runGetRequest(java.lang.String path,
                          java.util.Map<java.lang.String,java.lang.String> args,
                          org.apache.http.Header[] headers,
                          LQSession.OnRunApiRequestListener listener)

Send a GET request to the Geoloqi API.

Parameters:

path - the API path (example: "account/profile").

args - null-OK; a map of query arguments to be encoded and appended to the path.

headers - null-OK;

listener -

runPostRequest

public void runPostRequest(java.lang.String path,
                           org.json.JSONObject json,
                           LQSession.OnRunApiRequestListener listener)

Send a POST request to the Geoloqi API with a "Content-Type" value of "application/json".

Parameters:

path - the API path (example: "link/create").

json -

listener -

runPostRequest

public void runPostRequest(java.lang.String path,
                           org.json.JSONObject json,
                           org.apache.http.Header[] headers,
                           LQSession.OnRunApiRequestListener listener)

Send a POST request to the Geoloqi API with a "Content-Type" value of "application/json".

Parameters:

path - the API path (example: "link/create").

json -

headers - null-OK;

listener -

runPostRequest

public void runPostRequest(java.lang.String path,
                           org.json.JSONArray json,
                           LQSession.OnRunApiRequestListener listener)

Send a POST request to the Geoloqi API with a "Content-Type" value of "application/json".

Parameters:

path - the API path (example: "link/create").

json -

listener -

runPostRequest

public void runPostRequest(java.lang.String path,
                           org.json.JSONArray json,
                           org.apache.http.Header[] headers,
                           LQSession.OnRunApiRequestListener listener)

Send a POST request to the Geoloqi API with a "Content-Type" value of "application/json".

Parameters:

path - the API path (example: "link/create").

json -

headers - null-OK;

listener -

runPostRequest

public void runPostRequest(java.lang.String path,
                           org.apache.http.entity.StringEntity entity,
                           org.apache.http.Header[] headers,
                           LQSession.OnRunApiRequestListener listener)

Send a POST request to the Geoloqi API with a "Content-Type" value of "application/json".

This method is primarily used internally. If you're trying to send a JSON payload you're better off using one of the other runPostRequest(java.lang.String, org.json.JSONObject, com.geoloqi.android.sdk.LQSession.OnRunApiRequestListener) methods.

Parameters:

path - the API path (example: "link/create").

entity - a StringEntity containing a serialized JSONObject or JSONArray.

headers -

listener -

runApiRequest

public void runApiRequest(org.apache.http.client.methods.HttpRequestBase request,
                          LQSession.OnRunApiRequestListener listener)

Run a raw HttpRequest on a background thread. This method will sign the request by adding an "Authorization" header.

Parameters:

request -

listener -

formatTimestamp

public static java.lang.String formatTimestamp(long time)

Format a Unix timestamp as an ISO 8601 date String.

Parameters:

time -

Returns:

the formatted time as a String.

urlencode

public static java.lang.String urlencode(java.util.Map<java.lang.String,java.lang.String> args)

Encode a Map of query arguments for use in a GET request.

See URLEncoder.encode(java.lang.String).

Parameters:

args -

Returns:

the URL encoded String.