Package com.google.appengine.api.datastore

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

See: Description

Interface Summary

Interface	Description
AsyncDatastoreService	An asynchronous version of DatastoreService .
BaseDatastoreService	Methods that are common between DatastoreService and AsyncDatastoreService .
CallbackContext <T>	Describes the context in which a callback runs.
DatastoreConfig	Deprecated Use DatastoreServiceConfig instead.
DatastoreService	The DatastoreService provides synchronous access to a schema-less data storage system.
IDatastoreServiceFactory	This interface should be implemented by providers of the DatastoreService and registered with com.google.appengine.spi.ServiceFactoryFactory .
PreparedQuery	Contains methods for fetching and returning entities from a Query .
QueryResultIterable <T>	A class that produces QueryResultIterator s.
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

Class	Description
AdminDatastoreService	An AsyncDatastoreService implementation that is pinned to a specific appId and namesapce.
AdminDatastoreService.EntityBuilder	An Entity builder that pins it to the AdminUtils appId and namespace .
AdminDatastoreService.KeyBuilder	A Key builder that pins it to the AdminUtils appId and namespace .
AdminDatastoreService.QueryBuilder	A Query builder that pins it to the AdminUtils appId and namespace .
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.
DatastoreAttributes	Attributes of a datastore.
DatastoreServiceConfig	User-configurable properties of the datastore.
DatastoreServiceConfig.Builder	Contains static creation methods for DatastoreServiceConfig .
DatastoreServiceFactory	Creates DatastoreService implementations.
DataTypeTranslator	DataTypeTranslator is a utility class for converting between the data store's Property protocol buffers and 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.
DeleteContext	Concrete CallbackContext implementation that is specific to delete() callbacks.
Email	An e-mail address datatype.
EmbeddedEntity	A property value containing embedded entity properties (and optionally a Key ).
Entities	Utility functions and constants for entities.
Entity	Entity is the fundamental unit of data storage.
EntityProtoComparators	Utilities for comparing EntityProto .
EntityProtoComparators.EntityProtoComparator	A comparator for com.google.storage.onestore.v3.OnestoreEntity.EntityProto objects with the same ordering as EntityComparator .
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.
ExtendableEntityUtil	Internal class that provides utility methods for ExtendableEntity objects.
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.
IDatastoreServiceFactoryProvider	Creates IDatastoreServiceFactory implementations.
IMHandle	An instant messaging handle.
Index	A Datastore Index definition.
Index.Property	An indexed property.
IndexTranslator	Helper class to translate between Index to com.google.storage.onestore.v3.OnestoreEntity.Index .
Key	The primary key for a datastore entity.
KeyFactory	This class enables direct creation of Key objects, both in the root entity group (no parent) and as the child of a given 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.
PostLoadContext	Concrete CallbackContext implementation that is specific to intercepted operations that load Entities , currently get and "query".
PreGetContext	Concrete CallbackContext implementation that is specific to intercepted get() operations.
PreQueryContext	Concrete CallbackContext implementation that is specific to intercepted queries.
Projection	A query projection.
PropertyContainer	A mutable property container.
PropertyProjection	A property projection.
PutContext	Concrete CallbackContext implementation that is specific to put() callbacks.
Query	Query encapsulates a request for zero or more Entity objects out of the datastore.
Query.CompositeFilter	A Query.Filter that combines several sub filters using a Query.CompositeFilterOperator .
Query.Filter	The base class for a query filter.
Query.FilterPredicate	A Query.Filter on a single property.
Query.SortPredicate	SortPredicate is a data container that holds a single sort predicate.
Rating	A user-provided integer rating for a piece of content.
RawValue	A raw datastore value.
ReadPolicy	Policy for reads.
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.
TransactionOptions	Describes options for transactions, passed at transaction creation time.
TransactionOptions.Builder	Contains static creation methods for TransactionOptions .

Enum Summary

Enum	Description
DatastoreAttributes.DatastoreType	Indicates the type of datastore being used.
DatastoreService.KeyRangeState	Indicates the state of a KeyRange .
IMHandle.Scheme	Supported IM schemes.
ImplicitTransactionManagementPolicy	Describes the various policies the datastore can follow for implicit transaction management.
Index.IndexState	Indicates the state of the Index .
Query.CompositeFilterOperator	Operators supported by Query.CompositeFilter .
Query.FilterOperator	Operators supported by Query.FilterPredicate .
Query.SortDirection	SortDirection controls the order of a sort.
ReadPolicy.Consistency	Setting the Consistency for reads allows you to decide whether freshness or availability is more important.

Exception Summary

Exception	Description
CommittedButStillApplyingException	CommittedButStillApplyingException is thrown when the write or transaction was committed, but some entities or index rows may not have been fully updated.
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() .

Annotation Types Summary

Annotation Type	Description
PostDelete	Identifies a callback method to be invoked after an Entity of any of the specified kinds is deleted from the datastore.
PostLoad	Identifies a callback method to be invoked after an Entity of any of the specified kinds is loaded from the datastore.
PostPut	Identifies a callback method to be invoked after an Entity of any of the specified kinds is written to the datastore.
PreDelete	Identifies a callback method to be invoked before an Entity of any of the specified kinds is deleted from the datastore.
PreGet	Identifies a callback method to be invoked before an Entity of any of the specified kinds is fetched from the datastore via a get() rpc.
PrePut	Identifies a callback method to be invoked before an Entity of any of the specified kinds is written to the datastore.
PreQuery	Identifies a callback method to be invoked before a Query for any of the specified kinds is executed against the datastore.

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