com.stackmob.sdk.model
Class StackMobModel

java.lang.Object
  com.stackmob.sdk.model.StackMobModel

Direct Known Subclasses:

StackMobUser

public abstract class StackMobModel
extends Object

The base class for StackMob data objects. Extend this class with the fields you want, and you have an object that knows how to synchronize itself with the cloud

 public class Task extends StackMobModel {
     private String name;
     private Date dueDate;
     private int priority;
     private boolean done;

     public Task(String name) {
         super(Task.class);
         this.name = name;
     }

     //Add whatever setters/getters/other functionality you want here
 }
 
 

You can then create objects, manipulate them, and save/load them whenever you want

 Task myTask = new Task("write javadocs");
 myTask.save();

 // ... do other stuff

 myTask.fetch(new StackMobModelCallback() {
     public void success() {
         // The blogPostTask object is now filled in with data.
     }

     public void failure(StackMobException e) {
         // handle failure case
     }
 });
 
 

You can also do complex queries and get model classes back as a result:

 // Add constraints
 StackMobModelQuery<Task> highPriorityQuery = new StackMobModelQuery<Task>(Task.class).field(new StackMobField("priority").isGreaterThanOrEqualTo( 3).isLessThan(6)).fieldIsEqualTo("done", false);

 // Do an actual query
 Task.query(highPriorityQuery, new StackMobQueryCallback<Task>() {
     public void success(List<Task> result) {
         // handle success
     }

     public void failure(StackMobException e) {
         // handle failure
     }
 });
 
 

If you use model classes as fields, you end up with a tree-like structure that you can save/load to any depth

 public class TaskList extends StackMobModel {
     private String name;
     private List<Task> tasks = new ArrayList<Task>();
     public TaskList(String name, List<Task> tasks) {
         super(TaskList.class);
         this.name = name;
         this.tasks = tasks;
     }
 }

 Task javadocsTask = new Task("Write javadocs");
 Task proofreadTask = new Task("Proofread");
 TaskList blogTasks = new TaskList("Blog Tasks", Arrays.asList(blogPostTask, proofreadTask));
 blogTasks.save(StackMobOptions.depthOf(1));
 
 

Fields in a model can be any of the following:

• Java primitives/Strings
• java.util.Date, java.math.BigInteger, java.math.BigDecimal
• StackMobCounter
• Classes extending StackMobModel
• Arrays and java Collections of the above
• StackMobFile and StackMobGeoPoint (these must be set up in the schema first)

Models are not inherently thread-safe; since they're just objects there's nothing to stop you from accessing/modifying fields while fetch is in the middle of updating them, or modifying an array field from different threads and overwriting yourself. It's up to you to use standard thread-safety procedures when dealing with models like you would with any java object. Class and field names must be alphanumeric (no underscores) and at least three characters. If your model class has any required initialization it should happen in a zero args constructor. When objects are created during queries and fetches field initialization may not happen, and other constructors may not be called. By default the name of the schema corresponding to your model on the server is the class name lowercased. To change this, create the following static method in your subclass:

 public static String overrideSchemaName() {
     return "thenameyouwant";
 }
 
 

Field Summary

protected String

id

Constructor Summary

StackMobModel(Class<? extends StackMobModel> actualClass)
create a new model of the specified class.

StackMobModel(String id, Class<? extends StackMobModel> actualClass)
create a new model of the specified class with an id overriding the default, automatically generated one.

Method Summary

