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.


Constructor Summary
protected ParseObject()
          The base class constructor to call in subclasses.
  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.
 boolean containsKey(String key)
          Whether this object has a particular key.
static
<T extends ParseObject>
T
create(Class<T> subclass)
          Creates a new ParseObject based upon a subclass type.
static ParseObject create(String className)
          Creates a new ParseObject based upon a class name.
static
<T extends ParseObject>
T
createWithoutData(Class<T> subclass, String objectId)
          Creates a reference to an existing ParseObject for use in creating associations between ParseObjects.
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.
<T extends ParseObject>
T
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
<T extends ParseObject>
List<T>
fetchAllIfNeeded(List<T> objects)
          Fetches all the objects that don't have data in the provided list.
static
<T extends ParseObject>
void
fetchAllIfNeededInBackground(List<T> objects, FindCallback<T> callback)
          Fetches all the objects that don't have data in the provided list in the background
static
<T extends ParseObject>
void
fetchAllInBackground(List<T> objects, FindCallback<T> 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<ParseObject> callback)
          If this ParseObject has not been fetched (i.e.
<T extends ParseObject>
void
fetchInBackground(GetCallback<T> 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.
 ParseFile getParseFile(String key)
          Access a ParseFile value.
 ParseGeoPoint getParseGeoPoint(String key)
          Access a ParseGeoPoint value.
 ParseObject getParseObject(String key)
          Access a ParseObject value.
 ParseUser getParseUser(String key)
          Access a ParseUser value.
<T extends ParseObject>
ParseRelation<T>
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.
 Set<String> keySet()
          Returns a set view of the keys contained in this 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.
static void registerSubclass(Class<? extends ParseObject> subclass)
          Registers a custom subclass type with the Parse SDK, enabling strong-typing of those ParseObjects whenever they appear.
 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.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ParseObject

protected ParseObject()
The base class constructor to call in subclasses. Uses the class name specified with the ParseClassName annotation on the subclass.


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.

create

public static <T extends ParseObject> T create(Class<T> subclass)
Creates a new ParseObject based upon a subclass type. Note that the object will be created based upon the ParseClassName of the given subclass type. For example, calling create(ParseUser.class) may create an instance of a custom subclass of ParseUser.

Parameters:
subclass - The class of object to create.
Returns:
A new ParseObject based upon the class name of the given subclass type.

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.

createWithoutData

public static <T extends ParseObject> T createWithoutData(Class<T> subclass,
                                                          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:
subclass - The ParseObject subclass to create.
objectId - The object id for the referenced object.
Returns:
A ParseObject without data.

registerSubclass

public static void registerSubclass(Class<? extends ParseObject> subclass)
Registers a custom subclass type with the Parse SDK, enabling strong-typing of those ParseObjects whenever they appear. Subclasses must specify the ParseClassName annotation and have a default constructor.

Parameters:
subclass - The subclass type to register.

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.

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.

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.


save

public final 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 final 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 final 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 final 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 final 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 final 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 final 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 final 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 <T extends ParseObject> T 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 final <T extends ParseObject> void fetchInBackground(GetCallback<T> 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 final void fetchIfNeededInBackground(GetCallback<ParseObject> 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.

delete

public final 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 final 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 final 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 <T extends ParseObject> List<T> fetchAllIfNeeded(List<T> 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 <T extends ParseObject> void fetchAllIfNeededInBackground(List<T> objects,
                                                                        FindCallback<T> 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 <T extends ParseObject> void fetchAllInBackground(List<T> objects,
                                                                FindCallback<T> 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.

getParseFile

public ParseFile getParseFile(String key)
Access a ParseFile value. This function will not perform a network request. Unless the ParseFile has been downloaded (e.g. by calling ParseFile.getData()), ParseFile.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 ParseFile.

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 <T extends ParseObject> ParseRelation<T> 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)