com.parse
Class ParseObject

Object
  extended by com.parse.ParseObject
Direct Known Subclasses:
ParseInstallation, ParseRole, ParseUser

public class ParseObject
extends Object

The ParseObject is a local representation of data that can be saved and retrieved from the Parse cloud.

The basic workflow for creating new data is to construct a new ParseObject, use put() to fill it with data, and then use save() to persist to the database.

The basic workflow for accessing existing data is to use a ParseQuery to specify which existing data to retrieve.


Field Summary
protected  LinkedList<Map<String,com.parse.ParseFieldOperation>> operationSetQueue
           
 
Constructor Summary
ParseObject(String theClassName)
          Constructs a new ParseObject with no data in it.
 
Method Summary
 void add(String key, Object value)
          Atomically adds an object to the end of the array associated with a given key.
 void addAll(String key, Collection<?> values)
          Atomically adds the objects contained in a Collection to the end of the array associated with a given key.
 void addAllUnique(String key, Collection<?> values)
          Atomically adds the objects contained in a Collection to the array associated with a given key, only adding elements which are not already present in the array.
 void addUnique(String key, Object value)
          Atomically adds an object to the array associated with a given key, only if it is not already present in the array.
protected  void checkForChangesToMutableContainers()
          Inspects to see if any mutable container owned by this object has been mutated, and treats any mutation as a new put() call.
protected  void clearChanges()
          Removes all operations that have been performed on this object since its last save.
protected  com.parse.ParseCommand constructSaveCommand()
           
 boolean containsKey(String key)
          Whether this object has a particular key.
protected  void copyChangesFrom(ParseObject other)
          Copies all of the operations that have been performed on another object since its last save onto this one.
static ParseObject create(String className)
          Creates a new ParseObject based upon a class name.
static ParseObject createWithoutData(String className, String objectId)
          Creates a reference to an existing ParseObject for use in creating associations between ParseObjects.
 void delete()
          Deletes this object on the server.
 void deleteEventually()
          Deletes this object from the server at some unspecified time in the future, even if Parse is currently inaccessible.
 void deleteEventually(DeleteCallback callback)
          Deletes this object from the server at some unspecified time in the future, even if Parse is currently inaccessible.
 void deleteInBackground()
          Deletes this object on the server in a background thread.
 void deleteInBackground(DeleteCallback callback)
          Deletes this object on the server in a background thread.
 ParseObject fetch()
          Fetches this object with the data from the server.
static List<ParseObject> fetchAll(List<ParseObject> objects)
          Fetches all the objects in the provided list.
static List<ParseObject> fetchAllIfNeeded(List<ParseObject> objects)
          Fetches all the objects that don't have data in the provided list.
static void fetchAllIfNeededInBackground(List<ParseObject> objects, FindCallback callback)
          Fetches all the objects that don't have data in the provided list in the background