<T extends StackMobModel> void	append(String field, List<T> objs, StackMobCallback callback) append model objects to a collection field in this object.
<T extends StackMobModel> void	appendAndSave(String field, List<T> objs, StackMobCallback callback) append model objects to a collection field in this object.
static <T extends StackMobModel> void	count(Class<T> theClass, StackMobQuery q, StackMobCountCallback callback) run a count query on the server to count all the instances of your model within certain constraints
static <T extends StackMobModel> void	count(StackMob stackmob, Class<T> theClass, StackMobQuery q, StackMobCountCallback callback) run a count query on the server to count all the instances of your model within certain constraints
void	destroy() delete the object from the server
void	destroy(StackMobCallback callback) delete the object from the server
void	exists(StackMobExistsCallback callback)
void	fetch(StackMobCallback callback) Reload the object from the server.
void	fetch(StackMobOptions options, StackMobCallback callback) Reload the object from the server.
void	fillFromJson(String jsonString) fill the objects fields in from a json string.
String	getID() get the object's id.
String	getIDFieldName() Determines the field name for the primary key on the server.
protected String	getSchemaName() The name of the schema this object corresponds to on the server.
boolean	hasData() Check if the object has been loaded with data or if it's just a stub with an id.
protected void	init(Class<? extends StackMobModel> actualClass)
static <T extends StackMobModel> T	newFromJson(StackMob stackmob, Class<T> classOfT, String json) create a new instance of the specified model class from a json string.
static <T extends StackMobModel> void	query(Class<T> theClass, StackMobQuery q, StackMobOptions options, StackMobQueryCallback<T> callback) run a query on the server to get all the instances of your model within certain constraints
static <T extends StackMobModel> void	query(Class<T> theClass, StackMobQuery q, StackMobQueryCallback<T> callback) run a query on the server to get all the instances of your model within certain constraints
static <T extends StackMobModel> void	query(StackMob stackmob, Class<T> theClass, StackMobQuery q, StackMobOptions options, StackMobQueryCallback<T> callback) run a query on the server to get all the instances of your model within certain constraints
static <T extends StackMobModel> void	query(StackMob stackmob, Class<T> theClass, StackMobQuery q, StackMobQueryCallback<T> callback) run a query on the server to get all the instances of your model within certain constraints
<T extends StackMobModel> void	remove(String field, List<T> objs, StackMobCallback callback) remove values from a collection on the client and server.
<T extends StackMobModel> void	removeAndDelete(String field, List<T> objs, StackMobCallback callback) remove objects from a collection and delete them on the client and server.
void	save() Save the object to the server
void	save(StackMobCallback callback) Save the object to the server
void	save(StackMobOptions options) Save the object to the server with options.
void	save(StackMobOptions options, StackMobCallback callback) Save the object to the server with options.
static <T extends StackMobModel> void	saveMultiple(List<T> models, StackMobCallback callback) save multiple objects in one batch.
static <T extends StackMobModel> void	saveMultiple(StackMob stackmob, List<T> models, StackMobCallback callback) save multiple objects in one batch.
void	setID(String id) set the object's id.
void	setStackMob(StackMob stackmob) Have this model use a specific StackMob instance when making requests.
String	toJson() Converts the model into its Json representation.
String	toJson(StackMobOptions options) Converts the model into its Json representation, expanding any sub-objects to the given depth.
protected com.google.gson.JsonElement	toJsonElement(int depth, com.stackmob.sdk.model.StackMobModel.Selection selection, com.stackmob.sdk.util.TypeHints relationHints, com.stackmob.sdk.util.TypeHints typeHints)

Methods inherited from class java.lang.Object

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

Field Detail

id

protected transient String id

Constructor Detail

StackMobModel

public StackMobModel(String id,
                     Class<? extends StackMobModel> actualClass)

create a new model of the specified class with an id overriding the default, automatically generated one. This should be called by the subclass constructor.

Parameters:

actualClass - The subclass, specified because of type erasure

StackMobModel

public StackMobModel(Class<? extends StackMobModel> actualClass)

create a new model of the specified class. This must be called by the subclass constructor.

Parameters:

actualClass - The subclass, specified because of type erasure

Method Detail

query

public static <T extends StackMobModel> void query(Class<T> theClass,
                                                   StackMobQuery q,
                                                   StackMobQueryCallback<T> callback)

run a query on the server to get all the instances of your model within certain constraints

Parameters:

theClass - The class of your model

q - The query to run

callback - The callback to be invoked upon returning

query

public static <T extends StackMobModel> void query(StackMob stackmob,
                                                   Class<T> theClass,
                                                   StackMobQuery q,
                                                   StackMobQueryCallback<T> callback)

run a query on the server to get all the instances of your model within certain constraints

Parameters:

stackmob - The stackmob instance to run requests on

theClass - The class of your model

q - The query to run

callback - The callback to be invoked upon returning

query

