com.google.appengine.api.datastore
Class Entity

java.lang.Object
  com.google.appengine.api.datastore.Entity

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public final class Entity
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

Entity is the fundamental unit of data storage. It has an immutable identifier (contained in the Key) object, a reference to an optional parent Entity, a kind (represented as an arbitrary string), and a set of zero or more typed properties.

See Also:

Serialized Form

Field Summary

static java.lang.String	KEY_RESERVED_PROPERTY A reserved property name used to refer to the key of the entity.
static java.lang.String	SCATTER_RESERVED_PROPERTY A reserved property name used to refer to the scatter property of the entity.

Constructor Summary

Entity(Key key)
Create a new Entity uniquely identified by the provided Key.

Entity(java.lang.String kind)
Create a new Entity with the specified kind and no parent Entity.

Entity(java.lang.String kind, Key parent)
Create a new Entity with the specified kind and parent Entity.

Entity(java.lang.String kind, long id)
Create a new Entity with the specified kind and ID and no parent Entity.

Entity(java.lang.String kind, long id, Key parent)
Create a new Entity with the specified kind and ID and parent Entity.

Entity(java.lang.String kind, java.lang.String keyName)
Create a new Entity with the specified kind and key name and no parent Entity.

Entity(java.lang.String kind, java.lang.String keyName, Key parent)
Create a new Entity with the specified kind, key name, and parent Entity.

Method Summary

