com.stackmob.sdk.api
Class StackMob

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

public class StackMob
extends Object

Nested Class Summary

protected static class

StackMob.RegistrationIDAndUser

Field Summary

protected StackMobRedirectedCallback	redirectedCallback
protected StackMobRedirectedCallback	userRedirectedCallback

Constructor Summary

StackMob(String apiKey, String apiSecret, String userObjectName, Integer apiVersionNumber)
create a new StackMob object

StackMob(String apiKey, String apiSecret, String userObjectName, Integer apiVersionNumber, String urlFormat, StackMobRedirectedCallback redirectedCallback)
create a new StackMob object.

StackMob(String apiKey, String apiSecret, String userObjectName, Integer apiVersionNumber, String apiUrlFormat, String pushUrlFormat, StackMobRedirectedCallback redirectedCallback)

StackMob(String apiKey, String apiSecret, String userObjectName, String appName, Integer apiVersionNumber)
create a new StackMob object.

Method Summary

void	broadcastPushNotification(Map<String,String> payload, StackMobCallback callback) broadcast a push notification to all users of this app.
void	delete(String path, String id, StackMobCallback callback) do a delete request to the stackmob platform
<T> void	deleteIdFrom(String path, String primaryId, String field, T idToDelete, boolean cascadeDelete, StackMobCallback callback) atomically remove elements from an array or has many relationship
<T> void	deleteIdsFrom(String path, String primaryId, String field, List<T> idsToDelete, boolean cascadeDeletes, StackMobCallback callback) atomically remove elements from an array or has many relationship
void	facebookLogin(String token, StackMobCallback callback) login into facebook on the StackMob platform
void	facebookPostMessage(String msg, StackMobCallback callback) post a message to facebook.
void	get(StackMobQuery query, StackMobCallback callback)
void	get(StackMobQueryWithField query, StackMobCallback callback)
void	get(String path, Map<String,String> arguments, Map<String,String> headers, StackMobCallback callback) do a get request on the StackMob platform
void	get(String path, Map<String,String> arguments, StackMobCallback callback)
void	get(String path, StackMobCallback callback) do a get request on the StackMob platform
void	getAndClearExpiredPushTokens(StackMobCallback callback) get all expired push tokens for this app, and clear them after they've been returned
void	getExpiredPushTokens(StackMobCallback callback) get expired push tokens, but do not clear them after they've been returned
void	getFacebookUserInfo(StackMobCallback callback) get facebook user info for the current user.
StackMobSession	getSession() get the session that this StackMob object contains
void	getTokensForUsers(List<String> usernames, StackMobCallback callback) get all the tokens for the each of the given users
void	linkUserWithFacebookToken(String token, StackMobCallback callback) link an existing StackMob user with a Facebook user
void	linkUserWithTwitterToken(String token, String secret, StackMobCallback callback) link an existing stackmob user with an existing twitter user
void	login(Map<String,String> params, StackMobCallback callback) call the login method on StackMob
void	logout(StackMobCallback callback) call the logout method on StackMob
void	post(String path, Object requestObject, StackMobCallback callback) do a post request on the StackMob platform for a single object
<T> void	postBulk(String path, List<T> requestObjects, StackMobCallback callback) do a post request on the StackMob platform with a list of objects
void	postRelated(String path, String primaryId, String relatedField, Object relatedObject, StackMobCallback callback) post a new related object to an existing object.
<T> void	postRelatedBulk(String path, String primaryId, String relatedField, List<T> relatedObjects, StackMobCallback callback) post a list of new related objects to an existing object.
void	pushToTokens(Map<String,String> payload, List<StackMobPushToken> tokens, StackMobCallback callback) send a push notification to a group of tokens
void	pushToUsers(Map<String,String> payload, List<String> userIds, StackMobCallback callback) send a push notification to a group of users.
void	put(String path, String id, Object requestObject, StackMobCallback callback) do a put request on the StackMob platform
<T> void	putRelated(String path, String primaryId, String relatedField, List<T> relatedIds, StackMobCallback callback) do a an atomic put request on the StackMob platform with the contents of the has-many relation
void	registerForPushWithUser(String username, String registrationID, StackMobCallback callback) register a user for C2DM push notifications
void	registerWithFacebookToken(String token, String username, StackMobCallback callback) create a new StackMob user and link that user with a facebook account
void	registerWithTwitterToken(String token, String secret, String username, StackMobCallback callback) create a new user on stackmob and associate it with an existing twitter user
void	removePushToken(String tokenString, StackMobPushToken.TokenType tokenType, StackMobCallback callback) remove a push token for this app
void	startSession(StackMobCallback callback) call the startsession method on StackMob
void	twitterLogin(String token, String secret, StackMobCallback callback) call the twitterlogin method on stackmob
void	twitterStatusUpdate(String message, StackMobCallback callback) call the twitterStatusUpdate method on StackMob

