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

   1 // Copyright 2007 Google Inc. All rights reserved.
   2
   3 package com.google.appengine.api.datastore;
   4
   5 import java.util.ConcurrentModificationException;
   6 import java.util.List;
   7 import java.util.Map;
   8
   9 /**
  10  * The {@code DatastoreService} provides synchronous access to a schema-less
  11  * data storage system.  The fundamental unit of data in this system is the
  12  * {@code Entity}, which has an immutable identity (represented by a
  13  * {@code Key}) and zero or more mutable properties.  {@code Entity}
  14  * objects can be created, updated, deleted, retrieved by identifier,
  15  * and queried via a combination of properties.
  16  *
  17  * <p>The {@code DatastoreService} can be used transactionally and
  18  * supports the notion of a "current" transaction.  A current
  19  * transaction is established by calling {@link #beginTransaction()}.
  20  * The transaction returned by this method ceases to be current when
  21  * an attempt is made to commit or rollback or when another call is
  22  * made to {@link #beginTransaction()}.  A transaction can only be
  23  * current within the Thread that created it.
  24  *
  25  * <p>The various overloads of put, get, and delete all support
  26  * transactions.  Users of this class have the choice of explicitly
  27  * passing a (potentially {@code null}) {@link Transaction} to these
  28  * methods or relying on the behavior governed by the
  29  * {@link ImplicitTransactionManagementPolicy}.  If a user explicitly
  30  * provides a {@link Transaction} it is up to the user to call
  31  * {@link Transaction#commit()} or {@link Transaction#rollback()} at
  32  * the proper time.  If a user relies on implicit transaction
  33  * management and the installed policy creates a transaction, that
  34  * transaction will be committed (in the case of a success) or rolled
  35  * back (in the case of a failure) before the operation returns to the
  36  * user.  The methods that manage transactions according to
  37  * {@link ImplicitTransactionManagementPolicy} are:
  38  * {@link #delete(Key...)}, {@link #delete(Iterable)},
  39  * {@link #get(Key)}, {@link #get(Iterable)}, {@link #put(Entity)},
  40  * and {@link #put(Iterable)}.
  41  *
  42  * <p>The overload of prepare that takes a {@link Transaction}
  43  * parameter behaves the same as the overloads of put, get, and delete
  44  * that take a {@link Transaction} parameter.  However, the overload
  45  * of prepare that does not take a {@link Transaction} parameter,
  46  * unlike put, get, and delete, does not use an existing
  47  * {@link Transaction} if one is already running and does not consult
  48  * the {@link ImplicitTransactionManagementPolicy} if one is not
  49  * already running.
  50  *
  51  */
  52 public interface DatastoreService extends BaseDatastoreService {
  53   /**
  54    * Retrieves the {@code Entity} with the specified {@code Key}.
  55    *
  56    * If there is a current transaction, this operation will execute within
  57    * that transaction.  In this case it is up to the caller to commit
  58    * or rollback.  If there is no current transaction, the behavior of this
  59    * method with respect to transactions will be determined by the
  60    * {@link ImplicitTransactionManagementPolicy} available on the
  61    * {@link DatastoreServiceConfig}.
  62    *
  63    * @throws EntityNotFoundException If the specified entity could not be found.
  64    * @throws IllegalArgumentException If the specified key is invalid.
  65    * @throws DatastoreFailureException If any other datastore error occurs.
  66    */
  67   Entity get(Key key) throws EntityNotFoundException;
  68
  69   /**
  70    * Exhibits the same behavior as {@link #get(Key)}, but executes within
  71    * the provided transaction.  It is up to the caller to commit or
  72    * rollback.  Transaction can be null.
  73    *
  74    * @throws IllegalStateException If {@code txn} is not null and not
  75    * active.
  76    */
  77   Entity get(Transaction txn, Key key) throws EntityNotFoundException;
  78
  79   /**
  80    * Retrieves the set of {@link Entity Entities} matching {@code keys}.
  81    * The result {@code Map} will only contain {@code Keys} for which
  82    * {@code Entities} could be found.
  83    *
  84    * If there is a current transaction, this operation will execute within
  85    * that transaction.  In this case it is up to the caller to commit
  86    * or rollback.  If there is no current transaction, the behavior of this
  87    * method with respect to transactions will be determined by the
  88    * {@link ImplicitTransactionManagementPolicy} available on the
  89    * {@link DatastoreServiceConfig}.
  90    *
  91    * @throws IllegalArgumentException If any {@code Key} in keys is invalid.
  92    * @throws DatastoreFailureException If any other datastore error occurs.
  93    */
  94   Map<Key, Entity> get(Iterable<Key> keys);
  95
  96   /**
  97    * Exhibits the same behavior as {@link #get(Iterable)}, but executes within
  98    * the provided transaction.  It is up to the caller to commit or
  99    * rollback.  Transaction can be null.
 100    *
 101    * @throws IllegalStateException If {@code txn} is not null and not
 102    * active.
 103    */
 104   Map<Key, Entity> get(Transaction txn, Iterable<Key> keys);
 105
 106   /**
 107    * If the specified {@code Entity} does not yet exist in the data
 108    * store, create it and assign its {@code Key}.  If the specified
 109    * {@code Entity} already exists in the data store, save the new
 110    * version.
 111    *
 112    * <p>The {@code Key} is returned, and is also returned by future calls
 113    * to {@code entity.getKey()}.
 114    *
 115    * If there is a current transaction, this operation will execute within
 116    * that transaction.  In this case it is up to the caller to commit
 117    * or rollback.  If there is no current transaction, the behavior of this
 118    * method with respect to transactions will be determined by the
 119    * {@link ImplicitTransactionManagementPolicy} available on the
 120    * {@link DatastoreServiceConfig}.
 121    *
 122    * @throws IllegalArgumentException If the specified entity was incomplete.
 123    * @throws ConcurrentModificationException If the entity group to which the
 124    *    entity belongs was modified concurrently.
 125    * @throws DatastoreFailureException If any other datastore error occurs.
 126    */
 127   Key put(Entity entity);
 128
 129   /**
 130    * Exhibits the same behavior as {@link #put(Entity)}, but executes within
 131    * the provided transaction.  It is up to the caller to commit or
 132    * rollback.  Transaction can be null.
 133    *
 134    * @throws IllegalStateException If {@code txn} is not null and not
 135    *    active.
 136    * @throws ConcurrentModificationException If the entity group to which the
 137    *    entity belongs was modified concurrently.
 138    * @throws DatastoreFailureException If any other datastore error occurs.
 139    */
 140   Key put(Transaction txn, Entity entity);
 141
 142   /**
 143    * Performs a batch {@link #put(Entity) put} of all {@code entities}.
 144    *
 145    * If there is a current transaction, this operation will execute within
 146    * that transaction.  In this case it is up to the caller to commit
 147    * or rollback.  If there is no current transaction, the behavior of this
 148    * method with respect to transactions will be determined by the
 149    * {@link ImplicitTransactionManagementPolicy} available on the
 150    * {@link DatastoreServiceConfig}.
 151    *
 152    * @return The {@code Key}s that were assigned to the entities that were put.
 153    * If the {@code Iterable} that was provided as an argument has a stable
 154    * iteration order the {@code Key}s in the {@code List} we return are in
 155    * that same order.  If the {@code Iterable} that was provided as an argument
 156    * does not have a stable iteration order the order of the {@code Key}s in
 157    * the {@code List} we return is undefined.
 158    *
 159    * @throws IllegalArgumentException If any entity is incomplete.
 160    * @throws ConcurrentModificationException If an entity group to which any
 161    *    provided entity belongs was modified concurrently.
 162    * @throws DatastoreFailureException If any other datastore error occurs.
 163    */
 164   List<Key> put(Iterable<Entity> entities);
 165
 166   /**
 167    * Exhibits the same behavior as {@link #put(Iterable)}, but executes within
 168    * the provided transaction.  It is up to the caller to commit or
 169    * rollback.  Transaction can be null.
 170    *
 171    * @return The {@code Key}s that were assigned to the entities that were put.
 172    * If the {@code Iterable} that was provided as an argument has a stable
 173    * iteration order the {@code Key}s in the {@code List} we return are in
 174    * that same order.  If the {@code Iterable} that was provided as an argument
 175    * does not have a stable iteration order the order of the {@code Key}s in
 176    * the {@code List} we return is undefined.
 177    *
 178    * @throws IllegalStateException If {@code txn} is not null and not active.
 179    * @throws ConcurrentModificationException If an entity group to which any
 180    *    provided entity belongs was modified concurrently.
 181    * @throws DatastoreFailureException If any other datastore error occurs.
 182    */
 183   List<Key> put(Transaction txn, Iterable<Entity> entities);
 184
 185   /**
 186    * Deletes the {@code Entity entities} specified by {@code keys}.
 187    *
 188    * If there is a current transaction, this operation will execute within
 189    * that transaction.  In this case it is up to the caller to commit
 190    * or rollback.  If there is no current transaction, the behavior of this
 191    * method with respect to transactions will be determined by the
 192    * {@link ImplicitTransactionManagementPolicy} available on the
 193    * {@link DatastoreServiceConfig}.
 194    *
 195    * @throws IllegalArgumentException If the specified key was invalid.
 196    * @throws ConcurrentModificationException If an entity group to which any
 197    *    provided key belongs was modified concurrently.
 198    * @throws DatastoreFailureException If any other datastore error occurs.
 199    */
 200   void delete(Key... keys);
 201
 202   /**
 203    * Exhibits the same behavior as {@link #delete(Key...)}, but executes within
 204    * the provided transaction.  It is up to the caller to commit or
 205    * rollback.  Transaction can be null.
 206    *
 207    * @throws IllegalStateException If {@code txn} is not null and not active.
 208    * @throws ConcurrentModificationException If an entity group to which any
 209    *    provided key belongs was modified concurrently.
 210    * @throws DatastoreFailureException If any other datastore error occurs.
 211    */
 212   void delete(Transaction txn, Key... keys);
 213
 214   /**
 215    * Equivalent to {@link #delete(Key...)}.
 216    *
 217    * @throws ConcurrentModificationException If an entity group to which any
 218    *    provided key belongs was modified concurrently.
 219    * @throws DatastoreFailureException If any other datastore error occurs.
 220    */
 221   void delete(Iterable<Key> keys);
 222
 223   /**
 224    * Exhibits the same behavior as {@link #delete(Iterable)}, but executes within
 225    * the provided transaction.  It is up to the caller to commit or rollback.
 226    * Transaction can be null.
 227    *
 228    * @throws IllegalStateException If {@code txn} is not null and not active.
 229    * @throws ConcurrentModificationException If an entity group to which any
 230    *    provided key belongs was modified concurrently.
 231    * @throws DatastoreFailureException If any other datastore error occurs.
 232    */
 233   void delete(Transaction txn, Iterable<Key> keys);
 234
 235   /**
 236    * Equivalent to {@code beginTransaction(TransactionOptions.Builder.withDefaults())}.
 237    *
 238    * @return the {@code Transaction} that was started.
 239    * @throws DatastoreFailureException If a datastore error occurs.
 240    * @see #beginTransaction(TransactionOptions)
 241    */
 242   Transaction beginTransaction();
 243
 244   /**
 245    * Begins a transaction against the datastore.  Callers are responsible
 246    * for explicitly calling {@link Transaction#commit()} or
 247    * {@link Transaction#rollback()} when they no longer need the
 248    * {@code Transaction}.
 249    *
 250    * <p>The {@code Transaction} returned by this call will be considered the
 251    * current transaction and will be returned by subsequent, same-thread calls
 252    * to {@link #getCurrentTransaction()} and
 253    * {@link #getCurrentTransaction(Transaction)} until one of the following happens:
 254    * 1) {@link #beginTransaction()} is invoked from the same thread.  In this
 255    * case {@link #getCurrentTransaction()} and
 256    * {@link #getCurrentTransaction(Transaction)} will return the result of the
 257    * more recent call to {@link #beginTransaction()}.
 258    * 2) {@link Transaction#commit()} is invoked on the {@link Transaction}
 259    * returned by this method.  Whether or not the commit returns successfully,
 260    * the {@code Transaction} will no longer be the current transaction.
 261    * 3) {@link Transaction#rollback()} ()} is invoked on the
 262    * {@link Transaction} returned by this method.  Whether or not the rollback
 263    * returns successfully, the {@code Transaction} will no longer be the
 264    * current transaction.
 265    *
 266    * @param options The options for the new transaction.
 267    * @return the {@code Transaction} that was started.
 268    * @throws DatastoreFailureException If a datastore error occurs.
 269    * @see #getCurrentTransaction()
 270    * @see TransactionOptions
 271    */
 272   Transaction beginTransaction(TransactionOptions options);
 273
 274   /**
 275    * IDs are allocated within a namespace defined by a parent key and a kind.
 276    * This method allocates a contiguous range of unique IDs of size {@code num}
 277    * within the namespace defined by a null parent key (root entities) and the
 278    * given kind.
 279    *
 280    * IDs allocated in this manner may be provided manually to newly created
 281    * entities. They will not be used by the datastore's automatic ID allocator
 282    * for root entities of the same kind.
 283    *
 284    * @param kind The kind for which the root entity IDs should be allocated.
 285    * @param num The number of IDs to allocate.
 286    * @return A {@code KeyRange} of size {@code num}.
 287    *
 288    * @throws IllegalArgumentException If {@code num} is less than 1 or if
 289    * {@code num} is greater than 1 billion.
 290    * @throws DatastoreFailureException If a datastore error occurs.
 291    */
 292   KeyRange allocateIds(String kind, long num);
 293
 294   /**
 295    * IDs are allocated within a namespace defined by a parent key and a kind.
 296    * This method allocates a contiguous range of unique IDs of size {@code num}
 297    * within the namespace defined by the given parent key and the given kind.
 298    *
 299    * IDs allocated in this manner may be provided manually to newly created
 300    * entities. They will not be used by the datastore's automatic ID allocator
 301    * for entities with the same kind and parent.
 302    *
 303    * @param parent The key for which the child entity IDs should be allocated.
 304    * Can be null.
 305    * @param kind The kind for which the child entity IDs should be allocated.
 306    * @param num The number of IDs to allocate.
 307    *
 308    * @return A range of IDs of size {@code num} that are guaranteed to be
 309    * unique.
 310    *
 311    * @throws IllegalArgumentException If {@code parent} is not a complete key,
 312    * if {@code num} is less than 1, or if {@code num} is greater than
 313    * 1 billion.
 314    * @throws DatastoreFailureException If a datastore error occurs.
 315    */
 316   KeyRange allocateIds(Key parent, String kind, long num);
 317
 318   /**
 319    * Indicates the state of a {@link KeyRange}.
 320    *
 321    * @see DatastoreService#allocateIdRange(KeyRange)
 322    */
 323   enum KeyRangeState {
 324     /**
 325      * Indicates the given {@link KeyRange} is empty and the datastore's
 326      * automatic ID allocator will not assign keys in this range to new
 327      * entities.
 328      */
 329     EMPTY,
 330     /**
 331      * Indicates the given {@link KeyRange} is empty but the datastore's
 332      * automatic ID allocator may assign new entities keys in this range.
 333      * However it is safe to manually assign {@link Key Keys} in this range
 334      * if either of the following is true:
 335      * <ul>
 336      * <li>No other request will insert entities with the same kind and parent
 337      * as the given {@link KeyRange} until all entities with manually assigned
 338      * keys from this range have been written.
 339      * <li>Overwriting entities written by other requests with the same kind
 340      * and parent as the given {@link KeyRange} is acceptable.
 341      * </ul>
 342      * <p>The datastore's automatic ID allocator will not assign a key to a new
 343      * entity that will overwrite an existing entity, so once the range is
 344      * populated there will no longer be any contention.
 345      */
 346     CONTENTION,
 347     /**
 348      * Indicates that entities with keys inside the given {@link KeyRange}
 349      * already exist and writing to this range will overwrite those entities.
 350      * Additionally the implications of {@link #CONTENTION} apply. If
 351      * overwriting entities that exist in this range is acceptable it is safe
 352      * to use the given range.
 353      *
 354      * <p>The datastore's automatic ID allocator will never assign a key to
 355      * a new entity that will overwrite an existing entity so entities
 356      * written by the user to this range will never be overwritten by
 357      * an entity with an automatically assigned key.
 358      */
 359     COLLISION,
 360   }
 361
 362   /**
 363    * This method allocates a user-specified contiguous range of unique IDs.
 364    *
 365    * <p>Once these IDs have been allocated they may be provided manually to
 366    * newly created entities.
 367    *
 368    * <p>Since the datastore's automatic ID allocator will never assign
 369    * a key to a new entity that will cause an existing entity to be
 370    * overwritten, entities written to the given {@link KeyRange} will never be
 371    * overwritten. However, writing entities with manually assigned keys in this
 372    * range may overwrite existing entities (or new entities written by a
 373    * separate request) depending on the {@link KeyRangeState} returned.
 374    *
 375    * <p>This method should only be used if you have an existing numeric id
 376    * range that you want to reserve, e.g. bulk loading entities that already
 377    * have IDs. If you don't care about which IDs you receive, use {@link
 378    * #allocateIds} instead.
 379    *
 380    * @param range The key range to allocate.
 381    *
 382    * @return The state of the id range allocated.
 383    * @throws DatastoreFailureException If a datastore error occurs.
 384    */
 385   KeyRangeState allocateIdRange(KeyRange range);
 386
 387   /**
 388    * Retrieves the current datastore's attributes.
 389    *
 390    * @return The attributes of the datastore used to fulfill requests.
 391    * @throws DatastoreFailureException If a datastore error occurs.
 392    */
 393   DatastoreAttributes getDatastoreAttributes();
 394
 395   /**
 396    * Returns the application indexes and their states.
 397    */
 398   Map<Index, Index.IndexState> getIndexes();
 399 }