com.stackmob.sdk.api
Class StackMob

java.lang.Object
  com.stackmob.sdk.api.StackMob

public class StackMob
extends Object

The StackMob object is your interface for accessing StackMob's many features. Its functions include:

• Logging in and managing user sessions
• Datastore API Methods
• Push API Requests

A StackMob instance is created with authorization credentials along with some optional configuration parameters. To use different configurations in one app, simply instantiate multiple StackMob objects.

Nested Class Summary

static class

StackMob.OAuthVersion The two different OAuth versions the SDK can use for authentication.

Field Summary

static String	DEFAULT_API_HOST
static String	DEFAULT_PASSWORD_FIELD
static StackMobRedirectedCallback	DEFAULT_REDIRECTED_CALLBACK
static String	DEFAULT_USER_ID
static String	DEFAULT_USER_SCHEMA_NAME
protected StackMobRedirectedCallback	redirectedCallback An internal redirected callback.
protected StackMobRedirectedCallback	userRedirectedCallback The redirected callback set by the user

Constructor Summary

StackMob(Integer apiVersionNumber, String apiKey)
a StackMob constructor allowing you to specify the OAuth version.

StackMob(StackMob.OAuthVersion oauthVersion, Integer apiVersionNumber, String apiKey, String apiSecret)
a StackMob constructor allowing you to specify the OAuth version.

StackMob(StackMob.OAuthVersion oauthVersion, Integer apiVersionNumber, String apiKey, String apiSecret, String apiHost, String userSchema, String userIdName, String passwordFieldName, StackMobRedirectedCallback redirectedCallback)
the most complete StackMob constructor allowing you to set values for everything

StackMob(StackMob other)
Copy constructor

Method Summary

void	facebookLogin(String token, StackMobOptions options, StackMobRawCallback callback) login to StackMob with Facebook credentials.
void	facebookLogin(String token, StackMobRawCallback callback) login to StackMob with Facebook credentials.
void	facebookPostMessage(String msg, StackMobRawCallback callback) post a message to Facebook.
void	forgotPassword(String username, StackMobRawCallback callback) send out a password reset email to a user who's forgotten their password
StackMobDatastore	getDatastore()
ExecutorService	getExecutor() get the executor used for requests
void	getFacebookUserInfo(StackMobRawCallback callback) get facebook user info for the current user.
void	getLoggedInUser(StackMobCallback callback) Gets the user object for the currently logged in oauth2 user.
void	getLoggedInUser(StackMobOptions options, StackMobCallback callback) Gets the user object for the currently logged in oauth2 user.
String	getLoggedInUsername() get the logged in user locally.
StackMob.OAuthVersion	getOAuthVersion() get the OAuthVersion this StackMob object is configured for
String	getPasswordField() the name of the password field in the user object
StackMobRedirectedCallback	getRedirectedCallback() get the callback used for redirected requests
StackMobSession	getSession() get the session that this StackMob object contains
static StackMob	getStackMob() Get the singleton StackMob object.
void	getTwitterUserInfo(StackMobRawCallback callback) get twitter user info for the current user.
String	getUserIdName() the primary key for the user object
static String	getVersion() The current android sdk version
void	gigyaLogin(String gigyaUid, String timestamp, String sig, StackMobOptions options, StackMobRawCallback callback) login to StackMob with gigya credentials.
boolean	isLoggedIn() check whether a user is currently logged in.
boolean	isLoggedOut() check whether the user is logged out.
boolean	isUserLoggedIn(String username) check if a specific user is logged in.
void	linkUserWithFacebookToken(String token, StackMobRawCallback callback) link an existing StackMob user with an existing Facebook user via Facebook credentials.
void	linkUserWithTwitterToken(String token, String secret, StackMobRawCallback callback) link an existing StackMob user with an existing Twitter user via Twitter credentials.
void	login(Map<String,String> params, StackMobOptions options, StackMobRawCallback callback) call the login method on StackMob
void	login(Map<String,String> params, StackMobRawCallback callback) call the login method on StackMob
void	logout(StackMobRawCallback callback) call the logout method on StackMob, invalidating your credentials.
void	refreshLogin(StackMobRawCallback callback) Refresh the current OAuth2 login.
boolean	refreshRequired() check whether a refreshLogin(com.stackmob.sdk.callback.StackMobRawCallback) call is required to continue making authenticated requests.
void	registerWithFacebookToken(String token, String username, StackMobRawCallback callback) create a new user on StackMob and associate it with an existing Facebook user via Facebook credentials.
void	registerWithTwitterToken(String token, String secret, String username, StackMobRawCallback callback) create a new user on StackMob and associate it with an existing Twitter user via Twitter credentials.
void	resetPassword(String oldPassword, String newPassword, StackMobRawCallback callback) reset the logged in user's password
void	setSession(StackMobSession session) set a specific session
static void	setStackMob(StackMob stackmob) Set the singleton StackMob to a particular one for convenience.
void	twitterLogin(String token, String secret, StackMobOptions options, StackMobRawCallback callback) login to StackMob with twitter credentials.
void	twitterLogin(String token, String secret, StackMobRawCallback callback) login to StackMob with twitter credentials.
void	twitterStatusUpdate(String message, StackMobRawCallback callback) update the logged in users’s Twitter status.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_API_HOST