Methods inherited from class java.lang.Object

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

Field Detail

userRedirectedCallback

protected StackMobRedirectedCallback userRedirectedCallback

redirectedCallback

protected StackMobRedirectedCallback redirectedCallback

Constructor Detail

StackMob

public StackMob(String apiKey,
                String apiSecret,
                String userObjectName,
                String appName,
                Integer apiVersionNumber)

create a new StackMob object. this is the preferred constructor

Parameters:

apiKey - the api key for your app

apiSecret - the api secret for your app

userObjectName - 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

appName - the name of your application

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

StackMob

public StackMob(String apiKey,
                String apiSecret,
                String userObjectName,
                Integer apiVersionNumber)

create a new StackMob object

Parameters:

apiKey - the api key for your app

apiSecret - the api secret for your app

userObjectName - 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

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

StackMob

public StackMob(String apiKey,
                String apiSecret,
                String userObjectName,
                Integer apiVersionNumber,
                String urlFormat,
                StackMobRedirectedCallback redirectedCallback)

create a new StackMob object. use this constructor if you do your own caching of URLs for redirection

Parameters:

apiKey - the api key for your app

apiSecret - the api secret for your app

userObjectName - the name of your app's user object

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

urlFormat - the format of URLs to use. for instance: api.mob1.stackmob.com

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(String apiKey,
                String apiSecret,
                String userObjectName,
                Integer apiVersionNumber,
                String apiUrlFormat,
                String pushUrlFormat,
                StackMobRedirectedCallback redirectedCallback)

Method Detail

login

public void login(Map<String,String> params,
                  StackMobCallback 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

logout

public void logout(StackMobCallback callback)

call the logout method on StackMob

Parameters:

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

startSession

public void startSession(StackMobCallback callback)

call the startsession method on StackMob

Parameters:

callback - callback to call when the method completes

twitterLogin

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

call the twitterlogin method on stackmob

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

twitterStatusUpdate

public void twitterStatusUpdate(String message,
                                StackMobCallback callback)

call the twitterStatusUpdate method on StackMob

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,
                                     StackMobCallback callback)

create a new user on stackmob and associate it with an existing twitter user

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,
                                     StackMobCallback callback)

link an existing stackmob user with an existing twitter user

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,
                          StackMobCallback callback)

login into facebook on the StackMob platform

Parameters:

token - the facebook user token

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

registerWithFacebookToken

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

create a new StackMob user and link that user with a facebook account

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,
                                      StackMobCallback callback)

link an existing StackMob user with a Facebook user

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,
                                StackMobCallback 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

getFacebookUserInfo

