Datastore Callbacks

Note: Callbacks are not triggered if the App Engine app is called by some other app using the Remote API.

A callback allows you to execute code at various points in the persistence process. You can use these callbacks to easily implement cross-functional logic like logging, sampling, decoration, auditing, and validation (among other things). The Datastore API currently supports callbacks that execute before and after put() and delete() operations.

PrePut

When you register a PrePut callback with a specific kind, the callback will be invoked before any entity of that kind is put (or, if no kind is provided, before any entity is put):

importcom.google.appengine.api.datastore.PrePut ;
importcom.google.appengine.api.datastore.PutContext ;
importjava.util.Date;
importjava.util.logging.Logger;
class PrePutCallbacks{
staticLoggerlogger=Logger.getLogger("callbacks");
@PrePut(kinds={"Customer","Order"})
voidlog(PutContext context){
logger.fine("Putting "+context.getCurrentElement ().getKey());
}
@PrePut// Applies to all kinds
voidupdateTimestamp(PutContext context){
context.getCurrentElement ().setProperty ("last_updated",newDate());
}
}

A method annotated with PrePut must be an instance method that returns void, accepts a PutContext as its only argument, does not throw any checked exceptions, and belongs to a class with a no-arg constructor. When a PrePut callback throws an exception, no further callbacks are executed, and the put() operation throws the exception before any RPCs are issued to the datastore.

PostPut

When you register a PostPut callback with a specific kind, the callback will be invoked after any entity of that kind is put (or, if no kind is provided, after any entity is put).

importcom.google.appengine.api.datastore.PostPut ;
importcom.google.appengine.api.datastore.PutContext ;
importjava.util.logging.Logger;
class PostPutCallbacks{
staticLoggerlogger=Logger.getLogger("logger");
@PostPut(kinds={"Customer","Order"})// Only applies to Customers and Orders
voidlog(PutContext context){
logger.fine("Finished putting "+context.getCurrentElement ().getKey());
}
@PostPut// Applies to all kinds
voidcollectSample(PutContext context){
Sampler.getSampler().collectSample(
"put",context.getCurrentElement ().getKey());
}
}

A method annotated with PostPut must be an instance method that returns void, accepts a PutContext as its only argument, does not throw any checked exceptions, and belongs to a class with a no-arg constructor. When a PostPut callback throws an exception, no further callbacks are executed but the result of the put() operation is unaffected. Note that if the put() operation itself fails, PostPut callbacks will not be invoked at all. Also, PostPut callbacks that are associated with transactional put() operations will not run until the transaction successfully commits.

PreDelete

When you register a PreDelete callback with a specific kind, the callback will be invoked before any entity of that kind is deleted (or, if no kind is provided, before any entity is deleted):

