001package sting;
002
003import java.lang.annotation.Documented;
004import java.lang.annotation.ElementType;
005import java.lang.annotation.Retention;
006import java.lang.annotation.RetentionPolicy;
007import java.lang.annotation.Target;
008import javax.annotation.Nonnull;
009
010/**
011 * Identify an interface that can contribute to a component graph.
012 * This annotation is a top-level Sting processor entrypoint.
013 *
014 * <p>The interface is expected to declare 1 or more default methods and/or include 1 or more types
015 * in the {@link #includes() includes} parameter. Sting actively processes {@link Named},
016 * {@link Typed}, and {@link Eager} on provider methods declared by the fragment, and {@link Named}
017 * on provider method parameters. When {@link Typed} is present on a provider method, it defines the
018 * full set of service types published by that binding.</p>
019 */
020@Documented
021@Retention( RetentionPolicy.RUNTIME )
022@Target( ElementType.TYPE )
023public @interface Fragment
024{
025  /**
026   * A list of types that can contribute to the component graph.
027   * The types can be {@link Injectable}-annotated classes or {@link Fragment}-annotated interfaces.
028   * The {@link Fragment}-annotated interfaces contributions are added recursively and contributions are
029   * de-duplicated before they are resolved.
030   *
031   * @return a list of types that contribute to the fragments component graph.
032   */
033  @Nonnull
034  Class<?>[] includes() default {};
035
036  /**
037   * True if all explicitly included types must be declared in the same package as the fragment.
038   *
039   * @return true to reject cross-package includes, false to permit them.
040   */
041  boolean localOnly() default true;
042}