001package arez.annotations;
002
003import java.lang.annotation.Documented;
004import java.lang.annotation.ElementType;
005import java.lang.annotation.Target;
006import javax.annotation.Nonnull;
007
008/**
009 * This annotation designates the method used to retrieve the id of the reference. It can be placed
010 * on the getter of an {@link Observable} property or on a normal getter method if the id is never
011 * expected to change. See the {@link Reference} docs for how the method is used.
012 *
013 * <p>The method must also conform to the following constraints:</p>
014 * <ul>
015 * <li>Must not be annotated with any arez annotations other than @Observable</li>
016 * <li>Must have 0 parameters</li>
017 * <li>Must return a value</li>
018 * <li>Must not be private</li>
019 * <li>Must not be static</li>
020 * <li>Must not throw exceptions</li>
021 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
022 * </ul>
023 *
024 * <p>This annotation is only supported on elements contained within a type annotated by
025 * {@link ArezComponent} or {@link ArezComponentLike}. Other usages will fail compilation.</p>
026 */
027@Documented
028@Target( ElementType.METHOD )
029public @interface ReferenceId
030{
031  /**
032   * Return the name of the reference relative to the component. The value must conform
033   * to the requirements of a java identifier. If not specified, the name will be derived by assuming
034   * the naming convention "get[Name]Id" or "[name]Id" otherwise a compile failure will generated.
035   *
036   * @return the name of the reference relative to the component.
037   */
038  @Nonnull
039  String name() default "<default>";
040}