importcom.google.appengine.api.datastore.DeleteContext ;
importcom.google.appengine.api.datastore.PreDelete ;
importjava.util.logging.Logger;
class PreDeleteCallbacks{
staticLoggerlogger=Logger.getLogger("logger");
@PreDelete(kinds={"Customer","Order"})
voidcheckAccess(DeleteContext context){
if(!Auth.canDelete(context.getCurrentElement ()){
thrownewSecurityException();
}
}
@PreDelete// Applies to all kinds
voidlog(DeleteContext context){
logger.fine("Deleting "+context.getCurrentElement ().getKey());
}
}

A method annotated with PreDelete must be an instance method that returns void, accepts a DeleteContext as its only argument, does not throw any checked exceptions, and belongs to a class with a no-arg constructor. When a PreDelete callback throws an exception, no further callbacks are executed and the delete() operation throws the exception before any RPCs are issued to the datastore.

PostDelete

When you register a PostDelete callback with a specific kind, the callback will be invoked after any entity of that kind is deleted (or, if no kind is provided, after any entity is deleted):

importcom.google.appengine.api.datastore.DeleteContext ;
importcom.google.appengine.api.datastore.PostDelete ;
importjava.util.logging.Logger;
class PostDeleteCallbacks{
staticLoggerlogger=Logger.getLogger("logger");
@PostDelete(kinds={"Customer","Order"})
voidlog(DeleteContext context){
logger.fine(
"Finished deleting "+context.getCurrentElement ().getKey());
}
@PostDelete// Applies to all kinds
voidcollectSample(DeleteContext context){
Sampler.getSampler().collectSample(
"delete",context.getCurrentElement ().getKey());
}
}

A method annotated with PostDelete must be an instance method that returns void, accepts a DeleteContext as its only argument, does not throw any checked exceptions, and belongs to a class with a no-arg constructor. When a PostDelete callback throws an exception, no further callbacks are executed but the result of the delete() operation is unaffected. Note that if the delete() operation itself fails, PostDelete callbacks will not be invoked at all. Also, PostDelete callbacks that are associated with transactional delete() operations will not run until the transaction successfully commits.

PreGet

You can register a PreGet callback to be called before getting entities of some specific kinds (or all kinds). You might use this, for example, to intercept some get requests and fetch the data from a cache instead of from the datastore.

importcom.google.appengine.api.datastore.Entity ;
importcom.google.appengine.api.datastore.PreGetContext ;
importcom.google.appengine.api.datastore.PreGet ;
class PreGetCallbacks{
@PreGet(kinds={"Customer","Order"})
publicvoidpreGet(PreGetContext context){
Entity e=MyCache.get(context.getCurrentElement ());
if(e!=null){
context.setResultForCurrentElement (e);
}
// if not in cache, don't set result; let the normal datastore-fetch happen
}
}

PreQuery

You can register a PreQuery callback to be called before executing queries for specific kinds (or all kinds). You might use this, for example, to add an equality filter based on the logged in user. The callback is passed the query; by modifying it, the callback can cause a different query to be executed instead. Or the callback can throw an unchecked exception to prevent the query from being executed.

importcom.google.appengine.api.datastore.PreQueryContext ;
importcom.google.appengine.api.datastore.PreQuery ;
importcom.google.appengine.api.datastore.Query ;
importcom.google.appengine.api.users.UserService ;
importcom.google.appengine.api.users.UserServiceFactory ;
class PreQueryCallbacks{
@PreQuery(kinds={"Customer"})
// Queries should only return data owned by the logged in user.
publicvoidpreQuery(PreQueryContext context){
UserService users=UserServiceFactory .getUserService();
context.getCurrentElement ().setFilter (
newFilterPredicate ("owner",Query .FilterOperator.EQUAL,users.getCurrentUser ()));
}
}

PostLoad

You can register a PostLoad callback to be called after loading entities of specific kinds (or all kinds). Here, "loading" might mean the result of a get or a query. This is useful for decorating loaded entities.

importcom.google.appengine.api.datastore.PostLoadContext ;
importcom.google.appengine.api.datastore.PostLoad ;
class PostLoadCallbacks{
@PostLoad(kinds={"Order"})
publicvoidpostLoad(PostLoadContext context){
context.getCurrentElement ().setProperty ("read_timestamp",
System.currentTimeMillis());
}
}

Batch Operations

When you execute a batch operation (a put() with multiple entities for example), your callbacks are invoked once per entity. You can access the entire batch of objects by calling CallbackContext.getElements() on the argument to your callback method. This allows you to implement callbacks that operate on the entire batch instead of one element at a time.

importcom.google.appengine.api.datastore.PrePut ;
importcom.google.appengine.api.datastore.PutContext ;
class Validation{
@PrePut(kinds="TicketOrder")
voidcheckBatchSize(PutContext context){
if(context.getElements ().size()>5){
thrownewIllegalArgumentException(
"Cannot purchase more than 5 tickets at once.");
}
}
}

If you need your callback to only execute once per batch, use CallbackContext.getCurrentIndex() to determine if you're looking at the first element of the batch.

importcom.google.appengine.api.datastore.PrePut ;
importcom.google.appengine.api.datastore.PutContext ;
importjava.util.logging.Logger;
class Validation{
staticLoggerlogger=Logger.getLogger("logger");
@PrePut
voidlog(PutContext context){
if(context.getCurrentIndex ()==0){
logger.fine("Putting batch of size "+getElements().size());
}
}
}

Async Operations

There are a few important things to know about how callbacks interact with async datastore operations. When you execute a put() or a delete() using the async datastore API, any Pre* callbacks that you've registered will execute synchronously. Your Post* callbacks will execute synchronously as well, but not until you call any of the Future.get() methods to retrieve the result of the operation.

Using Callbacks With App Engine Services

Callbacks, like any other code in your application, have access to the full range of App Engine backend services, and you can define as many as you want in a single class.

importcom.google.appengine.api.datastore.DatastoreService ;
importcom.google.appengine.api.datastore.DatastoreServiceFactory ;
importcom.google.appengine.api.datastore.DeleteContext ;
importcom.google.appengine.api.datastore.PrePut ;
importcom.google.appengine.api.datastore.PostPut ;
importcom.google.appengine.api.datastore.PostDelete ;
importcom.google.appengine.api.datastore.PutContext ;
importcom.google.appengine.api.memcache.MemcacheService ;
importcom.google.appengine.api.memcache.MemcacheServiceFactory ;
importcom.google.appengine.api.taskqueue.Queue ;
importcom.google.appengine.api.taskqueue.QueueFactory ;
importcom.google.appengine.api.urlfetch.URLFetchService ;
importcom.google.appengine.api.urlfetch.URLFetchServiceFactory ;
class ManyCallbacks{
@PrePut(kinds={"kind1","kind2"})
voidfoo(PutContext context){
MemcacheService ms=MemcacheServiceFactory .getMemcacheService();
// ...
}
@PrePut
voidbar(PutContext context){
DatastoreService ds=DatastoreServiceFactory .getDatastoreService();
// ...
}
@PostPut(kinds={"kind1","kind2"})
voidbaz(PutContext context){
Queue q=QueueFactory .getDefaultQueue ();
// ...
}
@PostDelete(kinds={"kind2"})
voidyam(DeleteContext context){
URLFetchService us=URLFetchServiceFactory .getURLFetchService();
// ...
}
}

Common Errors To Avoid

There are a number of common errors to be aware of when implementing callbacks.

• Do Not Maintain Non-static State
• Do Not Make Assumptions About Callback Execution Order
• One Callback Per Method
• Do Not Forget To Retrieve Async Results
• Avoid Infinite Loops

Do Not Maintain Non-static State

importjava.util.logging.Logger;
importcom.google.appengine.api.datastore.PrePut ;
class MaintainsNonStaticState{
staticLoggerlogger=Logger.getLogger("logger");
// ERROR!
// should be static to avoid assumptions about lifecycle of the instance
booleanalreadyLogged=false;
@PrePut
voidlog(PutContext context){
if(!alreadyLogged){
alreadyLogged=true;
logger.fine(
"Finished deleting "+context.getCurrentElement ().getKey());
}
}
}

Do Not Make Assumptions About Callback Execution Order

Pre* callbacks will always execute before Post* callbacks, but it is not safe to make any assumptions about the order in which a Pre* callback executes relative to other Pre* callbacks, nor is it safe to make any assumptions about the order in which a Post* callback executes relative to other Post* callbacks.

importcom.google.appengine.api.datastore.Entity ;
importcom.google.appengine.api.datastore.PrePut ;
importjava.util.HashSet;
importjava.util.Set;
class MakesAssumptionsAboutOrderOfCallbackExecution{
staticSet<Key>paymentKeys=newHashSet<Key>();
@PrePut(kinds="Order")
voidprePutOrder(PutContext context){
Entity order=context.getCurrentElement ();
paymentKeys.addAll((Collection<Key>)order.getProperty ("payment_keys"));
}
@PrePut(kinds="Payment")
voidprePutPayment(PutContext context){
// ERROR!
// Not safe to assume prePutOrder() has already run!
if(!paymentKeys.contains(context.getCurrentElement ().getKey()){
thrownewIllegalArgumentException("Unattached payment!");
}
}
}

One Callback Per Method

Even though a class can have an unlimited number of callback methods, a single method can only be associated with a single callback.

importcom.google.appengine.api.datastore.PrePut ;
importcom.google.appengine.api.datastore.PostPut ;
class MultipleCallbacksOnAMethod{
@PrePut
@PostPut// Compiler error!
voidfoo(PutContext context){}
}

Do Not Forget To Retrieve Async Results

Post* callbacks do not run until you call Future.get() to retrieve the result of the operation. If you forget to call Future.get() before you finish servicing the HTTP request, your Post* callbacks will not run.

importcom.google.appengine.api.datastore.AsyncDatastoreService ;
importcom.google.appengine.api.datastore.DatastoreServiceFactory ;
importcom.google.appengine.api.datastore.Entity ;
importcom.google.appengine.api.datastore.PostPut ;
importcom.google.appengine.api.datastore.PutContext ;
importjava.util.concurrent.Future;
class IgnoresAsyncResult{
AsyncDatastoreService ds=DatastoreServiceFactory .getAsyncDatastoreService();
@PostPut
voidcollectSample(PutContext context){
Sampler.getSampler().collectSample(
"put",context.getCurrentElement ().getKey());
}
voidaddOrder(Entity order){
Futureresult=ds.put (order);
// ERROR! Never calls result.get() so collectSample() will not run.
}
}

Avoid Infinite Loops

If you perform datastore operations in your callbacks, be careful not to fall into an infinite loop.

importcom.google.appengine.api.datastore.DatastoreService ;
importcom.google.appengine.api.datastore.DatastoreServiceFactory ;
importcom.google.appengine.api.datastore.Entity ;
importcom.google.appengine.api.datastore.PrePut ;
importcom.google.appengine.api.datastore.PutContext ;
class InfiniteLoop{
DatastoreService ds=DatastoreServiceFactory .getDatastoreService();
@PrePut
voidaudit(PutContext context){
Entity original=ds.get (context.getCurrentElement().getKey());
Entity auditEntity=newEntity (original.getKind ()+"_audit");
auditEntity.setPropertiesFrom (original);
// INFINITE LOOP!
// Restricting the callback to specific kinds would solve this.
ds.put (auditEntity);
}
}

Using Callbacks With Eclipse

If you are developing your app with Eclipse you will need to perform a small number of configuration steps to use datastore callbacks. These steps are for Eclipse 3.7. We expect to make these steps unnecessary in a future release of the Google Plugin For Eclipse.

• Open the Properties dialog for your Project (Project > Properties)
• Open the Annotation Processing dialog (Java Compiler > Annotation Processing)
• Check "Enable annotation processing"
• Check "Enable processing in editor"
• Open the Factory Path dialog (Java Compiler > Annotation Processing > Factory Path)
• Click "Add External JARs"
• Select <SDK_ROOT>/lib/impl/appengine-api.jar (where SDK_ROOT is the top level directory of your sdk installation)
• Click "OK"

You can verify that callbacks are properly configured by implementing a method with multiple callbacks (see the code snippet under One Callback Per Method). This should generate a compiler error.