com.geoloqi.android.sdk
Class LQSession

java.lang.Object
  extended by 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.