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 generates a fragment from a list of contributors.
012 * The use of this annotation comes with significant constraints. The contributors are
013 * identified as types annotated by {@link ContributeTo} where the {@link ContributeTo#value()}
014 * parameter is exactly the as the {@link AutoFragment#value()} parameter.
015 *
016 * <p>The following constraints exist:</p>
017 *
018 * <ul>
019 * <li>
020 *   The {@link AutoFragment} annotated type and the {@link ContributeTo} annotated types must be
021 *   compiled using in a single javac invocation. If the linked AutoFragment and ContributedTo
022 *   are compiled using different javac invocations then they will not find each other and will generate
023 *   an error.
024 * </li>
025 * <li>
026 *   If there are multiple {@link AutoFragment} annotated types that specify the same value for the
027 *   {@link AutoFragment#value()} parameter and they are compiled using a single javac invocation then
028 *   the annotation processor will generate an error.
029 * </li>
030 * <li>
031 *   If the {@link ContributeTo} annotated type is generated by an annotation
032 *   processor then it MUST NOT be generated in a round after the {@link AutoFragment} has generated
033 *   the fragment. The annotation processor will generate the fragment for the {@link AutoFragment} type
034 *   after a round where there is at least 1 contributor and no contributors have been added in the current
035 *   round.
036 * </li>
037 * </ul>
038 */
039@Documented
040@Retention( RetentionPolicy.RUNTIME )
041@Target( ElementType.TYPE )
042@StingProvider( "[FlatEnclosingName]Sting_[SimpleName]_Fragment" )
043public @interface AutoFragment
044{
045  /**
046   * An opaque string that identifies auto-fragment.
047   *
048   * @return the auto-fragment key.
049   */
050  @Nonnull
051  String value();
052}