Entity	clone() Returns a shallow copy of this Entity instance.
boolean	equals(java.lang.Object object) Two Entity objects are considered equal if they refer to the same entity (i.e.
java.lang.String	getAppId() Returns the identifier of the application that owns this Entity.
Key	getKey() Returns the Key that represents this Entity.
java.lang.String	getKind() Returns a logical type that is associated with this Entity.
java.lang.String	getNamespace() Returns the namespace of the application/namespace that owns this Entity.
Key	getParent() Get a Key that corresponds to this the parent Entity of this Entity.
java.util.Map<java.lang.String,java.lang.Object>	getProperties() Gets all of the properties belonging to this Entity.
java.lang.Object	getProperty(java.lang.String propertyName) Gets the property with the specified name.
int	hashCode()
boolean	hasProperty(java.lang.String propertyName) Returns true if a property has been set.
boolean	isUnindexedProperty(java.lang.String propertyName) Returns true if propertyName has a value that will not be indexed.
void	removeProperty(java.lang.String propertyName) Removes any property with the specified name.
void	setPropertiesFrom(Entity src) A convenience method that populates the properties of this Entity with the properties set on the provided Entity.
void	setProperty(java.lang.String propertyName, java.lang.Object value) Sets the property named, propertyName, to value.
void	setUnindexedProperty(java.lang.String propertyName, java.lang.Object value) Like #setProperty, but doesn't index the property in the built-in single property indexes.
java.lang.String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

KEY_RESERVED_PROPERTY

public static final java.lang.String KEY_RESERVED_PROPERTY

A reserved property name used to refer to the key of the entity. This string can be used for filtering and sorting by the entity key itself.

See Also:

Constant Field Values

SCATTER_RESERVED_PROPERTY

public static final java.lang.String SCATTER_RESERVED_PROPERTY

A reserved property name used to refer to the scatter property of the entity. Used for finding split points (e.g. for mapping over a kind).

See Also:

Constant Field Values

Constructor Detail

Entity

public Entity(java.lang.String kind)

Create a new Entity with the specified kind and no parent Entity. The instantiated Entity will have an incomplete Key when this constructor returns. The Key will remain incomplete until you put the Entity, after which time the Key will have its id set.

Entity

public Entity(java.lang.String kind,
              Key parent)

Create a new Entity with the specified kind and parent Entity. The instantiated Entity will have an incomplete Key when this constructor returns. The Key will remain incomplete until you put the Entity, after which time the Key will have its id set.

Entity

public Entity(java.lang.String kind,
              java.lang.String keyName)

Create a new Entity with the specified kind and key name and no parent Entity. The instantiated Entity will have a complete Key when this constructor returns. The Key's name field will be set to the value of keyName.

This constructor is syntactic sugar for new Entity(KeyFactory.createKey(kind, keyName)).

Entity

public Entity(java.lang.String kind,
              long id)

Create a new Entity with the specified kind and ID and no parent Entity. The instantiated Entity will have a complete Key when this constructor returns. The Key's id field will be set to the value of id.

Creating an entity for the purpose of insertion (as opposed to update) with this constructor is discouraged unless the id was obtained from a key returned by a KeyRange obtained from AsyncDatastoreService.allocateIds(String, long) or DatastoreService.allocateIds(String, long) for the same kind.

This constructor is syntactic sugar for new Entity(KeyFactory.createKey(kind, id)).

Entity

public Entity(java.lang.String kind,
              java.lang.String keyName,
              Key parent)

Create a new Entity with the specified kind, key name, and parent Entity. The instantiated Entity will have a complete Key when this constructor returns. The Key's name field will be set to the value of keyName.

This constructor is syntactic sugar for new Entity(KeyFactory.createKey(parent, kind, keyName)).

Entity

public Entity(java.lang.String kind,
              long id,
              Key parent)

Create a new Entity with the specified kind and ID and parent Entity. The instantiated Entity will have a complete Key when this constructor returns. The Key's id field will be set to the value of id.

Creating an entity for the purpose of insertion (as opposed to update) with this constructor is discouraged unless the id was obtained from a key returned by a KeyRange obtained from AsyncDatastoreService.allocateIds(Key, String, long) or DatastoreService.allocateIds(Key, String, long) for the same parent and kind.

This constructor is syntactic sugar for new Entity(KeyFactory.createKey(parent, kind, id)).

Entity

public Entity(Key key)

Create a new Entity uniquely identified by the provided Key. Creating an entity for the purpose of insertion (as opposed to update) with a key that has its id field set is strongly discouraged unless the key was returned by a KeyRange.

See Also:

KeyRange

Method Detail

equals

public boolean equals(java.lang.Object object)

Two Entity objects are considered equal if they refer to the same entity (i.e. their Key objects match).

Overrides:

equals in class java.lang.Object

getKey

public Key getKey()

Returns the Key that represents this Entity. If the entity has not yet been saved (e.g. via DatastoreService.put), this Key will not be fully specified and cannot be used for certain operations (like DatastoreService.get). Once the Entity has been saved, its Key will be updated to be fully specified.

getKind

public java.lang.String getKind()

Returns a logical type that is associated with this Entity. This is simply a convenience method that forwards to the Key for this Entity.

getParent

public Key getParent()

Get a Key that corresponds to this the parent Entity of this Entity. This is simply a convenience method that forwards to the Key for this Entity.

getProperty

public java.lang.Object getProperty(java.lang.String propertyName)

Gets the property with the specified name. The value returned may not be the same type as originally set via setProperty(java.lang.String, java.lang.Object).

Returns:

the property corresponding to propertyName.

getProperties

public java.util.Map<java.lang.String,java.lang.Object> getProperties()

Gets all of the properties belonging to this Entity.

Returns:

an unmodifiable Map of properties.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

hasProperty

public boolean hasProperty(java.lang.String propertyName)

Returns true if a property has been set. This function can be used to test if a property has been specifically set to null.

Returns:

true iff the property named propertyName exists.

removeProperty

public void removeProperty(java.lang.String propertyName)

Removes any property with the specified name. If there is no property with this name set, simply does nothing.

Throws:

java.lang.NullPointerException - If propertyName is null.

setProperty

public void setProperty(java.lang.String propertyName,
                        java.lang.Object value)

Sets the property named, propertyName, to value.

As the value is stored in the datastore, it is converted to the datastore's native type. This may include widening, such as converting a Short to a Long.

All Collections are prone to losing their sort order and their original types as they are stored in the datastore. For example, a TreeSet may be returned as a List from getProperty(java.lang.String), with an arbitrary re-ordering of elements.

Overrides any existing value for this property, whether indexed or unindexed.

Note that Blob and Text property values are never indexed by the built-in single property indexes. To store other types without being indexed, use #setUnindexedProperty.

Parameters:

value - may be one of the supported datatypes or a heterogeneous Collection of one of the supported datatypes.

Throws:

java.lang.IllegalArgumentException - If the value is not of a type that the data store supports.

See Also:

setUnindexedProperty(java.lang.String, java.lang.Object)

setUnindexedProperty

public void setUnindexedProperty(java.lang.String propertyName,
                                 java.lang.Object value)

Like #setProperty, but doesn't index the property in the built-in single property indexes.

Parameters:

value - may be one of the supported datatypes, or a heterogeneous Collection of one of the supported datatypes.

Overrides any existing value for this property, whether indexed or unindexed.

Throws:

java.lang.IllegalArgumentException - If the value is not of a type that the data store supports.

See Also:

setProperty(java.lang.String, java.lang.Object)

isUnindexedProperty

public boolean isUnindexedProperty(java.lang.String propertyName)

Returns true if propertyName has a value that will not be indexed. This includes Text, Blob, and any property added using setUnindexedProperty(java.lang.String, java.lang.Object).

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getAppId

public java.lang.String getAppId()

Returns the identifier of the application that owns this Entity. This is simply a convenience method that forwards to the Key for this Entity.

getNamespace

public java.lang.String getNamespace()

Returns the namespace of the application/namespace that owns this Entity. This is simply a convenience method that forwards to the Key for this Entity.

clone

public Entity clone()

Returns a shallow copy of this Entity instance. Collection properties are cloned as an ArrayList, the type returned from the datastore. Instances of mutable datastore types are cloned as well. Instances of all other types are reused.

Overrides:

clone in class java.lang.Object

Returns:

a shallow copy of this Entity

setPropertiesFrom

public void setPropertiesFrom(Entity src)

A convenience method that populates the properties of this Entity with the properties set on the provided Entity. This method transfers information about unindexed properties.

Parameters:

src - The entity from which we will populate ourself.