public static String DEFAULT_API_HOST

DEFAULT_USER_SCHEMA_NAME

public static String DEFAULT_USER_SCHEMA_NAME

DEFAULT_USER_ID

public static String DEFAULT_USER_ID

DEFAULT_PASSWORD_FIELD

public static String DEFAULT_PASSWORD_FIELD

DEFAULT_REDIRECTED_CALLBACK

public static StackMobRedirectedCallback DEFAULT_REDIRECTED_CALLBACK

userRedirectedCallback

protected StackMobRedirectedCallback userRedirectedCallback

The redirected callback set by the user

redirectedCallback

protected StackMobRedirectedCallback redirectedCallback

An internal redirected callback.

Constructor Detail

StackMob

public StackMob(Integer apiVersionNumber,
                String apiKey)

a StackMob constructor allowing you to specify the OAuth version.

Parameters:

apiVersionNumber - the version of your app's API that you want to use with this StackMob session. pass 0 for sandbox

apiKey - the api key for your app

StackMob

public StackMob(StackMob.OAuthVersion oauthVersion,
                Integer apiVersionNumber,
                String apiKey,
                String apiSecret)

a StackMob constructor allowing you to specify the OAuth version.

Parameters:

oauthVersion - whether to use oauth1 or oauth2

apiVersionNumber - the version of your app's API that you want to use with this StackMob session. pass 0 for sandbox

apiKey - the api key for your app

apiSecret - the api secret for your app

StackMob

public StackMob(StackMob.OAuthVersion oauthVersion,
                Integer apiVersionNumber,
                String apiKey,
                String apiSecret,
                String apiHost,
                String userSchema,
                String userIdName,
                String passwordFieldName,
                StackMobRedirectedCallback redirectedCallback)

the most complete StackMob constructor allowing you to set values for everything

Parameters:

oauthVersion - whether to use oauth1 or oauth2

apiVersionNumber - the version of your app's API that you want to use with this StackMob session. pass 0 for sandbox

apiKey - the api key for your app

apiSecret - the api secret for your app. Can be null if you're using OAuth2

apiHost - the base of the url for api requests

userSchema - the name of your app's user object. if you do not have a user object, pass the empty strinrg here and do not use the login, logout, facebook or twitter methods, as they will fail

userIdName - the name of your app's user object primary key

passwordFieldName - the name of your app's user object primary key

redirectedCallback - callback to be called if the StackMob platform issues a redirect. you should use this callback to cache the new URLs. here is a sample callback: new StackMobRedirectedCallback() { public void redirected(HttpRequest origRequest, HttpResponse response, HttpRequest newRequest) { try { URI uri = new URI(newRequest.getRequestLine().getUri()); cache(uri.getHost); } catch (URISyntaxException e) { handleException(e); } } } } note that this callback may be called in a background thread

StackMob

public StackMob(StackMob other)

Copy constructor

Parameters:

other - the StackMob to copy

Method Detail

getVersion

public static String getVersion()

The current android sdk version

Returns:

the android sdk version

getStackMob

public static StackMob getStackMob()

Get the singleton StackMob object.

Returns:

the singleton StackMob

setStackMob

public static void setStackMob(StackMob stackmob)

Set the singleton StackMob to a particular one for convenience.

Parameters:

stackmob - the new singleton

getDatastore

public StackMobDatastore getDatastore()

login

public void login(Map<String,String> params,
                  StackMobRawCallback callback)

call the login method on StackMob

Parameters:

params - parameters to pass to the login method

callback - callback to be called when the server returns. may execute in a separate thread

login

public void login(Map<String,String> params,
                  StackMobOptions options,
                  StackMobRawCallback callback)

call the login method on StackMob

Parameters:

params - parameters to pass to the login method

options - additional options, such as headers, to modify the request

