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 * Marks a template method that returns the {@link arez.Observer} instance for
010 * the associated {@link Observe} annotated method.
011 *
012 * <p>The method that is annotated with this annotation must also comply with the following constraints:</p>
013 * <ul>
014 * <li>Must not be annotated with any other arez annotation</li>
015 * <li>Must be abstract</li>
016 * <li>Must not throw any exceptions</li>
017 * <li>Must return an instance of {@link arez.Observer}.</li>
018 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
019 * <li>
020 *   Should not be public as not expected to be invoked outside the component. A warning will be generated but can
021 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key
022 *   "Arez:PublicRefMethod". This warning is also suppressed by the annotation processor if it is implementing
023 *   an interface method.
024 * </li>
025 * <li>
026 *   Should not be protected if in the class annotated with the {@link ArezComponent} annotation as the method is not
027 *   expected to be invoked outside the component. A warning will be generated but can be suppressed by the
028 *   {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key "Arez:ProtectedMethod".
029 * </li>
030 * </ul>
031 *
032 * <p>This annotation is only supported on elements contained within a type annotated by
033 * {@link ArezComponent} or {@link ArezComponentLike}. Other usages will fail compilation.</p>
034 */
035@Documented
036@Target( ElementType.METHOD )
037public @interface ObserverRef
038{
039  /**
040   * Return the name of the associated Observer that this ref relates to.
041   * This value will be derived if the method name matches the pattern "get[Name]Observer",
042   * otherwise it must be specified.
043   *
044   * @return the name of the associated Observer.
045   */
046  @Nonnull
047  String name() default "<default>";
048}