public void getFacebookUserInfo(StackMobCallback 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

pushToTokens

public void pushToTokens(Map<String,String> payload,
                         List<StackMobPushToken> tokens,
                         StackMobCallback callback)

send a push notification to a group of tokens

Parameters:

payload - the payload of the push notification to send

tokens - the tokens to which to send

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

pushToUsers

public void pushToUsers(Map<String,String> payload,
                        List<String> userIds,
                        StackMobCallback callback)

send a push notification to a group of users.

Parameters:

payload - the payload to send

userIds - the IDs of the users to which to send

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

registerForPushWithUser

public void registerForPushWithUser(String username,
                                    String registrationID,
                                    StackMobCallback callback)

register a user for C2DM push notifications

Parameters:

username - the StackMob username to register

registrationID - the C2DM registration ID. see http://code.google.com/android/c2dm/#registering for detail on how to get this ID

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

getTokensForUsers

public void getTokensForUsers(List<String> usernames,
                              StackMobCallback callback)

get all the tokens for the each of the given users

Parameters:

usernames - the users whose tokens to get

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

broadcastPushNotification

public void broadcastPushNotification(Map<String,String> payload,
                                      StackMobCallback callback)

broadcast a push notification to all users of this app. use this method sparingly, especially if you have a large app

Parameters:

payload - the payload to broadcast

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

getAndClearExpiredPushTokens

public void getAndClearExpiredPushTokens(StackMobCallback callback)

get all expired push tokens for this app, and clear them after they've been returned

Parameters:

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

getExpiredPushTokens

public void getExpiredPushTokens(StackMobCallback callback)

get expired push tokens, but do not clear them after they've been returned

Parameters:

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

removePushToken

public void removePushToken(String tokenString,
                            StackMobPushToken.TokenType tokenType,
                            StackMobCallback callback)

remove a push token for this app

Parameters:

tokenString - the token value

tokenType - the type of the token

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

get

public void get(String path,
                StackMobCallback callback)

do a get request on the StackMob platform

Parameters:

path - the path to get

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

get

public void get(String path,
                Map<String,String> arguments,
                Map<String,String> headers,
                StackMobCallback callback)

do a get request on the StackMob platform

Parameters:

path - the path to get

arguments - arguments to be encoded into the query string of the get request

headers - any additional headers to send

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

get

public void get(String path,
                Map<String,String> arguments,
                StackMobCallback callback)

get

public void get(StackMobQuery query,
                StackMobCallback callback)

get

public void get(StackMobQueryWithField query,
                StackMobCallback callback)

post

public void post(String path,
                 Object requestObject,
                 StackMobCallback callback)

do a post request on the StackMob platform for a single object

Parameters:

path - the path to get

requestObject - the object to serialize and send in the POST body. this object will be serialized with Gson

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

postBulk

public <T> void postBulk(String path,
                         List<T> requestObjects,
                         StackMobCallback callback)

do a post request on the StackMob platform with a list of objects

Parameters:

path - the path to get

requestObjects - List of objects to serialize and send in the POST body. the list will be serialized with Gson

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

postRelated

public void postRelated(String path,
                        String primaryId,
                        String relatedField,
                        Object relatedObject,
                        StackMobCallback callback)

post a new related object to an existing object. the relation of the root object is updated

Parameters:

path - the path to get

primaryId - id of the object with the relation

relatedField - name of the relation

relatedObject - related object to post

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

postRelatedBulk

public <T> void postRelatedBulk(String path,
                                String primaryId,
                                String relatedField,
                                List<T> relatedObjects,
                                StackMobCallback callback)

post a list of new related objects to an existing object. the relation of the root object is updated

Parameters:

path - the path to get

primaryId - id of the object with the relation

relatedField - name of the relation

relatedObjects - list of related objects to post. the list will be serialized with Gson

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

put

public void put(String path,
                String id,
                Object requestObject,
                StackMobCallback callback)

do a put request on the StackMob platform

Parameters:

path - the path to put

id - the id of the object to put

requestObject - the object to serialize and send in the PUT body. this object will be serialized with Gson

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

putRelated

public <T> void putRelated(String path,
                           String primaryId,
                           String relatedField,
                           List<T> relatedIds,
                           StackMobCallback callback)

do a an atomic put request on the StackMob platform with the contents of the has-many relation

Parameters:

path - the path to get

primaryId - id of the object with the relation

relatedField - name of the relation

relatedIds - list of ids to atomically add to the relation. The type should be the same type as the primary key field of the related object

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

delete

public void delete(String path,
                   String id,
                   StackMobCallback callback)

do a delete request to the stackmob platform

Parameters:

path - the path to delete

id - the id of the object to put

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

deleteIdsFrom

public <T> void deleteIdsFrom(String path,
                              String primaryId,
                              String field,
                              List<T> idsToDelete,
                              boolean cascadeDeletes,
                              StackMobCallback callback)

atomically remove elements from an array or has many relationship

Parameters:

path - the path to get

primaryId - id of the object with the relation

field - name of the relation or array field to delete from

idsToDelete - list of ids to atomically remove from field. ids should be same type as the primary id of the related type (most likely String or Integer)

cascadeDeletes - true if related objects specified in idsToDelete should also be deleted

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

deleteIdFrom

public <T> void deleteIdFrom(String path,
                             String primaryId,
                             String field,
                             T idToDelete,
                             boolean cascadeDelete,
                             StackMobCallback callback)

atomically remove elements from an array or has many relationship

Parameters:

path - the path to get

primaryId - id of the object with the relation

field - name of the relation or array field to delete from

idToDelete - id to atomically remove from field. should be same type as the primary id of the related type (most likely String or Integer)

cascadeDelete - true if related object specified in idToDelete should also be deleted

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

getSession

public StackMobSession getSession()

get the session that this StackMob object contains

Returns:

the session