# 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.
  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
  --- | ---
  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 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 |
  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.
  Index | A Datastore `Index` definition.
  Index.Property | An indexed property.
  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