public static <T extends StackMobModel> void query(Class<T> theClass,
                                                   StackMobQuery q,
                                                   StackMobOptions options,
                                                   StackMobQueryCallback<T> callback)

run a query on the server to get all the instances of your model within certain constraints

Parameters:

theClass - The class of your model

q - The query to run

options - options, such as select and expand, to apply to the request

callback - The callback to be invoked upon returning

query

public static <T extends StackMobModel> void query(StackMob stackmob,
                                                   Class<T> theClass,
                                                   StackMobQuery q,
                                                   StackMobOptions options,
                                                   StackMobQueryCallback<T> callback)

run a query on the server to get all the instances of your model within certain constraints

Parameters:

stackmob - The stackmob instance to run requests on

theClass - The class of your model

q - The query to run

options - options, such as select and expand, to apply to the request

callback - The callback to be invoked upon returning

count

public static <T extends StackMobModel> void count(Class<T> theClass,
                                                   StackMobQuery q,
                                                   StackMobCountCallback callback)

run a count query on the server to count all the instances of your model within certain constraints

Parameters:

theClass - The class of your model

q - The query to run

callback - The callback to be invoked upon returning

count

public static <T extends StackMobModel> void count(StackMob stackmob,
                                                   Class<T> theClass,
                                                   StackMobQuery q,
                                                   StackMobCountCallback callback)

run a count query on the server to count all the instances of your model within certain constraints

Parameters:

theClass - The class of your model

q - The query to run

callback - The callback to be invoked upon returning

newFromJson

public static <T extends StackMobModel> T newFromJson(StackMob stackmob,
                                                      Class<T> classOfT,
                                                      String json)
                                           throws StackMobException

create a new instance of the specified model class from a json string. Useful if you've serialized a model class for some reason and now want to deserialize it.

Parameters:

classOfT - The class to instantiate

json - The string to deserialize

Returns:

A new instance of the class based on the json

Throws:

StackMobException

saveMultiple

public static <T extends StackMobModel> void saveMultiple(List<T> models,
                                                          StackMobCallback callback)

save multiple objects in one batch. This is equivalent to calling save on each

Type Parameters:

T -

Parameters:

models -

callback -

saveMultiple

public static <T extends StackMobModel> void saveMultiple(StackMob stackmob,
                                                          List<T> models,
                                                          StackMobCallback callback)

save multiple objects in one batch. This is equivalent to calling save on each

Type Parameters:

T -

Parameters:

models -

callback -

setStackMob

public void setStackMob(StackMob stackmob)

Have this model use a specific StackMob instance when making requests. Useful if you want to access more than one StackMob application from the same app

Parameters:

stackmob - the StackMob instance

init

protected void init(Class<? extends StackMobModel> actualClass)

setID

public void setID(String id)

set the object's id. The id is a special field used as a primary key for an object. If not specified this will be automatically generated when the object is saved

Parameters:

id - the primary key of the object

getID

public String getID()

get the object's id. This was either set manually or generated on save

Returns:

the primary key of the object

getSchemaName

protected String getSchemaName()

The name of the schema this object corresponds to on the server. To override, create the following static method in your sublcass: *

 public static String overrideSchemaName() {
     return "thenameyouwant";
 }
 
 

The static method is necessary for the name to be accessible from static method By default it's the name of the class in lower case. Must be less than 25 alphanumeric characters.

Returns:

the schema name

getIDFieldName

public String getIDFieldName()

Determines the field name for the primary key on the server. By default it's the name of the class in lower case plus "_id". Override in subclasses to change that. Must be 3-25 alphanumeric characters

Returns:

the id field name

hasData

public boolean hasData()

Check if the object has been loaded with data or if it's just a stub with an id. Objects can end up as stubs if you load an object tree to less than its full depth. Objects without data shouldn't be used except to check the id or fetch data

Returns:

whether or not this object has data

fillFromJson

public void fillFromJson(String jsonString)
                  throws StackMobException

fill the objects fields in from a json string. This isn't necessary during normal usage of a model class, but can be useful if you've had to serialize the class for some reason

Parameters:

jsonString - a json string as produced by toJson()

Throws:

StackMobException

toJsonElement

