java/src/main/com/google/appengine/api/datastore/PreQuery.java

   1 // Copyright 2012 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.datastore;
   4
   5 import java.lang.annotation.ElementType;
   6 import java.lang.annotation.Retention;
   7 import java.lang.annotation.RetentionPolicy;
   8 import java.lang.annotation.Target;
   9
  10 /**
  11  * Identifies a callback method to be invoked before a {@link Query} for any
  12  * of the specified kinds is executed against the datastore.  If {@link #kinds()}
  13  * is not provided the callback will execute for queries against all kinds,
  14  * including kind-less queries.  Methods with this annotation must return
  15  * {@code void}, must accept a single argument of type {@link PreQueryContext},
  16  * must not throw any checked exceptions, must not be static, and must belong
  17  * to a class with a no-arg constructor.  Neither the method nor the no-arg
  18  * constructor of the class to which it belongs are required to be public.
  19  * Methods with this annotation are free to throw any unchecked exception they
  20  * like.  Throwing an unchecked exception will prevent callbacks that have not
  21  * yet been executed from running, and the exception will propagate to the code
  22  * that invoked the datastore operation that resulted in the invocation of the
  23  * callback.  Throwing an unchecked exception from a callback will prevent the
  24  * datastore operation from executing.
  25  *
  26  */
  27 @Target(ElementType.METHOD)
  28 @Retention(RetentionPolicy.RUNTIME)
  29 public @interface PreQuery {
  30
  31   /**
  32    * The kinds to which this callback applies.  The default value is an empty
  33    * array, which indicates that the callback should run for all kinds.
  34    *
  35    * @return The kinds to which this callback applies.
  36    */
  37   String[] kinds() default {};
  38 }