# Entity
Date: 2012-02-24

## 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.