com.google.appengine.api.datastore (Google App Engine API for Java)

Package com.google.appengine.api.datastore

Provides persistent storage, also accessible via JDO or JPA interfaces.

See: Description

Package com.google.appengine.api.datastore Description

Provides persistent storage, also accessible via JDO or JPA interfaces. It provides redundant storage for fault-tolerance.

A common pattern of usage is: 

 // Get a handle on the datastore itself
 DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

 // Lookup data by known key name
 Entity userEntity = datastore.get(KeyFactory.createKey("UserInfo", email));

 // Or perform a query
 Query query = new Query("Task");
 query.addFilter("dueDate", Query.FilterOperator.LESS_THAN, today);
 for (Entity taskEntity : datastore.prepare(query).asIterable()) {
   if ("done".equals(taskEntity.getProperty("status"))) {
     datastore.delete(taskEntity);
   } else {
     taskEntity.setProperty("status", "overdue");
     datastore.put(taskEntity);
   }
 }

This illustrates several basic points:

  • The actual datastore itself is accessed through a DatastoreService object, produced from a DatastoreServiceFactory.
  • The unit of storage is the Entity object, which are of named kinds ("UserInfo" and "Task" above).
  • Entities have a Key value, which can be created by a KeyFactory to retrieve a specific known entity. If the key is not readily determined, then Query objects can be used to retrieve one Entity, multiple as a list, Iterable, or Iterator, or to retrieve the count of matching entities.
  • Entities have named properties, the values of which may be basic types or collections of basic types. Richer objects, of course, may be stored if serialized as byte arrays, although that may prevent effective querying by those properties.
  • Entities may be associated in a tree structure; the Query in the snippet above searches only for Task entities associated with a specific UserInfo entity, and then filters those for Tasks due before today.

In production, non-trivial queries cannot be performed until one or more indexes have been built to ensure that the individual queries can be processed efficiently. You can specify the set of indexes your application requires in a WEB-INF/datastore-indexes.xml file, or they can be generated automatically as you test your application in the Development Server. If a query requires an index that cannot be found, a DatastoreNeedIndexException will be thrown at runtime.

Although Google App Engine allows many versions of your application to be accessible, there is only one datastore for your application, shared by all versions. Similarly, the set of indexes is shared by all application versions.

Application authors may also consider using either of the provided JDO or JPA interfaces to the datastore.

See Also:
DatastoreService, The Datastore Java API in the Google App Engine Developers Guide, JDO API, JPA API