java/src/main/com/google/appengine/api/datastore/package-info.java

   1 // Copyright 2009 Google Inc.  All rights reserved.
   2
   3 /**
   4  * Provides persistent storage, also accessible via <a
   5  * href="http://www.oracle.com/technetwork/java/index-jsp-135919.html">JDO</a>
   6  * or <a
   7  * href="http://www.oracle.com/technetwork/articles/javaee/jpa-137156.html">JPA</a>
   8  * interfaces.  It provides redundant storage for fault-tolerance.
   9  *
  10  * <p>A common pattern of usage is:
  11  *
  12  * <pre>
  13  * // Get a handle on the datastore itself
  14  * DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
  15  *
  16  * // Lookup data by known key name
  17  * Entity userEntity = datastore.get(KeyFactory.createKey("UserInfo", email));
  18  *
  19  * // Or perform a query
  20  * Query query = new Query("Task");
  21  * query.addFilter("dueDate", Query.FilterOperator.LESS_THAN, today);
  22  * for (Entity taskEntity : datastore.prepare(query).asIterable()) {
  23  *   if ("done".equals(taskEntity.getProperty("status"))) {
  24  *     datastore.delete(taskEntity);
  25  *   } else {
  26  *     taskEntity.setProperty("status", "overdue");
  27  *     datastore.put(taskEntity);
  28  *   }
  29  * }
  30  * </pre>
  31  *
  32  * <p>This illustrates several basic points:
  33  * <ul>
  34  * <li> The actual datastore itself is accessed through a
  35  *      {@link com.google.appengine.api.datastore.DatastoreService} object,
  36  *      produced from a {@link com.google.appengine.api.datastore.DatastoreServiceFactory}.
  37  * <li> The unit of storage is the {@link com.google.appengine.api.datastore.Entity}
  38  *      object, which are of named kinds ("UserInfo" and "Task" above).
  39  * <li> Entities have a {@link com.google.appengine.api.datastore.Key} value,
  40  *      which can be created by a {@link com.google.appengine.api.datastore.KeyFactory}
  41  *      to retrieve a specific known entity.  If the key is not readily
  42  *      determined, then {@link com.google.appengine.api.datastore.Query}
  43  *      objects can be used to retrieve one Entity, multiple as a list, {@link
  44  *      java.lang.Iterable}, or {@link java.util.Iterator}, or to retrieve the
  45  *      count of matching entities.
  46  * <li> Entities have named properties, the values of which may be basic types
  47  *      or collections of basic types.  Richer objects, of course, may be
  48  *      stored if serialized as byte arrays, although that may prevent
  49  *      effective querying by those properties.
  50  * <li> Entities may be associated in a tree structure; the {@link
  51  *      com.google.appengine.api.datastore.Query} in the snippet above searches
  52  *      only for Task entities associated with a specific UserInfo entity, and
  53  *      then filters those for Tasks due before today.
  54  * </ul>
  55  *
  56  * <p>In production, non-trivial queries cannot be performed until one
  57  * or more indexes have been built to ensure that the individual
  58  * queries can be processed efficiently.  You can specify the set of
  59  * indexes your application requires in a
  60  * {@code WEB-INF/datastore-indexes.xml} file, or they can be
  61  * generated automatically as you test your application in the
  62  * Development Server.  If a query requires an index that cannot be
  63  * found, a {@link com.google.appengine.api.datastore.DatastoreNeedIndexException}
  64  * will be thrown at runtime.
  65  *
  66  * <p>Although Google App Engine allows many versions of your
  67  * application to be accessible, there is only one datastore for your
  68  * application, shared by all versions.  Similarly, the set of indexes
  69  * is shared by all application versions.
  70  *
  71  * <p>Application authors may also consider using either of the
  72  * provided JDO or JPA interfaces to the datastore.
  73  *
  74  * @see com.google.appengine.api.datastore.DatastoreService
  75  * @see <a
  76  * href="http://cloud.google.com/appengine/docs/java/datastore/">
  77  * The Datastore Java API in the Google App Engine
  78  * Developers Guide</a>
  79  * @see <a
  80  * href="http://www.oracle.com/technetwork/java/index-jsp-135919.html">JDO
  81  * API</a>
  82  * @see <a
  83  * href="http://www.oracle.com/technetwork/articles/javaee/jpa-137156.html">JPA
  84  * API</a>
  85  */
  86 package com.google.appengine.api.datastore;
  87