Package com.google.appengine.api.datastore (2.0.0)

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 com.google.appengine.api.datastore.DatastoreService object, produced from a com.google.appengine.api.datastore.DatastoreServiceFactory.
• The unit of storage is the com.google.appengine.api.datastore.Entity object, which are of named kinds ("UserInfo" and "Task" above).
• Entities have a com.google.appengine.api.datastore.Key value, which can be created by a com.google.appengine.api.datastore.KeyFactory to retrieve a specific known entity. If the key is not readily determined, then com.google.appengine.api.datastore.Query objects can be used to retrieve one Entity, multiple as a list, java.lang.Iterable, or java.util.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 com.google.appengine.api.datastore.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 com.google.appengine.api.datastore.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: com.google.appengine.api.datastore.DatastoreService, JPA API, JDO API, The Datastore Java API in the Google App Engine Developers Guide

Classes

AdminDatastoreService

An AsyncDatastoreService implementation that is pinned to a specific appId and namesapce. This implementation ignores the "current" appId provided by ApiProxy.getCurrentEnvironment().getAppId() and the "current" namespace provided by NamespaceManager.get(). Note, this is particularly important in the following methods:

• AsyncDatastoreService#getIndexes()
• AsyncDatastoreService#getDatastoreAttributes()
• AsyncDatastoreService#allocateIds(String, long)

In addition this class provides ways to create Query, Entity and Key that are pinned to the same appId/namespace.

Note: users should not access this class directly.

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. This byte array can be no bigger than 1MB. To store files, particularly files larger than this 1MB limit, look at the Blobstore API.

Category

A tag, ie a descriptive word or phrase. Entities may be tagged by users, and later returned by a queries for that tag. Tags can also be used for ranking results (frequency), photo captions, clustering, activity, etc. See Also: Jeffrey Zeldmans blog post on tag clouds for a more in-depth description.

CloudDatastoreRemoteServiceConfig

User-configurable global properties of Cloud Datastore.

Code not running in App Engine Standard can use the Cloud Datastore API by making a single call to #setConfig before accessing any other classes from com.google.appengine.api. For example:

 public static void main(Strings[] args) {
   CloudDatastoreRemoteServiceConfig config = CloudDatastoreRemoteServiceConfig.builder()
       .appId(AppId.create(Location.US_CENTRAL, "my-project-id"))
       .build();
   CloudDatastoreRemoteServiceConfig.setConfig(config);
   DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
   ...
 }
 

Outside of tests, the config should not be cleared once it has been set. In tests, the config can be cleared by calling #clear:

 {@literal @}Before
 public void before() {
   CloudDatastoreRemoteServiceConfig config = CloudDatastoreRemoteServiceConfig.builder()
       .appId(AppId.create(Location.US_CENTRAL, "my-project-id"))
       .emulatorHost(...)
       .build();
   CloudDatastoreRemoteServiceConfig.setConfig(config);
 }

 {@literal @}After
 public void after() {
   CloudDatastoreRemoteServiceConfig.clear();
 }
 

By default, this configuration uses application-default credentials.

CloudDatastoreRemoteServiceConfig.AppId

An App Engine application ID.

CloudDatastoreRemoteServiceConfig.Builder

Builder for CloudDatastoreRemoteServiceConfig.

CompositeIndexManager

Composite index management operations needed by the datastore api.

CompositeIndexManager.IndexComponentsOnlyQuery

Protected alias that allows us to make this class available to the local datastore without publicly exposing it in the api.

CompositeIndexManager.KeyTranslator

Protected alias that allows us to make this class available to the local datastore without publicly exposing it in the api.

CompositeIndexManager.ValidatedQuery

Protected alias that allows us to make this class available to the local datastore without publicly exposing it in the api.

CompositeIndexUtils

Static utilities for working with composite indexes.

Cursor

A cursor that represents a position in a query.

To resume a Query at the position defined by a Cursor, the Cursor must be present in the FetchOptions passed to a PreparedQuery identical to the one it was created from.

Cursors can be retrieved from PreparedQuery.asQueryResult* functions. A typical use case would be:

 Cursor originalCursor = preparedQuery.asQueryResultList(withLimit(20)).getCursor();
 String encodedCursor = original.toWebSafeString();
 

The encoded cursor can then be passed safely in a get or post arg of a web request and on another request the next batch of results can be retrieved with:

 Cursor decodedCursor = Cursor.fromWebSafeString(encodedCursor);
 List<Entity> nextBatch = preparedQuery.asQueryResultList(withLimit(20).cursor(decoded));
 

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. Comparison algorithm is the same as the prod datastore.

