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
• Social Network 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, boolean createUser, String username, StackMobOptions options, 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 has forgotten their password.
StackMobDatastore	getDatastore() Access Datastore API methods
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() Deprecated.
StackMob.OAuthVersion	getOAuthVersion() Get the OAuthVersion that is set for this StackMob object.
String	getPasswordField() Get the name of the password field in the user object.
StackMobRedirectedCallback	getRedirectedCallback() Get the callback used for redirected requests.
StackMobSession	getSession() Get the session contained by this StackMob object.
static StackMob	getStackMob() Get the singleton StackMob object.
void	getTwitterUserInfo(StackMobRawCallback callback) Get Twitter user info for the current user.
String	getUserIdName() Get the primary key for this 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 current 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	linkUserWithGigya(String gigyaUid, String timestamp, String sig, StackMobRawCallback callback) Link an existing StackMob user with an existing Gigya user via Gigya 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 the current user's 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, boolean createUser, String username, StackMobOptions options, StackMobRawCallback callback) Login to StackMob with Twitter credentials.
void	twitterStatusUpdate(String message, StackMobRawCallback callback) Update the logged-in user’s Twitter status.
void	unlinkUserFromFacebook(StackMobRawCallback callback) Unlink the logged-in user from their Facebook token, if linked.
void	unlinkUserFromGigya(StackMobRawCallback callback) Unlink the logged-in user from their Gigya token, if linked.
void	unlinkUserFromTwitter(StackMobRawCallback callback) Unlink the logged-in user from their Twitter token, if linked.

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 string 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()

Access Datastore API methods

Returns:

a StackMobDatastore instance with the same credentials

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 normally 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 the current user's 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,
                         boolean createUser,
                         String username,
                         StackMobOptions options,
                         StackMobRawCallback callback)

Login to StackMob with Twitter credentials. The method includes the option to create a StackMob user if one didn't exist before. Otherwise, the credentials should match an existing StackMob user object with 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)

createUser - pass true to create a new user if no existing user is associated with the provided tokens. This works with OAuth2 only.

username - if createUser is true, the primary key (username) to give the created user.

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 user’s Twitter status. The logged-in user must be linked with a 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 app's consumer key)

secret - the Twitter session secret (this is a per-user secret, different from the app's consumer secret)

username - the username that the StackMob 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 app's consumer key)

secret - the Twitter session secret (this is a per-user secret, different from the app's consumer secret)

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

unlinkUserFromTwitter

public void unlinkUserFromTwitter(StackMobRawCallback callback)

Unlink the logged-in user from their Twitter token, if linked.

Parameters:

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

facebookLogin

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

Login to StackMob with Facebook credentials. The method includes the option to create a StackMob user if one didn't exist before. Otherwise, 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

createUser - pass true to create a new user if no existing user is associated with the provided token. This works with OAuth2 only.

username - if createUser is true, the primary key (username) to give the created user.

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.

unlinkUserFromFacebook

public void unlinkUserFromFacebook(StackMobRawCallback callback)

Unlink the logged-in user from their Facebook token, if linked.

Parameters:

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. If there is no user logged into Facebook, this method will not post to Facebook and will return nothing.

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.

linkUserWithGigya

public void linkUserWithGigya(String gigyaUid,
                              String timestamp,
                              String sig,
                              StackMobRawCallback callback)

Link an existing StackMob user with an existing Gigya user via Gigya credentials.

Parameters:

gigyaUid - The parameter UID

timestamp - The parameter signatureTimestamp

sig - The parameter UIDSignature

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

unlinkUserFromGigya

public void unlinkUserFromGigya(StackMobRawCallback callback)

Unlink the logged-in user from their Gigya token, if linked.

Parameters:

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 Facebook 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 has 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

@Deprecated
public String getLoggedInUsername()

Deprecated.

Get the logged-in user's username, or null if there is no logged-in user. This method is deprecated and getLoggedInUser(com.stackmob.sdk.callback.StackMobCallback) should be used 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 current user is logged out.

Returns:

whether the current user is logged out

getSession

public StackMobSession getSession()

Get the session contained by this StackMob object.

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 that is set for this StackMob object.

Returns:

the current OAuth version

getUserIdName

public String getUserIdName()

Get the primary key for this user object.

Returns:

the user id name

getPasswordField

public String getPasswordField()

Get the name of the password field in the user object.

Returns:

the password field