shaded.com.google.inject.RestrictedBindingSource Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of spring-cloud-contract-shade Show documentation
Spring Cloud Contract Shaded Dependencies
There is a newer version: 4.1.4
Show newest version
package shaded.shaded.com.google.inject;

import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

/**
 * Annotation restricting the binding of the target type to permitted sources.
 *
 * Bindings restricted by this annotation may only be created by sources annotated with a permit
 * from {@link #permits} -- otherwise, an error message including the {@link #explanation} is
 * issued.
 *
 * 
There are two kinds of binding source:
 *
 * 

 *   Module: a module is the source of a binding if it creates it (either directly, or
 *       indirectly by installing another module). For example: if module A creates restricted
 *       binding X, and module C installs module B that installs A; then all 3 modules C,B,A are
 *       sources of X, and it's enough for any one of them to be annotated with a permit from X's
 *       restriction.
 *   
Method Scanner ({@code ModuleAnnotatedMethodScanner}): If a binding was created by a
 *       scanner, then that scanner is also a source of the binding (in addition to the module
 *       sources) and a permit may be given to the scanner by annotating its class.
 * 
 *
 * Bindings with qualifier annotations are restricted solely by the annotation on their qualifier
 * (restrictions on the type are ignored for qualified bindings). Unqualified bindings are
 * restricted by the annotation on their type.
 *
 * 
This allows libraries to prevent their clients from binding their keys, similar to how
 * declaring a class final prevents subtyping. For example, a library may want to prevent users from
 * creating mock bindings for tests, using the {@link #explanation} - included in the error message
 * - to point them to a supported testing module.
 *
 * 
Example usage:
 *
 * 
{@code
 * @RestrictedBindingSource.Permit
 * @Retention(RetentionPolicy.RUNTIME)
 * @interface NetworkPermit {}
 *
 * @RestrictedBindingSource(
 *   explanation = "Only NetworkModule can create network bindings.",
 *   permits = {NetworkPermit.class})
 * @Qualifier
 * @Retention(RetentionPolicy.RUNTIME)
 * public @interface GatewayIpAdress {}
 *
 * @NetworkPermit
 * public final class NetworkModule extends AbstractModule {
 *   @Provides
 *   @GatewayIpAdress // Allowed because the module is annotated with @NetworkPermit.
 *   int provideGatewayIp() { ... }
 * }
 * }
 *
 * @author [email protected] (Vladimir Makaric)
 * @since 5.0
 */
@Inherited
@Retention(RUNTIME)
@Target(TYPE)
public @interface RestrictedBindingSource {
  /**
   * Explanation of why binding this target type is restricted.
   *
   * Will appear as the error message if the target type is bound by non-allowed modules.
   */
  String explanation();

  /**
   * Meta-annotation indicating that the target annotation is a permit for binding restricted
   * bindings. Annotating a binding source (defined in top-level javadoc) with a permit gives it
   * permission to bind the restricted bindings guarded by the permit (see {@link #permits}).
   *
   * @since 5.0
   */
  @Documented
  @Retention(RUNTIME)
  @Target(ANNOTATION_TYPE)
  public @interface Permit {}

  /**
   * List of {@code Permit} annotations (must be non-empty), one of which has has to be present on a
   * restricted binding's source (defined in top-level javadoc).
   */
  Class[] permits();

  /**
   * Exempt modules whose fully qualified class names match this regex.
   *
   * 
If any module on the binding's module stack matches this regex, the binding is allowed (no
   * permit necessary). No module is exempt by default (empty string).
   *
   * Inteded to be used when retrofitting a binding with this restriction. When restricting an
   * existing binding, it's often practical to first restrict with exemptions for existing
   * violations (to prevent new violations), before updating the code in violation to use the
   * permitted module(s).
   */
  String exemptModules() default "";

  /**
   * Level of restriction. Determines how violations are handled.
   *
   * @since 5.0
   */
  public static enum RestrictionLevel {
    WARNING,
    ERROR;
  }

  RestrictionLevel restrictionLevel() default RestrictionLevel.ERROR;
}