static void fetchAllInBackground(List<ParseObject> objects, FindCallback callback)
          Fetches all the objects in the provided list in the background
 ParseObject fetchIfNeeded()
          If this ParseObject has not been fetched (i.e.
 void fetchIfNeededInBackground(GetCallback callback)
          If this ParseObject has not been fetched (i.e.
 void fetchInBackground(GetCallback callback)
          Fetches this object with the data from the server in a background thread.
 Object get(String key)
          Access a value.
 ParseACL getACL()
          Access the ParseACL governing this object.
 boolean getBoolean(String key)
          Access a boolean value.
 byte[] getBytes(String key)
          Access a byte array value.
 String getClassName()
          Accessor to the class name.
 Date getCreatedAt()
          This reports time as the server sees it, so that if you create a ParseObject, then wait a while, and then call save(), the creation time will be the time of the first save() call rather than the time the object was created locally.
 Date getDate(String key)
          Access a Date value.
 double getDouble(String key)
          Access a double value.
 int getInt(String key)
          Access an int value.
 JSONArray getJSONArray(String key)
          Access a JSONArray value.
 JSONObject getJSONObject(String key)
          Access a JSONObject value.
<T> List<T>
getList(String key)
          Access a List value.
 long getLong(String key)
          Access a long value.
<V> Map<String,V>
getMap(String key)
          Access a Map value
 Number getNumber(String key)
          Access a numerical value.
 String getObjectId()
          Accessor to the object id.
 String getOrCreateLocalId()
          Returns the localId, which is used internally for serializing relations to objects that don't yet have an objectId.
 ParseGeoPoint getParseGeoPoint(String key)
          Access a ParseGeoPoint value.
 ParseObject getParseObject(String key)
          Access a ParseObject value.
 ParseUser getParseUser(String key)
          Access a ParseUser value.
 ParseRelation getRelation(String key)
          Access or create a Relation value for a key
 String getString(String key)
          Access a string value.
 Date getUpdatedAt()
          This reports time as the server sees it, so that if you make changes to a ParseObject, then wait a while, and then call save(), the updated time will be the time of the save() call rather than the time the object was changed locally.
 boolean has(String key)
          Whether this object has a particular key.
 boolean hasSameId(ParseObject other)
           
 void increment(String key)
          Atomically increments the given key by 1.
 void increment(String key, Number amount)
          Atomically increments the given key by the given number.
 boolean isDataAvailable()
          Gets whether the ParseObject has been fetched.
protected  boolean isDirty()
           
 Set<String> keySet()
          Returns a set view of the keys contained in this object.
protected  void mergeAfterFetch(JSONObject result)
           
protected  void mergeFromObject(ParseObject other)
           
protected  void mergeFromServer(JSONObject object)
           
 void put(String key, Object value)
          Add a key-value pair to this object.
 void refresh()
          Refreshes this object with the data from the server.
 void refreshInBackground(RefreshCallback callback)
          Refreshes this object with the data from the server in a background thread.
 void remove(String key)
          Removes a key from this object's data if it exists.
 void removeAll(String key, Collection<?> values)
          Atomically removes all instances of the objects contained in a Collection from the array associated with a given key.
 void save()
          Saves this object to the server.
static void saveAll(List<ParseObject> objects)
          Saves each object in the provided list.
static void saveAllInBackground(List<ParseObject> objects)
          Saves each object to the server in a background thread.
static void saveAllInBackground(List<ParseObject> objects, SaveCallback callback)
          Saves each object in the provided list to the server in a background thread.
 void saveEventually()
          Saves this object to the server at some unspecified time in the future, even if Parse is currently inaccessible.
 void saveEventually(SaveCallback callback)
          Saves this object to the server at some unspecified time in the future, even if Parse is currently inaccessible.
 void saveInBackground()
          Saves this object to the server in a background thread.
 void saveInBackground(SaveCallback callback)
          Saves this object to the server in a background thread.
 void setACL(ParseACL acl)
          Set the ParseACL governing this object.
 void setObjectId(String newObjectId)
          Setter for the object id.
protected  void startSave()
           
protected  JSONObject toJSONObjectForSaving()
          Converts a ParseObject to a JSON representation for saving to Parse.
protected  void validateDelete()
           
protected  void validateSave()
           
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

operationSetQueue

protected final LinkedList<Map<String,com.parse.ParseFieldOperation>> operationSetQueue
Constructor Detail

ParseObject

public ParseObject(String theClassName)
Constructs a new ParseObject with no data in it. A ParseObject constructed in this way will not have an objectId and will not persist to the database until save() is called.

Class names must be alphanumerical plus underscore, and start with a letter. It is recommended to name classes in CamelCaseLikeThis.

Parameters:
theClassName - The className for this ParseObject.
Method Detail

create

public static ParseObject create(String className)
Creates a new ParseObject based upon a class name. If the class name is a special type (e.g. for ParseUser), then the appropriate type of ParseObject is returned.

Parameters:
className - The class of object to create.
Returns:
A new ParseObject for the given class name.

createWithoutData

public static ParseObject createWithoutData(String className,
                                            String objectId)
Creates a reference to an existing ParseObject for use in creating associations between ParseObjects. Calling ParseObject.isDataAvailable() on this object will return false until ParseObject.fetchIfNeeded() or ParseObject.refresh() has been called. No network request will be made.

Parameters:
className - The object's class.
objectId - The object id for the referenced object.
Returns:
A ParseObject without data.

getClassName

public String getClassName()
Accessor to the class name.


keySet

public Set<String> keySet()
Returns a set view of the keys contained in this object. This does not include createdAt, updatedAt, authData, or objectId. It does include things like username and ACL.


getUpdatedAt

public Date getUpdatedAt()
This reports time as the server sees it, so that if you make changes to a ParseObject, then wait a while, and then call save(), the updated time will be the time of the save() call rather than the time the object was changed locally.

Returns:
The last time this object was updated on the server.

getCreatedAt

public Date getCreatedAt()
This reports time as the server sees it, so that if you create a ParseObject, then wait a while, and then call save(), the creation time will be the time of the first save() call rather than the time the object was created locally.

Returns:
The first time this object was saved on the server.

clearChanges

protected void clearChanges()
Removes all operations that have been performed on this object since its last save.


copyChangesFrom

protected void copyChangesFrom(ParseObject other)
Copies all of the operations that have been performed on another object since its last save onto this one.


mergeFromObject

protected void mergeFromObject(ParseObject other)

mergeAfterFetch

protected void mergeAfterFetch(JSONObject result)

mergeFromServer

protected void mergeFromServer(JSONObject object)

isDirty

protected boolean isDirty()

checkForChangesToMutableContainers

protected void checkForChangesToMutableContainers()
Inspects to see if any mutable container owned by this object has been mutated, and treats any mutation as a new put() call.


getObjectId

public String getObjectId()
Accessor to the object id. An object id is assigned as soon as an object is saved to the server. The combination of a className and an objectId uniquely identifies an object in your application.

Returns:
The object id.

getOrCreateLocalId

public String getOrCreateLocalId()
Returns the localId, which is used internally for serializing relations to objects that don't yet have an objectId.


setObjectId

public void setObjectId(String newObjectId)
Setter for the object id. In general you do not need to use this. However, in some cases this can be convenient. For example, if you are serializing a ParseObject yourself and wish to recreate it, you can use this to recreate the ParseObject exactly.


constructSaveCommand

protected com.parse.ParseCommand constructSaveCommand()
                                               throws ParseException
Throws:
ParseException

toJSONObjectForSaving

protected JSONObject toJSONObjectForSaving()
Converts a ParseObject to a JSON representation for saving to Parse. { data: { // objectId plus any ParseFieldOperations }, classname: class name for the object } updatedAt and createdAt are not included. only dirty keys are represented in the data.


startSave

protected void startSave()

validateSave

protected void validateSave()

save

public void save()
          throws ParseException
Saves this object to the server. Typically, you should use ParseObject.saveInBackground(com.parse.SaveCallback) instead of this, unless you are managing your own threading.

Throws:
ParseException - Throws an exception if the server is inaccessible.

saveInBackground

public void saveInBackground(SaveCallback callback)
Saves this object to the server in a background thread. This is preferable to using save(), unless your code is already running from a background thread.

Parameters:
callback - callback.done(e) is called when the save completes.

saveInBackground

public void saveInBackground()
Saves this object to the server in a background thread. Use this when you do not have code to run on completion of the push.


saveEventually

public void saveEventually()
Saves this object to the server at some unspecified time in the future, even if Parse is currently inaccessible. Use this when you may not have a solid network connection, and don't need to know when the save completes. If there is some problem with the object such that it can't be saved, it will be silently discarded. Objects saved with this method will be stored locally in an on-disk cache until they can be delivered to Parse. They will be sent immediately if possible. Otherwise, they will be sent the next time a network connection is available. Objects saved this way will persist even after the app is closed, in which case they will be sent the next time the app is opened. If more than 10MB of data is waiting to be sent, subsequent calls to saveEventually or deleteEventually will cause old saves to be silently discarded until the connection can be re-established, and the queued objects can be saved.


saveEventually

public void saveEventually(SaveCallback callback)
Saves this object to the server at some unspecified time in the future, even if Parse is currently inaccessible. Use this when you may not have a solid network connection, and don't need to know when the save completes. If there is some problem with the object such that it can't be saved, it will be silently discarded. Objects saved with this method will be stored locally in an on-disk cache until they can be delivered to Parse. They will be sent immediately if possible. Otherwise, they will be sent the next time a network connection is available. Objects saved this way will persist even after the app is closed, in which case they will be sent the next time the app is opened. If more than 10MB of data is waiting to be sent, subsequent calls to saveEventually or deleteEventually will cause old saves to be silently discarded until the connection can be re-established, and the queued objects can be saved.

Parameters:
callback - - A callback which will be called if the save completes before the app exits.

deleteEventually

public void deleteEventually()
Deletes this object from the server at some unspecified time in the future, even if Parse is currently inaccessible. Use this when you may not have a solid network connection, and don't need to know when the delete completes. If there is some problem with the object such that it can't be deleted, the request will be silently discarded. Delete requests made with this method will be stored locally in an on-disk cache until they can be transmitted to Parse. They will be sent immediately if possible. Otherwise, they will be sent the next time a network connection is available. Delete instructions saved this way will persist even after the app is closed, in which case they will be sent the next time the app is opened. If more than 10MB of commands are waiting to be sent, subsequent calls to deleteEventually or saveEventually will cause old instructions to be silently discarded until the connection can be re-established, and the queued objects can be saved.


deleteEventually

public void deleteEventually(DeleteCallback callback)
Deletes this object from the server at some unspecified time in the future, even if Parse is currently inaccessible. Use this when you may not have a solid network connection, and don't need to know when the delete completes. If there is some problem with the object such that it can't be deleted, the request will be silently discarded. Delete requests made with this method will be stored locally in an on-disk cache until they can be transmitted to Parse. They will be sent immediately if possible. Otherwise, they will be sent the next time a network connection is available. Delete instructions saved this way will persist even after the app is closed, in which case they will be sent the next time the app is opened. If more than 10MB of commands are waiting to be sent, subsequent calls to deleteEventually or saveEventually will cause old instructions to be silently discarded until the connection can be re-established, and the queued objects can be saved.

Parameters:
callback - - A callback which will be called if the delete completes before the app exits.

refresh

public void refresh()
             throws ParseException
Refreshes this object with the data from the server. Call this whenever you want the state of the object to reflect exactly what is on the server.

Throws:
ParseException - Throws an exception if the server is inaccessible.

refreshInBackground

public void refreshInBackground(RefreshCallback callback)
Refreshes this object with the data from the server in a background thread. This is preferable to using refresh(), unless your code is already running from a background thread.

Parameters:
callback - callback.done(object, e) is called when the refresh completes.

fetch

public ParseObject fetch()
                  throws ParseException
Fetches this object with the data from the server. Call this whenever you want the state of the object to reflect exactly what is on the server.

Returns:
The ParseObject that was fetched.
Throws:
ParseException - Throws an exception if the server is inaccessible.

fetchInBackground

public void fetchInBackground(GetCallback callback)
Fetches this object with the data from the server in a background thread. This is preferable to using fetch(), unless your code is already running from a background thread.

Parameters:
callback - callback.done(object, e) is called when the fetch completes.

fetchIfNeeded

public ParseObject fetchIfNeeded()
                          throws ParseException
If this ParseObject has not been fetched (i.e. ParseObject.isDataAvailable() returns false), fetches this object with the data from the server.

Returns:
The fetched ParseObject.
Throws:
ParseException - Throws an exception if the server is inaccessible.

fetchIfNeededInBackground

public void fetchIfNeededInBackground(GetCallback callback)
If this ParseObject has not been fetched (i.e. ParseObject.isDataAvailable() returns false), fetches this object with the data from the server in a background thread. This is preferable to using ParseObject.fetchIfNeeded(), unless your code is already running from a background thread.

Parameters:
callback - callback.done(object, e) is called when the fetch completes.

validateDelete

protected void validateDelete()

delete

public void delete()
            throws ParseException
Deletes this object on the server. This does not delete or destroy the object locally.

Throws:
ParseException - Throws an error if the object does not exist or if the internet fails.

deleteInBackground

public void deleteInBackground(DeleteCallback callback)
Deletes this object on the server in a background thread. This is preferable to using delete(), unless your code is already running from a background thread.

Parameters:
callback - callback.done(e) is called when the save completes.

deleteInBackground

public void deleteInBackground()
Deletes this object on the server in a background thread. Does nothing in particular when the save completes. Use this when you don't care if the delete works.


saveAll

public static void saveAll(List<ParseObject> objects)
                    throws ParseException
Saves each object in the provided list. This is faster than saving each object individually because it batches the requests.

Parameters:
objects - The objects to save.
Throws:
ParseException - Throws an exception if the server returns an error or is inaccessible.

fetchAllIfNeeded

public static List<ParseObject> fetchAllIfNeeded(List<ParseObject> objects)
                                          throws ParseException
Fetches all the objects that don't have data in the provided list.

Parameters:
objects - The list of objects to fetch.
Returns:
The list passed in for convenience.
Throws:
ParseException - Throws an exception if the server returns an error or is inaccessible.

fetchAllIfNeededInBackground

public static void fetchAllIfNeededInBackground(List<ParseObject> objects,
                                                FindCallback callback)
Fetches all the objects that don't have data in the provided list in the background

Parameters:
objects - The list of objects to fetch.
callback - callback.done(result, e) is called when the fetch completes.

fetchAll

public static List<ParseObject> fetchAll(List<ParseObject> objects)
                                  throws ParseException
Fetches all the objects in the provided list.

Parameters:
objects - The list of objects to fetch.
Returns:
The list passed in.
Throws:
ParseException - Throws an exception if the server returns an error or is inaccessible.

fetchAllInBackground

public static void fetchAllInBackground(List<ParseObject> objects,
                                        FindCallback callback)
Fetches all the objects in the provided list in the background

Parameters:
objects - The list of objects to fetch.
callback - callback.done(result, e) is called when the fetch completes.

saveAllInBackground

public static void saveAllInBackground(List<ParseObject> objects,
                                       SaveCallback callback)
Saves each object in the provided list to the server in a background thread. This is preferable to using saveAll, unless your code is already running from a background thread.

Parameters:
objects - The objects to save.
callback - callback.done(e) is called when the save completes.

saveAllInBackground

public static void saveAllInBackground(List<ParseObject> objects)
Saves each object to the server in a background thread. Does nothing in particular when the save completes. Use this when you don't care if the save works.

Parameters:
objects - The objects to save.

remove

public void remove(String key)
Removes a key from this object's data if it exists.

Parameters:
key - The key to remove.

has

public boolean has(String key)
Whether this object has a particular key. Same as containsKey.

Parameters:
key - The key to check for
Returns:
Returns whether this object contains the key

put

public void put(String key,
                Object value)
Add a key-value pair to this object. It is recommended to name keys in partialCamelCaseLikeThis.

Parameters:
key - Keys must be alphanumerical plus underscore, and start with a letter.
value - Values may be numerical, String, JSONObject, JSONArray, JSONObject.NULL, or other ParseObjects. value may not be null.

increment

public void increment(String key)
Atomically increments the given key by 1.

Parameters:
key - The key to increment.

increment

public void increment(String key,
                      Number amount)
Atomically increments the given key by the given number.

Parameters:
key - The key to increment.
amount - The amount to increment by.

add

public void add(String key,
                Object value)
Atomically adds an object to the end of the array associated with a given key.

Parameters:
key - The key.
value - The object to add.

addAll

public void addAll(String key,
                   Collection<?> values)
Atomically adds the objects contained in a Collection to the end of the array associated with a given key.

Parameters:
key - The key.
values - The objects to add.

addUnique

public void addUnique(String key,
                      Object value)
Atomically adds an object to the array associated with a given key, only if it is not already present in the array. The position of the insert is not guaranteed.

Parameters:
key - The key.
value - The object to add.

addAllUnique

public void addAllUnique(String key,
                         Collection<?> values)
Atomically adds the objects contained in a Collection to the array associated with a given key, only adding elements which are not already present in the array. The position of the insert is not guaranteed.

Parameters:
key - The key.
values - The objects to add.

removeAll

public void removeAll(String key,
                      Collection<?> values)
Atomically removes all instances of the objects contained in a Collection from the array associated with a given key. To maintain consistency with the Java Collection API, there is no method removing all instances of a single object. Instead, you can call parseObject.removeAll(key, Arrays.asList(value)).

Parameters:
key - The key.
values - The objects to remove.

containsKey

public boolean containsKey(String key)
Whether this object has a particular key. Same as 'has'.

Parameters:
key - The key to check for
Returns:
Returns whether this object contains the key

getString

public String getString(String key)
Access a string value.

Parameters:
key - The key to access the value for.
Returns:
Returns null if there is no such key or if it is not a String.

getBytes

public byte[] getBytes(String key)
Access a byte array value.

Parameters:
key - The key to access the value for.
Returns:
Returns null if there is no such key or if it is not a byte array.

getNumber

public Number getNumber(String key)
Access a numerical value.

Parameters:
key - The key to access the value for.
Returns:
Returns null if there is no such key or if it is not a Number.

getJSONArray

public JSONArray getJSONArray(String key)
Access a JSONArray value.

Parameters:
key - The key to access the value for.
Returns:
Returns null if there is no such key or if it is not a JSONArray.

getList

public <T> List<T> getList(String key)
Access a List value.

Parameters:
key - The key to access the value for
Returns:
Returns null if there is no such key or if the value can't be converted to a List

getMap

public <V> Map<String,V> getMap(String key)
Access a Map value

Parameters:
key - The key to access the value for
Returns:
Returns null if there is no such key or if the value can't be converted to a Map.

getJSONObject

public JSONObject getJSONObject(String key)
Access a JSONObject value.

Parameters:
key - The key to access the value for.
Returns:
Returns null if there is no such key or if it is not a JSONObject.

getInt

public int getInt(String key)
Access an int value.

Parameters:
key - The key to access the value for.
Returns:
Returns 0 if there is no such key or if it is not a JSONObject.

getDouble

public double getDouble(String key)
Access a double value.

Parameters:
key - The key to access the value for.
Returns:
Returns 0 if there is no such key or if it is not a double.

getLong

public long getLong(String key)
Access a long value.

Parameters:
key - The key to access the value for.
Returns:
Returns 0 if there is no such key or if it is not a long.

getBoolean

public boolean getBoolean(String key)
Access a boolean value.

Parameters:
key - The key to access the value for.
Returns:
Returns false if there is no such key or if it is not a boolean.

getDate

public Date getDate(String key)
Access a Date value.

Parameters:
key - The key to access the value for.
Returns:
Returns null if there is no such key or if it is not a Date.

getParseObject

public ParseObject getParseObject(String key)
Access a ParseObject value. This function will not perform a network request. Unless the ParseObject has been downloaded (e.g. by a ParseQuery.include(String) or by calling ParseObject.fetchIfNeeded() or ParseObject.refresh()), ParseObject.isDataAvailable() will return false.

Parameters:
key - The key to access the value for.
Returns:
Returns null if there is no such key or if it is not a ParseObject.

getParseUser

public ParseUser getParseUser(String key)
Access a ParseUser value. This function will not perform a network request. Unless the ParseObject has been downloaded (e.g. by a ParseQuery.include(String) or by calling ParseObject.fetchIfNeeded() or ParseObject.refresh()), ParseObject.isDataAvailable() will return false.

Parameters:
key - The key to access the value for.
Returns:
Returns null if there is no such key or if it is not a ParseUser.

getParseGeoPoint

public ParseGeoPoint getParseGeoPoint(String key)
Access a ParseGeoPoint value.

Parameters:
key - The key to access the value for
Returns:
Returns null if there is no such key or if it is not a ParseGeoPoint.

getACL

public ParseACL getACL()
Access the ParseACL governing this object.


setACL

public void setACL(ParseACL acl)
Set the ParseACL governing this object.


isDataAvailable

public boolean isDataAvailable()
Gets whether the ParseObject has been fetched.

Returns:
true if the ParseObject is new or has been fetched or refreshed. false otherwise.

getRelation

public ParseRelation getRelation(String key)
Access or create a Relation value for a key

Parameters:
key - The key to access the relation for.
Returns:
the ParseRelation object if the relation already exists for the key or can be created for this key.

get

public Object get(String key)
Access a value. In most cases it is more convenient to use a helper function such as getString or getInt.

Parameters:
key - The key to access the value for.
Returns:
Returns null if there is no such key.
Throws:
Throws - a ParseException if the server could not be reached to load a relational value.

hasSameId

public boolean hasSameId(ParseObject other)