callback - callback to be called when the server returns. may execute in a separate thread

refreshLogin

public void refreshLogin(StackMobRawCallback callback)

Refresh the current OAuth2 login. This ordinarily happens automatically, but this method can give you finer control if you need it. Logins last an hour by default. Once they expire they need to be refreshed. Make sure not to send multiple refresh token requests.

Parameters:

callback - callback to be called when the server returns. may execute in a separate thread

logout

public void logout(StackMobRawCallback callback)

call the logout method on StackMob, invalidating your credentials.

Parameters:

callback - callback to be called when the server returns. may execute in a separate thread

twitterLogin

public void twitterLogin(String token,
                         String secret,
                         StackMobRawCallback callback)

login to StackMob with twitter credentials. The credentials should match a existing user object that has a linked Twitter account, via either registerWithTwitterToken(String, String, String, com.stackmob.sdk.callback.StackMobRawCallback) or linkUserWithTwitterToken(String, String, com.stackmob.sdk.callback.StackMobRawCallback)

Parameters:

token - the twitter session key (this is a per user key - different from the consumer key)

secret - the twitter session secret (this is a per user secret - different from the consumer secret)

callback - callback to be called when the server returns. may execute in a separate thread

twitterLogin

public void twitterLogin(String token,
                         String secret,
                         StackMobOptions options,
                         StackMobRawCallback callback)

login to StackMob with twitter credentials. The credentials should match a existing user object that has a linked Twitter account, via either registerWithTwitterToken(String, String, String, com.stackmob.sdk.callback.StackMobRawCallback) or linkUserWithTwitterToken(String, String, com.stackmob.sdk.callback.StackMobRawCallback)

Parameters:

token - the twitter session key (this is a per user key - different from the consumer key)

secret - the twitter session secret (this is a per user secret - different from the consumer secret)

options - additional options, such as headers, to modify the request

callback - callback to be called when the server returns. may execute in a separate thread

twitterStatusUpdate

public void twitterStatusUpdate(String message,
                                StackMobRawCallback callback)

update the logged in users’s Twitter status. The logged in user must have a linked Twitter account.

Parameters:

message - the message to send. must be <= 140 characters

callback - callback to be called when the server returns. may execute in a separate thread

registerWithTwitterToken

public void registerWithTwitterToken(String token,
                                     String secret,
                                     String username,
                                     StackMobRawCallback callback)

create a new user on StackMob and associate it with an existing Twitter user via Twitter credentials.

Parameters:

token - the twitter session key (this is a per user key - different from the consumer key)

secret - the twitter session secret (this is a per user secret - different from the consumer secret)

username - the username that the user should have

callback - callback to be called when the server returns. may execute in a separate thread

linkUserWithTwitterToken

public void linkUserWithTwitterToken(String token,
                                     String secret,
                                     StackMobRawCallback callback)

link an existing StackMob user with an existing Twitter user via Twitter credentials.

Parameters:

token - the twitter session key (this is a per user key - different from the consumer key)

secret - the twitter session secret (this is a per user secret - different from the consumer secret)

callback - callback to be called when the server returns. may execute in a separate thread

facebookLogin

public void facebookLogin(String token,
                          StackMobRawCallback callback)

login to StackMob with Facebook credentials. The credentials should match a existing user object that has a linked Facebook account, via either registerWithFacebookToken(String, String, com.stackmob.sdk.callback.StackMobRawCallback) or linkUserWithFacebookToken(String, com.stackmob.sdk.callback.StackMobRawCallback)

Parameters:

token - the facebook user token

callback - callback to be called when the server returns. may execute in a separate thread

facebookLogin

public void facebookLogin(String token,
                          StackMobOptions options,
                          StackMobRawCallback callback)

login to StackMob with Facebook credentials. The credentials should match a existing user object that has a linked Facebook account, via either registerWithFacebookToken(String, String, com.stackmob.sdk.callback.StackMobRawCallback) or linkUserWithFacebookToken(String, com.stackmob.sdk.callback.StackMobRawCallback)

Parameters:

token - the facebook user token

options - additional options, such as headers, to modify the request

callback - callback to be called when the server returns. may execute in a separate thread

registerWithFacebookToken

public void registerWithFacebookToken(String token,
                                      String username,
                                      StackMobRawCallback callback)

create a new user on StackMob and associate it with an existing Facebook user via Facebook credentials.

Parameters:

token - the facebook user token

username - the StackMob username that the new user should have

callback - callback to be called when the server returns. may execute in a separate thread

linkUserWithFacebookToken

