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 * Annotation that indicates the class that provides the service.
012 * The class that provides the service may be either a {@link Fragment} annotated type or an {@link Injectable}
013 * annotated type. This annotation is applied to another frameworks annotation to simplify integration with Sting.
014 * Sting will process this annotation when the framework annotation is applied to a type element and that Sting
015 * attempts to include that type. Sting can attempt to include the type either by the type being added to an
016 * {@link Injector#includes()} annotation parameter, a {@link Fragment#includes()} annotation parameter, or by
017 * being an unresolved service referenced in component graph that sting attempts to autodetect.
018 *
019 * <p>It should be noted that Sting will attempt to use any annotation with this name and shape so that
020 * frameworks do not need a direct code dependency on Sting. </p>
021 */
022@Documented
023@Retention( RetentionPolicy.RUNTIME )
024@Target( ElementType.ANNOTATION_TYPE )
025public @interface StingProvider
026{
027  /**
028   * The name pattern of the class that provides the service.
029   * The name is relative to the reference type (See above for how to determine the reference type).
030   * The package is the same package as the reference type. The pattern can include constant string
031   * parts as well as the following replacements:
032   *
033   * <ul>
034   *   <li>
035   *     <b>[SimpleName]</b>: The simple name of the class. i.e. For a top-level class like
036   *     {@code come.example.MyElement} the simple name is {@code "MyElement"}. For a nested class like
037   *     {@code come.example.MyElement.ElementType.Kind} the simple name is {@code "Kind"}.
038   *   </li>
039   *   <li>
040   *     <b>[CompoundName]</b>: The compound name of the class. i.e. For a top-level class like
041   *     {@code come.example.MyElement} the compound name is {@code "MyElement"}. For a nested class like
042   *     {@code come.example.MyElement.ElementType.Kind} the simple name is {@code "MyElement.ElementType.Kind"}.
043   *   </li>
044   *   <li>
045   *     <b>[EnclosingName]</b>: The compound name of the class with the simple name elided. i.e. For a top-level
046   *     class like {@code come.example.MyElement} the enclosing name is {@code ""}. For a nested class like
047   *     {@code come.example.MyElement.ElementType.Kind} the enclosing name is {@code "MyElement.ElementType."}.
048   *   </li>
049   *   <li>
050   *     <b>[FlatEnclosingName]</b>: The enclosing name of the class with the dots replaced with underscores.
051   *     i.e. For a top-level class like {@code come.example.MyElement} the flat enclosing name is {@code ""}.
052   *     For a nested class like {@code come.example.MyElement.ElementType.Kind} the flat enclosing name is
053   *     {@code "MyElement_ElementType_"}.
054   *   </li>
055   * </ul>
056   *
057   * <p>A typical pattern used by a framework such as <a href="https://arez.github.io/">Arez</a> is
058   * "[FlatEnclosingName]Arez_[SimpleName]"..</p>
059   *
060   * @return the pattern to produce a name.
061   */
062  @Nonnull
063  String value();
064}