DataTypeUtils

DataTypeUtils presents a simpler interface that allows user-code to determine what Classes can safely be stored as properties in the data store.

Currently this list includes:

• String (but not StringBuffer),
• All numeric primitive wrappers (Byte through Long, Float and Double, but not java.math.BigInteger or java.math.BigDecimal.
• Key, for storing references to other Entity objects.
• User, for storing references to users.
• ShortBlob, for storing binary data small enough to be indexed. This means properties of this type, unlike Blob properties, can be filtered and sorted on in queries.
• Blob, for storing unindexed binary data less than 1MB.
• Text, for storing unindexed String data less than 1MB.
• BlobKey, for storing references to user uploaded blobs (which may exceed 1MB).
• Date.
• Link.

DatastoreApiHelper

Helper methods and constants shared by classes that implement the Java api on top of the datastore.

Note: users should not access this class directly.

DatastoreAttributes

Attributes of a datastore.

DatastoreServiceConfig

User-configurable properties of the datastore.

Notes on usage:
The recommended way to instantiate a DatastoreServiceConfig object is to statically import Builder.* and invoke a static creation method followed by an instance mutator (if needed):

 import static com.google.appengine.api.datastore.DatastoreServiceConfig.Builder.*;
 import com.google.appengine.api.datastore.ReadPolicy.Consistency;

 ...

 // eventually consistent reads
 DatastoreServiceConfig config = withReadPolicy(new ReadPolicy(Consistency.EVENTUAL));

 // eventually consistent reads with a 5 second deadline
 DatastoreServiceConfig config =
   withReadPolicy(new ReadPolicy(Consistency.EVENTUAL)).deadline(5.0);
 

DatastoreServiceConfig.Builder

Contains static creation methods for DatastoreServiceConfig.

DatastoreServiceFactory

Creates DatastoreService implementations.

DeleteContext

Concrete CallbackContext implementation that is specific to delete() callbacks.

Email

An e-mail address datatype. Makes no attempt at validation. See Also: RFC 2822 for the e-mail address specification.

EmbeddedEntity

A property value containing embedded entity properties (and optionally a Key).

This class is similar to Entity, but differs in the following ways:

• #equals(Object) and #hashCode() compare the embedded properties in addition to the Key.
• It is not queryable when stored in the datastore.
• A Key is optional.
• Keys without a name or id are considered equal if all other aspects of the keys are equal (as they will not be assigned IDs by the datastore when embedded).

To convert from an Entity use:

 EmbeddedEntity sv = new EmbeddedEntity();
 sv.setKey(entity.getKey())
 sv.setPropertiesFrom(entity)
 

To convert to an Entity use:

 Entity entity = new Entity(sv.getKey())
 entity.setPropertiesFrom(sv);
 

Entities

Utility functions and constants for entities.

Entity

Entity is the fundamental unit of data storage. It has an immutable identifier (contained in the Key) object, a reference to an optional parent Entity, a kind (represented as an arbitrary string), and a set of zero or more typed properties.

EntityProtoComparators

Utilities for comparing EntityProto. This class is only public because the dev appserver needs access to it. It should not be accessed by user code.

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 extendable entity objects.

FetchOptions

Describes the limit, offset, and chunk size to be applied when executing a PreparedQuery.

limit is the maximum number of results the query will return.

offset is the number of results to skip before returning any results. Results that are skipped due to offset do not count against limit.
Note: Using offset still retrieves skipped entities internally. This affects the latency of the query, and your application is billed for the operations required to retrieve them. Using cursors lets you avoid these costs.

startCursor and endCursor are previously generated cursors that point to locations in a result set. If specified queries will start and end at these locations.

prefetchSize is the number of results retrieved on the first call to the datastore.

chunkSize determines the internal chunking strategy of the Iterator returned by PreparedQuery#asIterator(FetchOptions) and the Iterable returned by PreparedQuery#asIterable(FetchOptions).

Note that unlike limit, offset and cursor, prefetchSize and chunkSize have no impact on the result of the PreparedQuery, but rather only the performance of the PreparedQuery.

Notes on usage:
The recommended way to instantiate a FetchOptions object is to import FetchOptions and invoke a static creation method followed by an instance mutator (if needed):

 import com.google.appengine.api.datastore.FetchOptions;

 Cursor cursor = ...

 ...

 // limit 10
 datastoreService.prepare(query).asList(FetchOptions.Builder.withLimit(10));

 // limit 10, start cursor
 datastoreService.prepare(query).asList(FetchOptions.Builder.withLimit(10).startCursor(cursor));
 

FetchOptions.Builder

Contains static creation methods for FetchOptions.

FriendHacks

Provides limited access to unlaunched (package-private) methods and classes from outside this package. This class is not bundled with the API jar. As features launch, code should be updated to use the public interfaces instead of the contents of this class.

FutureHelper

Utilities for working with Futures in the synchronous datastore api.

GeoPt

A geographical point, specified by float latitude and longitude coordinates. Often used to integrate with mapping sites like Google Maps.

IDatastoreServiceFactoryProvider

Creates IDatastoreServiceFactory implementations.

Note: This class is not intended for end users.

IMHandle

An instant messaging handle. Includes both an address and its protocol. The protocol value is either a standard IM scheme (legal scheme values are defined by Scheme or a URL identifying the IM network for the protocol (e.g. http://aim.com/).

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.

A datastore GUID. A Key instance uniquely identifies an entity across all apps, and includes all information necessary to fetch the entity from the datastore with DatastoreService.get(Key).

You can create Key objects directly by using KeyFactory#createKey or #getChild.

You can also retrieve the Key automatically created when you create a new Entity, or serialize Key objects, or use KeyFactory to convert them to and from websafe String values. See Also: KeyFactory

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. Keys can also be created indirectly by putting named Entities into the datastore, which will allocate a new key. See Entity#Entity(String, String) for details.

This class also has methods for encoding and decoding Key objects to and from strings. Clients should not make any assumptions about the encoding format, except that it is a websafe string that does not need to be quoted when used in HTML or in URLs. See Also: Entity

KeyFactory.Builder

Helper class that aids in the construction of Keys with ancestors. Initialize the Builder with the topmost ancestor in your key path and then add children using the #addChild overload that best suits your needs. When finished adding children, call #getKey() to retrieve your Key or #getString() to retrieve your Key encoded as a websafe String.

Examples:

 import com.google.appengine.api.datastore.KeyFactory.Builder;

 ...

 Key key = new Builder("Person", 88).addChild("Address", 24).getKey();
 String keyStr = new Builder("Photo Album", "Vacation").addChild("Photo", 1424).getString();
 

KeyRange

Represents a range of unique datastore identifiers from getStart().getId() to getEnd().getId() inclusive. If an instance of this class is the result of a call to DatastoreService.allocateIds(), the Keys returned by this instance have been consumed in the datastore's id-space and are guaranteed never to be reused.
This class can be used to construct Entities with Keys that have specific id values without fear of the datastore creating new records with those same ids at a later date. This can be helpful as part of a data migration or large bulk upload where you may need to preserve existing ids and relationships between entities.
This class is threadsafe but the Iterators returned by #iterator() are not.

Link

A Link is a URL of limited length.

In addition to adding the meaning of URL onto a String, a Link can also be longer than a Text value, with a limit of 2083 characters.

PhoneNumber

A human-readable phone number. No validation is performed because phone numbers have many different formats - local, long distance, domestic, international, internal extension, TTY, VOIP, SMS, and alternative networks like Skype, XFire and Roger Wilco. They all have their own numbering and addressing formats.

PostLoadContext

Concrete CallbackContext implementation that is specific to intercepted operations that load Entities, currently get and "query". It is important to note that when a PostLoadContext is provided to a callback following a get operation, #getElements() returns all retrieved Entities. However, when a PostLoadContext is provided to a callback following a query, a separate PostLoadContext will be constructed for each Entity in the result set so #getElements() will only return a List containing a single Entity. This is due to the streaming nature of query responses.

PostalAddress

A human-readable mailing address. Mailing address formats vary widely so no validation is performed.

PreGetContext

Concrete CallbackContext implementation that is specific to intercepted get() operations. Methods annotated with PreGet that receive instances of this class may modify the result of the get() operation by calling #setResultForCurrentElement(Entity). Keys that receive results via this method will not be fetched from the datastore. This is an effective way to inject cached results.

PreQueryContext

Concrete CallbackContext implementation that is specific to intercepted queries. Methods annotated with PreQuery that receive instances of this class may modify the Query returned by calling #getCurrentElement(). This is an effective way to modify queries prior to execution.

Projection

A query projection. See Also: Query#getProjections()

PropertyContainer

A mutable property container.

PropertyProjection

A property projection.

If specified on a query, this will cause the query return the specified property. See Also: Query#getProjections()

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. It supports querying on zero or more properties, querying by ancestor, and sorting. Entity objects which match the query can be retrieved in a single list, or with an unbounded iterator.

Query.CompositeFilter

A Filter that combines several sub filters using a CompositeFilterOperator.

For example, to construct a filter of the form a = 1 AND (b = 2 OR c = 3) use:

 new CompositeFilter(CompositeFilterOperator.AND, Arrays.asList(
     new FilterPredicate("a", FilterOperator.EQUAL, 1),
     new CompositeFilter(CompositeFilterOperator.OR, Arrays.<Filter>asList(
         new FilterPredicate("b", FilterOperator.EQUAL, 2),
         new FilterPredicate("c", FilterOperator.EQUAL, 3)))));
 

or

 CompositeFilterOperator.and(
     FilterOperator.EQUAL.of("a", 1),
     CompositeFilterOperator.or(
         FilterOperator.EQUAL.of("b", 2),
         FilterOperator.EQUAL.of("c", 3)));
 

Query.Filter

The base class for a query filter.

All sub classes should be immutable.

Query.FilterPredicate

A Filter on a single property.

Query.GeoRegion

A geographic region intended for use in a StContainsFilter. Note that this is the only purpose for which it should be used: in particular, it is not suitable as a Property value to be stored in Datastore.

Query.GeoRegion.Circle

A geographical region representing all points within a fixed distance from a central point, i.e., a circle. Intended for use in a geo-containment predicate filter.

Query.GeoRegion.Rectangle

A simple geographical region bounded by two latitude lines, and two longitude lines, i.e., a "rectangle". It's not really a rectangle, of course, because longitude lines are not really parallel.

Intended for use in a geo-containment predicate filter.

Query.SortPredicate

SortPredicate is a data container that holds a single sort predicate.

Query.StContainsFilter

A Filter representing a geo-region containment predicate.

Rating

A user-provided integer rating for a piece of content. Normalized to a 0-100 scale.

RawValue

A raw datastore value.

These are returned by projection queries when a PropertyProjection does not specify a type. See Also: Query#getProjections()

ReadPolicy

Policy for reads.

ShortBlob

ShortBlob contains an array of bytes no longer than DataTypeUtils#MAX_SHORT_BLOB_PROPERTY_LENGTH. Unlike Blob, ShortBlobs are indexed by the datastore and can therefore be filtered and sorted on in queries. If your data is too large to fit in a ShortBlob use Blob instead.

Text

Text wraps around a string of unlimited size.

Ordinary Java strings stored as properties in Entity objects are limited to 1500 bytes. However, Text objects can also be stored in properties, and are unlimited in size. However, they will not be indexed for query purposes.

Consider using a standard Java string and storing it with the Entity#setUnindexedProperty method instead.

TransactionHelper

TransactionHelper enables the task queue API to serialize a datastore transaction without knowing the details of how it is implemented.

TransactionOptions

Describes options for transactions, passed at transaction creation time.

Notes on usage:
The recommended way to instantiate a TransactionsOptions object is to statically import Builder.* and invoke a static creation method followed by an instance mutator (if needed):

 import static com.google.appengine.api.datastore.TransactionOptions.Builder.*;

 ...

 datastoreService.beginTransaction(withXG(true));
 

TransactionOptions.Builder

Contains static creation methods for TransactionOptions.

Interfaces

AsyncDatastoreService

An asynchronous version of DatastoreService. All methods return immediately and provide Futures as their return values.

The key difference between implementations of AsyncDatastoreService and implementations of DatastoreService is that async implementations do not perform implicit transaction management. The reason is that implicit transaction management requires automatic commits of some transactions, and without some sort of callback mechanism there is no way to determine that a put/get/delete that has been implicitly enrolled in a transaction is complete and therefore ready to be committed. See ImplicitTransactionManagementPolicy for more information.

BaseDatastoreService

Methods that are common between DatastoreService and AsyncDatastoreService.

CallbackContext<T>

Describes the context in which a callback runs. The context has access to the current transaction (if any), the element that the callback is operating on (eg the Entity being put or the Key being deleted), as well as all elements being operated on in the operation that triggered the callback..

DatastoreConfig (deprecated)

Deprecated. Use DatastoreServiceConfig instead.

User-configurable properties of the datastore.

DatastoreService

The DatastoreService provides synchronous access to a schema-less data storage system. The fundamental unit of data in this system is the Entity, which has an immutable identity (represented by a Key) and zero or more mutable properties. Entity objects can be created, updated, deleted, retrieved by identifier, and queried via a combination of properties.

The DatastoreService can be used transactionally and supports the notion of a "current" transaction. A current transaction is established by calling #beginTransaction(). The transaction returned by this method ceases to be current when an attempt is made to commit or rollback or when another call is made to #beginTransaction(). A transaction can only be current within the Thread that created it.

The various overloads of put, get, and delete all support transactions. Users of this class have the choice of explicitly passing a (potentially null) Transaction to these methods or relying on the behavior governed by the ImplicitTransactionManagementPolicy. If a user explicitly provides a Transaction it is up to the user to call Transaction#commit() or Transaction#rollback() at the proper time. If a user relies on implicit transaction management and the installed policy creates a transaction, that transaction will be committed (in the case of a success) or rolled back (in the case of a failure) before the operation returns to the user. The methods that manage transactions according to ImplicitTransactionManagementPolicy are: #delete(Key...), #delete(Iterable), #get(Key), #get(Iterable), #put(Entity), and #put(Iterable).

The overload of prepare that takes a Transaction parameter behaves the same as the overloads of put, get, and delete that take a Transaction parameter. However, the overload of prepare that does not take a Transaction parameter, unlike put, get, and delete, does not use an existing Transaction if one is already running and does not consult the ImplicitTransactionManagementPolicy if one is not already running.

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. If the Query specified a sort order, Entities are returned in that order. Otherwise, the order is undefined.

A PreparedQuery does not cache results. Each use of PreparedQuery results in a new trip to the datastore.

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. Operations performed as part of a single Transaction succeed or fail as a unit. Transactions can be committed and rolled back synchronously and asynchronously.

Enums

CloudDatastoreRemoteServiceConfig.AppId.Location

Locations for App Engine applications.

CompositeIndexManager.IndexSource

The source of an index in the index file. These are used as literals in an xml document that we read and write.

DatastoreAttributes.DatastoreType

Indicates the type of datastore being used. Currently always returns HIGH_REPLICATION.

DatastoreService.KeyRangeState

Indicates the state of a KeyRange. See Also: DatastoreService#allocateIdRange(KeyRange)

IMHandle.Scheme

Supported IM schemes.

ImplicitTransactionManagementPolicy

Describes the various policies the datastore can follow for implicit transaction management. When deciding which policy to use, keep the following in mind: The datastore will automatically retry operations that fail due to concurrent updates to the same entity group if the operation is not part of a transaction. The datastore will not retry operations that fail due to concurrent updates to the same entity group if the operation is part of a transaction, and will instead immediately throw a ConcurrentModificationException. If your application needs to perform any sort of intelligent merging when concurrent attempts are made to update the same entity group you probably want #AUTO, otherwise #NONE is probably acceptable.

See DatastoreService for a list of operations that perform implicit transaction management.

Index.IndexState

Indicates the state of the Index.

Query.CompositeFilterOperator

Operators supported by CompositeFilter.

Query.FilterOperator

Operators supported by 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.

TransactionOptions.Mode

The mode of the transaction.

Exceptions

CommittedButStillApplyingException

CommittedButStillApplyingException is thrown when the write or transaction was committed, but some entities or index rows may not have been fully updated. Those updates should automatically be applied soon. You can roll them forward immediately by reading one of the entities inside a transaction.

DatastoreFailureException

DatastoreFailureException is thrown when any unknown error occurs while communicating with the data store.

Clients should not attempt to retry after receiving this exception.

DatastoreNeedIndexException

DatastoreNeedIndexException is thrown when no matching index was found for a query requiring an index. Check the Indexes page in the Admin Console and your datastore-indexes.xml file.

DatastoreTimeoutException

DatastoreTimeoutException is thrown when a datastore operation times out. This can happen when you attempt to put, get, or delete too many entities or an entity with too many properties, or if the datastore is overloaded or having trouble.

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

PostDelete

Identifies a callback method to be invoked after an Entity of any of the specified kinds is deleted from the datastore. If #kinds() is not provided the callback will execute for all kinds. Methods with this annotation must return void, must accept a single argument of type DeleteContext, must not throw any checked exceptions, must not be static, and must belong to a class with a no-arg constructor. Neither the method nor the no-arg constructor of the class to which it belongs are required to be public. Methods with this annotation are free to throw any unchecked exception they like. Throwing an unchecked exception will prevent callbacks that have not yet been executed from running, and the exception will propagate to the code that invoked the datastore operation that resulted in the invocation of the callback. Throwing an unchecked exception from a callback will not have any impact on the result of the datastore operation. Methods with this annotation will not be invoked if the datastore operation fails.

PostLoad

Identifies a callback method to be invoked after an Entity of any of the specified kinds is loaded from the datastore. This can happen as the result of a get() operation or a query. If #kinds() is not provided the callback will execute for all kinds. Methods with this annotation must return void, must accept a single argument of type PostLoadContext, must not throw any checked exceptions, must not be static, and must belong to a class with a no-arg constructor. Neither the method nor the no-arg constructor of the class to which it belongs are required to be public. Methods with this annotation are free to throw any unchecked exception they like. Throwing an unchecked exception will prevent callbacks that have not yet been executed from running, and the exception will propagate to the code that invoked the datastore operation that resulted in the invocation of the callback. Throwing an unchecked exception from a callback will not have any impact on the result of the datastore operation. Methods with this annotation will not be invoked if the datastore operation fails.

PostPut

Identifies a callback method to be invoked after an Entity of any of the specified kinds is written to the datastore. If #kinds() is not provided the callback will execute for all kinds. Methods with this annotation must return void, must accept a single argument of type PutContext, must not throw any checked exceptions, must not be static, and must belong to a class with a no-arg constructor. Neither the method nor the no-arg constructor of the class to which it belongs are required to be public. Methods with this annotation are free to throw any unchecked exception they like. Throwing an unchecked exception will prevent callbacks that have not yet been executed from running, and the exception will propagate to the code that invoked the datastore operation that resulted in the invocation of the callback. Throwing an unchecked exception from a callback will not have any impact on the result of the datastore operation. Methods with this annotation will not be invoked if the datastore operation fails.

PreDelete

Identifies a callback method to be invoked before an Entity of any of the specified kinds is deleted from the datastore. If #kinds() is not provided the callback will execute for all kinds. Methods with this annotation must return void, must accept a single argument of type DeleteContext, must not throw any checked exceptions, must not be static, and must belong to a class with a no-arg constructor. Neither the method nor the no-arg constructor of the class to which it belongs are required to be public. Methods with this annotation are free to throw any unchecked exception they like. Throwing an unchecked exception will prevent callbacks that have not yet been executed from running, and the exception will propagate to the code that invoked the datastore operation that resulted in the invocation of the callback. Throwing an unchecked exception from a callback will prevent the datastore operation from executing.

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. If #kinds() is not provided the callback will execute for all kinds. Methods with this annotation must return void, must accept a single argument of type PreGetContext, must not throw any checked exceptions, must not be static, and must belong to a class with a no-arg constructor. Neither the method nor the no-arg constructor of the class to which it belongs are required to be public. Methods with this annotation are free to throw any unchecked exception they like. Throwing an unchecked exception will prevent callbacks that have not yet been executed from running, and the exception will propagate to the code that invoked the datastore operation that resulted in the invocation of the callback. Throwing an unchecked exception from a callback will prevent the datastore operation from executing.

PrePut

Identifies a callback method to be invoked before an Entity of any of the specified kinds is written to the datastore. If #kinds() is not provided the callback will execute for all kinds. Methods with this annotation must return void, must accept a single argument of type PutContext, must not throw any checked exceptions, must not be static, and must belong to a class with a no-arg constructor. Neither the method nor the no-arg constructor of the class to which it belongs are required to be public. Methods with this annotation are free to throw any unchecked exception they like. Throwing an unchecked exception will prevent callbacks that have not yet been executed from running, and the exception will propagate to the code that invoked the datastore operation that resulted in the invocation of the callback. Throwing an unchecked exception from a callback will prevent the datastore operation from executing.

PreQuery

Identifies a callback method to be invoked before a Query for any of the specified kinds is executed against the datastore. If #kinds() is not provided the callback will execute for queries against all kinds, including kind-less queries. Methods with this annotation must return void, must accept a single argument of type PreQueryContext, must not throw any checked exceptions, must not be static, and must belong to a class with a no-arg constructor. Neither the method nor the no-arg constructor of the class to which it belongs are required to be public. Methods with this annotation are free to throw any unchecked exception they like. Throwing an unchecked exception will prevent callbacks that have not yet been executed from running, and the exception will propagate to the code that invoked the datastore operation that resulted in the invocation of the callback. Throwing an unchecked exception from a callback will prevent the datastore operation from executing.