java/src/main/com/google/appengine/spi/ServiceProvider.java

   1 // Copyright 2012 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.spi;
   4
   5 import java.lang.annotation.Documented;
   6 import java.lang.annotation.ElementType;
   7 import java.lang.annotation.Retention;
   8 import java.lang.annotation.RetentionPolicy;
   9 import java.lang.annotation.Target;
  10
  11 /**
  12  * An annotation for service providers as described in {@link java.util.ServiceLoader}.
  13  * The
  14  * {@link com.google.appengine.spi.ServiceProviderProcessor ServiceProviderProcessor}
  15  * generates the configuration files which allows service providers
  16  * to be loaded with {@link java.util.ServiceLoader#load(Class) ServiceLoader.load(Class)}.
  17  * You must enable the processor, typically by specifying
  18  *   {@code "-processor com.google.appengine.spi.ServiceProviderProcessor"}
  19  * as a flag to javac.
  20  *
  21  * <p>
  22  * Service providers assert that they conform to the service provider
  23  * specification. Specifically they must:<ul>
  24  *  <li>be a non-inner, non-anonymous, concrete class</li>
  25  *  <li>have a publically accessible no-arg constructor</li>
  26  *  <li>implement the interface type returned by {@code value()}</li>
  27  * </ul>
  28  *
  29  */
  30 @Documented
  31 @Retention(RetentionPolicy.RUNTIME)
  32 @Target(ElementType.TYPE)
  33 public @interface ServiceProvider {
  34
  35   public static final int DEFAULT_PRECEDENCE = 0;
  36
  37   /**
  38    * Returns the interface implemented by this ServiceProvider.
  39    */
  40   Class<?> value();
  41
  42   /**
  43    * Higher precedence will take priority over lower precedences for a given <code>value</code>.
  44    */
  45   int precedence() default DEFAULT_PRECEDENCE;
  46 }