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

   1 // Copyright 2012 Google Inc. All rights reserved.
   2
   3 package com.google.appengine.api.datastore;
   4
   5 /**
   6  * Utility functions and constants for entities.
   7  *
   8  */
   9 public final class Entities {
  10   /**
  11    * A metadata kind that can be used to query for kinds that exist in the
  12    * datastore.
  13    */
  14   public static final String KIND_METADATA_KIND = "__kind__";
  15
  16   /**
  17    * A metadata kind that can be used to query for properties that exist in the
  18    * datastore.
  19    */
  20   public static final String PROPERTY_METADATA_KIND = "__property__";
  21
  22   /**
  23    * A metadata kind that can be used to query for namespaces that exist in the
  24    * datastore.
  25    */
  26   public static final String NAMESPACE_METADATA_KIND = "__namespace__";
  27
  28   /**
  29    * The numeric ID for __namespace__ keys representing the empty namespace.
  30    */
  31   public static final long NAMESPACE_METADATA_EMPTY_ID = 1;
  32
  33   /**
  34    * A metadata kind that can be used to get information about entity groups.
  35    * The metadata for the entity group with root entity key R is fetched using a
  36    * {@link DatastoreService#get} call on key
  37    * {@code KeyFactory.createKey(R, ENTITY_GROUP_METADATA_KIND,
  38    * ENTITY_GROUP_METADATA_ID)}.
  39    *
  40    * <p>The resulting entity has a {@link Entity#VERSION_RESERVED_PROPERTY}
  41    * numeric property whose value is guaranteed to increase on every change to
  42    * the entity group. This value may also occasionally increase without any
  43    * user-visible change to the entity group.
  44    */
  45   public static final String ENTITY_GROUP_METADATA_KIND = "__entity_group__";
  46
  47   /**
  48    * ID for __entity_group__ entities.
  49    * @see #ENTITY_GROUP_METADATA_KIND
  50    */
  51   public static final long ENTITY_GROUP_METADATA_ID = 1;
  52
  53   /**
  54    * Create a __kind__ key for {@code kind}.
  55    *
  56    * @param kind Kind to create key for.
  57    * @return __kind__ key.
  58    */
  59   public static Key createKindKey(String kind) {
  60     return KeyFactory.createKey(KIND_METADATA_KIND, kind);
  61   }
  62
  63   /**
  64    * Create a __property__ key for {@code property} of {@code kind}.
  65    *
  66    * @param kind Kind to create key for.
  67    * @param property Property to create key for.
  68    * @return __property__ key.
  69    */
  70   public static Key createPropertyKey(String kind, String property) {
  71     return KeyFactory.createKey(createKindKey(kind), PROPERTY_METADATA_KIND, property);
  72   }
  73
  74   /**
  75    * Create a __namespace__ key for {@code namespace}.
  76    *
  77    * @param namespace Namespace to create key for.
  78    * @return __namespace__ key.
  79    */
  80   public static Key createNamespaceKey(String namespace) {
  81     if (namespace.isEmpty()) {
  82       return KeyFactory.createKey(NAMESPACE_METADATA_KIND, NAMESPACE_METADATA_EMPTY_ID);
  83     } else {
  84       return KeyFactory.createKey(NAMESPACE_METADATA_KIND, namespace);
  85     }
  86   }
  87
  88   /**
  89    * Extract the namespace name from a __namespace__ key.
  90    *
  91    * @param namespaceKey Key to extract namespace from.
  92    * @return The namespace name.
  93    */
  94   public static String getNamespaceFromNamespaceKey(Key namespaceKey) {
  95     if (namespaceKey.getId() == NAMESPACE_METADATA_EMPTY_ID) {
  96       return "";
  97     } else {
  98       return namespaceKey.getName();
  99     }
 100   }
 101
 102   /**
 103    * Create an __entity_group__ key for the entity group containing {@code key}.
 104    *
 105    * @param key Key of any entity in the entity group.
 106    * @return __entity_group__ key.
 107    */
 108   public static Key createEntityGroupKey(Key key) {
 109     while (key.getParent() != null) {
 110       key = key.getParent();
 111     }
 112     return KeyFactory.createKey(key, ENTITY_GROUP_METADATA_KIND, ENTITY_GROUP_METADATA_ID);
 113   }
 114
 115   /**
 116    * Get the value of the __version__ property from {@code entity}.
 117    *
 118    * @param entity Entity to fetch __version__ from (must have a numeric
 119    * __version__ property).
 120    * @return __version__ property value.
 121    */
 122   public static long getVersionProperty(Entity entity) {
 123     return ((Number) entity.getProperty(Entity.VERSION_RESERVED_PROPERTY)).longValue();
 124   }
 125 }