public void linkUserWithFacebookToken(String token,
                                      StackMobRawCallback callback)

link an existing StackMob user with an existing Facebook user via Facebook credentials.

Parameters:

token - the Facebook user token

callback - callback to be called when the server returns. may execute in a separate thread

facebookPostMessage

public void facebookPostMessage(String msg,
                                StackMobRawCallback callback)

post a message to Facebook. This method will not post to FB and will return nothing if there is no user logged into FB.

Parameters:

msg - the message to post

callback - callback to be called when the server returns. may execute in a separate thread

gigyaLogin

public void gigyaLogin(String gigyaUid,
                       String timestamp,
                       String sig,
                       StackMobOptions options,
                       StackMobRawCallback callback)

login to StackMob with gigya credentials. If a corresponding StackMob user didn't exist before, it will be created.

Parameters:

gigyaUid - The parameter UID

timestamp - The parameter signatureTimestamp

sig - The parameter UIDSignature

options - additional options, such as headers, to modify the request

callback - callback to be called when the server returns. may execute in a separate thread

getFacebookUserInfo

public void getFacebookUserInfo(StackMobRawCallback callback)

get facebook user info for the current user. this method will return nothing if there is no currently logged in FB user

Parameters:

callback - callback to be called when the server returns. may execute in a separate thread

getTwitterUserInfo

public void getTwitterUserInfo(StackMobRawCallback callback)

get twitter user info for the current user. this method will return nothing if there is no currently logged in twitter user

Parameters:

callback - callback to be called when the server returns. may execute in a separate thread

forgotPassword

public void forgotPassword(String username,
                           StackMobRawCallback callback)

send out a password reset email to a user who's forgotten their password

Parameters:

username - the user who's forgotten their password

callback - callback to be called when the server returns. may execute in a separate thread

resetPassword

public void resetPassword(String oldPassword,
                          String newPassword,
                          StackMobRawCallback callback)

reset the logged in user's password

Parameters:

oldPassword - the old temporary password

newPassword - the new password that the user just created

callback - callback to be called when the server returns. may execute in a separate thread

getLoggedInUser

public void getLoggedInUser(StackMobCallback callback)

Gets the user object for the currently logged in oauth2 user. Invokes the failure callback if there is no logged in user

Parameters:

callback - callback to be called when the server returns. may execute in a separate thread

getLoggedInUser

public void getLoggedInUser(StackMobOptions options,
                            StackMobCallback callback)

Gets the user object for the currently logged in oauth2 user. Invokes the failure callback if there is no logged in user

Parameters:

options - additional options, such as headers, to modify the request

callback - callback to be called when the server returns. may execute in a separate thread

getLoggedInUsername

public String getLoggedInUsername()

get the logged in user locally. This method is deprecated and getLoggedInUser(com.stackmob.sdk.callback.StackMobCallback) should be use instead

Returns:

the logged in user

isLoggedIn

public boolean isLoggedIn()

check whether a user is currently logged in. In rare cases when a user is logged off remotely this may be inaccurate

Returns:

whether the user is logged in

refreshRequired

public boolean refreshRequired()

check whether a refreshLogin(com.stackmob.sdk.callback.StackMobRawCallback) call is required to continue making authenticated requests. This will happen automatically, so there's no reason to check this method unless you're overriding the existing refresh token system. If there are no credentials at all this will be false.

Returns:

whether there's a valid refresh token that can be used to refresh the login

isUserLoggedIn

public boolean isUserLoggedIn(String username)

check if a specific user is logged in. Use getLoggedInUser(com.stackmob.sdk.callback.StackMobCallback) instead

Parameters:

username - the user to check

Returns:

whether that user is logged in

isLoggedOut

public boolean isLoggedOut()

check whether the user is logged out.

Returns:

whether the user is logged out

getSession

public StackMobSession getSession()

get the session that this StackMob object contains

Returns:

the session

setSession

public void setSession(StackMobSession session)

set a specific session

Parameters:

session - the session to set

getExecutor

public ExecutorService getExecutor()

get the executor used for requests

Returns:

the executor

getRedirectedCallback

public StackMobRedirectedCallback getRedirectedCallback()

get the callback used for redirected requests

Returns:

the redirected callback

getOAuthVersion

public StackMob.OAuthVersion getOAuthVersion()

get the OAuthVersion this StackMob object is configured for

Returns:

the current OAuth version

getUserIdName

public String getUserIdName()

the primary key for the user object

Returns:

the user id name

getPasswordField

public String getPasswordField()

the name of the password field in the user object

Returns:

the password field