protected com.google.gson.JsonElement toJsonElement(int depth,
                                                    com.stackmob.sdk.model.StackMobModel.Selection selection,
                                                    com.stackmob.sdk.util.TypeHints relationHints,
                                                    com.stackmob.sdk.util.TypeHints typeHints)

toJson

public String toJson()

Converts the model into its Json representation. This method is used internally while communicating with the cloud, but can also come in handy anytime you need a string representation of your model objects, such as passing them around in Intents on Android.

Returns:

a json representation of the object

toJson

public String toJson(StackMobOptions options)

Converts the model into its Json representation, expanding any sub-objects to the given depth. Be sure to use the right depth, or you'll end up with empty sub-objects.

Parameters:

options - options, such and select and expand, to apply to the request

Returns:

a json representation of the object and its children to the depth

fetch

public void fetch(StackMobCallback callback)

Reload the object from the server. This is not thread safe, make sure the object isn't disturbed during the load.

Parameters:

callback - invoked when the load is complete

fetch

public void fetch(StackMobOptions options,
                  StackMobCallback callback)

Reload the object from the server. Use StackMobOptions#depthOf(int) to also save its children to the given depth. This is not thread safe, make sure the object isn't disturbed during the load.

Parameters:

options - options, such and select and expand, to apply to the request

callback - invoked when the load is complete

save

public void save()

Save the object to the server

save

public void save(StackMobOptions options)

Save the object to the server with options. Use StackMobOptions#depthOf(int) to also save its children to the given depth.

Parameters:

options - options, such and select and expand, to apply to the request

save

public void save(StackMobCallback callback)

Save the object to the server

Parameters:

callback - invoked when the save is complete

save

public void save(StackMobOptions options,
                 StackMobCallback callback)

Save the object to the server with options. Use StackMobOptions#depthOf(int) to also save its children to the given depth.

Parameters:

options - options, such and select and expand, to apply to the request

callback - invoked when the save is complete

destroy

public void destroy()

delete the object from the server

destroy

public void destroy(StackMobCallback callback)

delete the object from the server

Parameters:

callback - invoked when the delete is complete

exists

public void exists(StackMobExistsCallback callback)

append

public <T extends StackMobModel> void append(String field,
                                             List<T> objs,
                                             StackMobCallback callback)

append model objects to a collection field in this object. The items must match the type of the array, or an exception will be thrown. The objects should already exist on the server; to append and create objects, use appendAndSave(String, java.util.List, com.stackmob.sdk.callback.StackMobCallback). The items will be added to the list both locally and on the server.

Type Parameters:

T - the type of objects being appended

Parameters:

field - the name of the field to append to. The field must be a java Collection

objs - the objects to append to

callback - invoked when the append is complete

Throws:

IllegalArgumentException - if the type of the field doesn't match the input objects

appendAndSave

public <T extends StackMobModel> void appendAndSave(String field,
                                                    List<T> objs,
                                                    StackMobCallback callback)

append model objects to a collection field in this object. The items must match the type of the array, or an exception will be thrown. The objects will be created and also added as children of this object both locally and on the server.

Type Parameters:

T - the type of objects being appended

Parameters:

field - the name of the field to append to. The field must be a java Collection

objs - the objects to append to

callback - invoked when the append is complete

Throws:

IllegalArgumentException - if the type of the field doesn't match the input objects

remove

public <T extends StackMobModel> void remove(String field,
                                             List<T> objs,
                                             StackMobCallback callback)

remove values from a collection on the client and server. The items must match the type of the array, or an exception will be thrown.

Type Parameters:

T - the type of objects being removed

Parameters:

field - the name of the field to remove from. The field must be a java Collection

objs - the objects to remove from

callback - invoked when the remove is complete

Throws:

IllegalArgumentException - if the type of the field doesn't match the input objects

removeAndDelete

public <T extends StackMobModel> void removeAndDelete(String field,
                                                      List<T> objs,
                                                      StackMobCallback callback)

remove objects from a collection and delete them on the client and server. The items must match the type of the array, or an exception will be thrown.

Type Parameters:

T - the type of objects being removed

Parameters:

field - the name of the field to remove from. The field must be a java Collection

objs - the objects to remove from

callback - invoked when the remove is complete

Throws:

IllegalArgumentException - if the type of the field doesn't match the input objects