java/src/main/com/google/appengine/api/datastore/Entity.java

   1 // Copyright 2007 Google Inc. All rights reserved.
   2
   3 package com.google.appengine.api.datastore;
   4
   5 import java.io.Serializable;
   6 import java.util.HashMap;
   7 import java.util.Map;
   8
   9 /**
  10  * {@code Entity} is the fundamental unit of data storage.  It has an
  11  * immutable identifier (contained in the {@link Key}) object, a
  12  * reference to an optional parent {@code Entity}, a kind (represented
  13  * as an arbitrary string), and a set of zero or more typed
  14  * properties.
  15  *
  16  */
  17 public final class Entity extends PropertyContainer implements Cloneable {
  18
  19   static final long serialVersionUID = -836647825120453511L;
  20
  21   /**
  22    * A reserved property name used to refer to the key of the entity.
  23    * This string can be used for filtering and sorting by the entity
  24    * key itself.
  25    */
  26   public static final String KEY_RESERVED_PROPERTY = "__key__";
  27
  28   /**
  29    * A reserved property name used to refer to the scatter property of the
  30    * entity.
  31    * Used for finding split points (e.g. for mapping over a kind).
  32    */
  33   public static final String SCATTER_RESERVED_PROPERTY = "__scatter__";
  34
  35   /**
  36    * A reserved property name used to report an entity group's version.
  37    */
  38   public static final String VERSION_RESERVED_PROPERTY = "__version__";
  39
  40   private final Key key;
  41   final Map<String, Object> propertyMap;
  42
  43   static final class UnindexedValue implements Serializable {
  44     private final Object value;
  45
  46     /**
  47      * @param value may be null
  48      */
  49     UnindexedValue(Object value) {
  50       this.value = value;
  51     }
  52
  53     public Object getValue() {
  54       return value;
  55     }
  56
  57     @Override
  58     public boolean equals(Object that) {
  59       if (that instanceof UnindexedValue) {
  60         UnindexedValue uv = (UnindexedValue) that;
  61         return (value == null) ? uv.value == null : value.equals(uv.value);
  62       }
  63       return false;
  64     }
  65
  66     @Override
  67     public int hashCode() {
  68       return (value == null) ? 0 : value.hashCode();
  69     }
  70
  71     @Override
  72     public String toString() {
  73       return value + " (unindexed)";
  74     }
  75   }
  76
  77   /**
  78    * Create a new {@code Entity} with the specified kind and no
  79    * parent {@code Entity}.  The instantiated {@code Entity} will have an
  80    * incomplete {@link Key} when this constructor returns.  The
  81    * {@link Key} will remain incomplete until you put the {@code Entity},
  82    * after which time the {@link Key} will have its {@code id} set.
  83    */
  84   public Entity(String kind) {
  85     this(kind, (Key) null);
  86   }
  87
  88   /**
  89    * Create a new {@code Entity} with the specified kind and parent
  90    * {@code Entity}.  The instantiated {@code Entity} will have an
  91    * incomplete {@link Key} when this constructor returns.  The
  92    * {@link Key} will remain incomplete until you put the {@code Entity},
  93    * after which time the {@link Key} will have its {@code id} set.
  94    */
  95   public Entity(String kind, Key parent) {
  96
  97     this(new Key(kind, parent));
  98   }
  99
 100   /**
 101    * Create a new {@code Entity} with the specified kind and key name and no
 102    * parent {@code Entity}.  The instantiated {@code Entity} will have a
 103    * complete {@link Key} when this constructor returns.  The
 104    * {@link Key Key's} {@code name} field will be set to the value of
 105    * {@code keyName}.
 106    *
 107    * <p>This constructor is syntactic sugar for
 108    * {@code new Entity(KeyFactory.createKey(kind, keyName))}.
 109    */
 110   public Entity(String kind, String keyName) {
 111     this(KeyFactory.createKey(kind, keyName));
 112   }
 113
 114   /**
 115    * Create a new {@code Entity} with the specified kind and ID and no
 116    * parent {@code Entity}.  The instantiated {@code Entity} will have a
 117    * complete {@link Key} when this constructor returns.  The
 118    * {@link Key Key's} {@code id} field will be set to the value of
 119    * {@code id}.
 120    *
 121    * <p>Creating an entity for the purpose of insertion (as opposed to
 122    * update) with this constructor is discouraged unless the id was
 123    * obtained from a key returned by a {@link KeyRange} obtained from
 124    * {@link AsyncDatastoreService#allocateIds(String, long)} or
 125    * {@link DatastoreService#allocateIds(String, long)} for the same
 126    * kind.
 127    *
 128    * <p>This constructor is syntactic sugar for
 129    * {@code new Entity(KeyFactory.createKey(kind, id))}.
 130    */
 131   public Entity(String kind, long id) {
 132     this(KeyFactory.createKey(kind, id));
 133   }
 134
 135   /**
 136    * Create a new {@code Entity} with the specified kind, key name, and
 137    * parent {@code Entity}.  The instantiated {@code Entity} will have a
 138    * complete {@link Key} when this constructor returns.  The
 139    * {@link Key Key's} {@code name} field will be set to the value of
 140    * {@code keyName}.
 141    *
 142    * <p>This constructor is syntactic sugar for
 143    * {@code new Entity(KeyFactory.createKey(parent, kind, keyName))}.
 144    */
 145   public Entity(String kind, String keyName, Key parent) {
 146     this(KeyFactory.createKey(parent, kind, keyName));
 147   }
 148
 149   /**
 150    * Create a new {@code Entity} with the specified kind and ID and
 151    * parent {@code Entity}.  The instantiated {@code Entity} will have a
 152    * complete {@link Key} when this constructor returns.  The
 153    * {@link Key Key's} {@code id} field will be set to the value of
 154    * {@code id}.
 155    *
 156    * <p>Creating an entity for the purpose of insertion (as opposed to
 157    * update) with this constructor is discouraged unless the id was
 158    * obtained from a key returned by a {@link KeyRange} obtained from
 159    * {@link AsyncDatastoreService#allocateIds(Key, String, long)} or
 160    * {@link DatastoreService#allocateIds(Key, String, long)} for the same
 161    * parent and kind.
 162    *
 163    * <p>This constructor is syntactic sugar for
 164    * {@code new Entity(KeyFactory.createKey(parent, kind, id))}.
 165    */
 166   public Entity(String kind, long id, Key parent) {
 167     this(KeyFactory.createKey(parent, kind, id));
 168   }
 169
 170   /**
 171    * Create a new {@code Entity} uniquely identified by the provided
 172    * {@link Key}.  Creating an entity for the purpose of insertion (as opposed
 173    * to update) with a key that has its {@code id} field set is strongly
 174    * discouraged unless the key was returned by a {@link KeyRange}.
 175    *
 176    * @see KeyRange
 177    */
 178   public Entity(Key key) {
 179     this.key = key;
 180     this.propertyMap = new HashMap<String, Object>();
 181   }
 182
 183   /**
 184    * Two {@code Entity} objects are considered equal if they refer to
 185    * the same entity (i.e. their {@code Key} objects match).
 186    */
 187   @Override
 188   public boolean equals(Object object) {
 189     if (object instanceof Entity) {
 190       Entity otherEntity = (Entity) object;
 191       return key.equals(otherEntity.key);
 192     }
 193     return false;
 194   }
 195
 196   /**
 197    * Returns the {@code Key} that represents this {@code Entity}.  If
 198    * the entity has not yet been saved (e.g. via {@code
 199    * DatastoreService.put}), this {@code Key} will not be fully
 200    * specified and cannot be used for certain operations (like {@code
 201    * DatastoreService.get}).  Once the {@code Entity} has been saved,
 202    * its {@code Key} will be updated to be fully specified.
 203    */
 204   public Key getKey() {
 205     return key;
 206   }
 207
 208   /**
 209    * Returns a logical type that is associated with this {@code
 210    * Entity}.  This is simply a convenience method that forwards to
 211    * the {@code Key} for this {@code Entity}.
 212    */
 213   public String getKind() {
 214     return key.getKind();
 215   }
 216
 217   /**
 218    * Get a {@code Key} that corresponds to this the parent {@code
 219    * Entity} of this {@code Entity}.  This is simply a convenience
 220    * method that forwards to the {@code Key} for this {@code Entity}.
 221    */
 222   public Key getParent() {
 223     return key.getParent();
 224   }
 225
 226   @Override
 227   public int hashCode() {
 228     return key.hashCode();
 229   }
 230
 231   @Override
 232   public String toString() {
 233     StringBuilder builder = new StringBuilder("<Entity [");
 234     builder.append(key).append("]:\n");
 235     appendPropertiesTo(builder);
 236     builder.append(">\n");
 237     return builder.toString();
 238   }
 239
 240   /**
 241    * Returns the identifier of the application that owns this {@code
 242    * Entity}.  This is simply a convenience method that forwards to
 243    * the {@code Key} for this {@code Entity}.
 244    */
 245   public String getAppId() {
 246     return key.getAppId();
 247   }
 248
 249   /**
 250    * Returns the AppIdNamespace of the application/namespace that owns
 251    * this {@code Entity}.  This is simply a convenience method that forwards to
 252    * the {@code Key} for this {@code Entity}.
 253    */
 254   AppIdNamespace getAppIdNamespace() {
 255     return key.getAppIdNamespace();
 256   }
 257
 258   /**
 259    * Returns the namespace of the application/namespace that owns
 260    * this {@code Entity}.  This is simply a convenience method that forwards to
 261    * the {@code Key} for this {@code Entity}.
 262    */
 263   public String getNamespace() {
 264     return key.getNamespace();
 265   }
 266
 267   /**
 268    * Returns a shallow copy of this {@code Entity} instance. {@code Collection}
 269    * properties are cloned as an {@code ArrayList}, the type returned from the
 270    * datastore. Instances of mutable datastore types are cloned as well.
 271    * Instances of all other types are reused.
 272    *
 273    * @return a shallow copy of this {@code Entity}
 274    */
 275   @Override
 276   public Entity clone() {
 277     Entity entity = new Entity(key);
 278     entity.setPropertiesFrom(this);
 279     return entity;
 280   }
 281
 282   public void setPropertiesFrom(Entity src) {
 283     super.setPropertiesFrom(src);
 284   }
 285
 286   @Override
 287   Map<String, Object> getPropertyMap() {
 288     return propertyMap;
 289   }
 290 }