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.SOURCE;
007
008import java.lang.annotation.Retention;
009import java.lang.annotation.Target;
010
011/**
012 * Used to explicitly specify whether the current module depends on/provides beans or aspects.
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(SOURCE)
046@Target({TYPE, PACKAGE, MODULE})
047public @interface InjectModule {
048
049  /**
050   * Optimizes module wiring by enforcing multi-module wiring checks at compile-time.
051   * Will throw a compilation error if all inter-module {@link InjectModule#requires requires}
052   * dependencies are not satisfied.
053   *
054   * <p>Set true if your project:
055   *
056   * <ol>
057   *   <li>Is not a library
058   *   <li>Does not dynamically provide beans at runtime
059   * </ol>
060   */
061  boolean strictWiring() default false;
062
063  /**
064   * Explicitly specify the name of the module.
065   */
066  String name() default "";
067
068  /**
069   * Set to true to ignore anything annotated with <code>@Singleton</code>.
070   * <p>
071   * Set this to true when some other library is using <code>@Singleton</code> and we want
072   * avaje-inject to be completely independent of that by ignoring the standard <code>@Singleton</code>.
073   * <p>
074   * We instead use <code>@Component</code> instead of <code>@Singleton</code>.
075   */
076  boolean ignoreSingleton() default false;
077
078  /**
079   * Explicitly define beans that are provided by this module and required by other modules.
080   *
081   * <p>This is used to order wiring across multiple modules. Modules that provide dependencies
082   * should be wired before modules that require dependencies.
083   */
084  Class<?>[] provides() default {};
085
086  /**
087   * Required external beans for wiring this module.
088   *
089   * <p>This tells the annotation processor that these types are expected to be provided and to not
090   * treat them as missing dependencies. If we don't do this the annotation processor thinks the
091   * dependency is missing and will error the compilation saying there is a missing dependency.
092   */
093  Class<?>[] requires() default {};
094
095  /**
096   * Explicitly define beans provided by this module and required by other modules.
097   *
098   * @see #provides()
099   */
100  String[] providesString() default {};
101
102  /**
103   * Required external beans for wiring this module.
104   *
105   * @see #requires()
106   */
107  String[] requiresString() default {};
108
109  /**
110   * Dependencies in these packages are expected to be provided by other modules.
111   * <p>
112   * Instead of listing each and every dependency in {@code requires} we can use this to specify
113   * that any required dependency that is in these packages is expected to be provided by another module.
114   * <p>
115   * Use this rather than {@code requires} when there are lots of required dependencies, and we don't
116   * want to list each one in {@code requires} and {@code provides}.
117   */
118  Class<?>[] requiresPackages() default {};
119
120  /**
121   * Internal use only - identifies the custom scope annotation associated to this module.
122   * <p>
123   * When a module is generated for a custom scope this is set to link the module back to the
124   * custom scope annotation and support partial compilation.
125   */
126  String customScopeType() default "";
127
128}