Package com.google.appengine.api.datastore

The datastore provides persistent storage for App Engine applications, used either directly or via the provided JDO or JPA interfaces.

See:
Description

Interface Summary

DatastoreConfig	User-configurable properties of the datastore.
DatastoreService	The DatastoreService provides access to a schema-less data storage system.
PreparedQuery	Contains methods for fetching and returning entities from a Query.
QueryResultIterable<T>	A class that produces QueryResultIterators.
QueryResultIterator<T>	A class that iterates through the results of a Query
QueryResultList<T>	A list of results returned by executing a Query.
Transaction	Describes a logical unit of work to be performed against the datastore.

Class Summary

Blob	Blob contains an array of bytes.
Category	A tag, ie a descriptive word or phrase.
CompositeIndexManager	Composite index management operations needed by the datastore api.
Cursor	A cursor that represents a position in a query.
DatastoreApiHelper	Helper methods and constants shared by classes that implement the java api on top of the datastore.
DatastoreServiceFactory	Creates DatastoreService implementations.
DataTypeTranslator	DataTypeTranslator is a utility class for converting between the data store's Property protocol buffers and the the user-facing classes (String, User, etc.).
DataTypeTranslator.ComparableByteArray	A wrapper for a byte[] that implements Comparable.
DataTypeUtils	DataTypeUtils presents a simpler interface that allows user-code to determine what Classes can safely be stored as properties in the data store.
Email	An RFC2822 email address.
Entity	Entity is the fundamental unit of data storage.
EntityProtoComparators	Utilities for comparing OnestoreEntity.EntityProto.
EntityProtoComparators.EntityProtoComparator
EntityTranslator	EntityTranslator contains the logic to translate an Entity into the protocol buffers that are used to pass it to the implementation of the API.
FetchOptions	Describes the limit, offset, and chunk size to be applied when executing a PreparedQuery.
FetchOptions.Builder	Contains static creation methods for FetchOptions.
GeoPt	A geographical point, specified by float latitude and longitude coordinates.
IMHandle	An instant messaging handle.
Key	The primary key for a datastore entity.
KeyFactory	Allows you to create arbitrary Key objects in the root entity group group (no parent).
KeyFactory.Builder	Helper class that aids in the construction of Keys with ancestors.
KeyRange	Represents a range of unique datastore identifiers from getStart().getId() to getEnd().getId() inclusive.
Link	A Link is a URL of limited length.
PhoneNumber	A human-readable phone number.
PostalAddress	A human-readable mailing address.
Query	Query encapsulates a request for zero or more Entity objects out of the datastore.
Query.FilterPredicate	FilterPredicate is a data container that holds a single filter predicate.
Query.SortPredicate	SortPredicate is a data container that holds a single sort predicate.
Rating	A user-provided integer rating for a piece of content.
ShortBlob	ShortBlob contains an array of bytes no longer than DataTypeUtils.MAX_SHORT_BLOB_PROPERTY_LENGTH.
Text	Text wraps around a string of unlimited size.

Enum Summary

IMHandle.Scheme	Supported IM schemes.
ImplicitTransactionManagementPolicy	Describes the various policies the datastore can follow for implicit transaction management.
Query.FilterOperator	FilterOperator specifies what type of operation you want to apply to your filter.
Query.SortDirection	SortDirection controls the order of a sort.

Exception Summary

DatastoreFailureException	DatastoreFailureException is thrown when any unknown error occurs while communicating with the data store.
DatastoreNeedIndexException	DatastoreNeedIndexException is thrown when no matching index was found for a query requiring an index.
DatastoreTimeoutException	DatastoreTimeoutException is thrown when a datastore operation times out.
EntityNotFoundException	EntityNotFoundException is thrown when no Entity with the specified Key could be found.
PreparedQuery.TooManyResultsException	Indicates that too many results were found for PreparedQuery.asSingleEntity().

Package com.google.appengine.api.datastore Description

The datastore provides persistent storage for App Engine applications, used either directly or via the provided JDO or JPA interfaces. It provides redundant storage for fault-tolerance. More information is available in the on-line documentation.

This package contains a low-level API to the datastore that is intended primarily for framework authors. Applications authors should consider using either the provided JDO or JPA interfaces to the datastore. If using the datastore API directly, 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", userEntity);
 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 retrive 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.