001package io.avaje.inject;
002
003import static java.lang.annotation.ElementType.MODULE;
004import static java.lang.annotation.ElementType.PACKAGE;
005import static java.lang.annotation.ElementType.TYPE;
006import static java.lang.annotation.RetentionPolicy.CLASS;
007
008import java.lang.annotation.Retention;
009import java.lang.annotation.Target;
010
011/**
012 * Used to explicitly specify if it depends on externally provided beans or provides.
013 *
014 * <h3>External dependencies</h3>
015 * <p>
016 * Use {@code requires} to specify dependencies that will be provided externally.
017 *
018 * <pre>{@code
019 *
020 *   // tell the annotation processor Pump and Grinder are provided externally
021 *   // otherwise it will think we have missing dependencies at compile time
022 *
023 *   @InjectModule(requires = {Pump.class, Grinder.class})
024 *
025 * }</pre>
026 *
027 * <h3>Custom scope depending on another scope</h3>
028 * <p>
029 * When using custom scopes we can have the case where we desire one scope to depend
030 * on another. In this case we put the custom scope annotation in requires.
031 * <p>
032 * For example lets say we have a custom scope called {@code StoreComponent} and that
033 * depends on {@code QueueComponent} custom scope.
034 *
035 * <pre>{@code
036 *
037 *   @Scope
038 *   @InjectModule(requires = {QueueComponent.class})
039 *   public @interface StoreComponent {
040 *   }
041 *
042 *
043 * }</pre>
044 */
045@Retention(CLASS)
046@Target({TYPE, PACKAGE, MODULE})
047public @interface InjectModule {
048
049  /**
050   * Explicitly specify the name of the module.
051   */
052  String name() default "";
053
054  /**
055   * Set to true to ignore anything annotated with <code>@Singleton</code>.
056   * <p>
057   * Set this to true when some other library is using <code>@Singleton</code> and we want
058   * avaje-inject to be completely independent of that by ignoring the standard <code>@Singleton</code>.
059   * <p>
060   * We instead use <code>@Component</code> instead of <code>@Singleton</code>.
061   */
062  boolean ignoreSingleton() default false;
063
064  /**
065   * Explicitly define features that are provided by this module and required by other modules.
066   * <p>
067   * This is used to order wiring across multiple modules. Modules that provide dependencies
068   * should be wired before modules that require dependencies.
069   */
070  Class<?>[] provides() default {};
071
072  /**
073   * The dependencies that are provided externally or by other modules and that are required
074   * when wiring this module.
075   * <p>
076   * This effectively tells the annotation processor that these types are expected to be
077   * provided and to not treat them as missing dependencies. If we don't do this the annotation
078   * processor thinks the dependency is missing and will error the compilation saying there is
079   * a missing dependency.
080   */
081  Class<?>[] requires() default {};
082
083  /**
084   * Dependencies in these packages are expected to be provided by other modules.
085   * <p>
086   * Instead of listing each and every dependency in {@code requires} we can use this to specify
087   * that any required dependency that is in these packages is expected to be provided by another module.
088   * <p>
089   * Use this rather than {@code requires} when there are lots of required dependencies, and we don't
090   * want to list each one in {@code requires} and {@code provides}.
091   */
092  Class<?>[] requiresPackages() default {};
093
094  /**
095   * Internal use only - identifies the custom scope annotation associated to this module.
096   * <p>
097   * When a module is generated for a custom scope this is set to link the module back to the
098   * custom scope annotation and support partial compilation.
099   */
100  String customScopeType() default "";
101
102}