001package arez.annotations;
002
003import arez.ComputableValue;
004import java.lang.annotation.Documented;
005import java.lang.annotation.ElementType;
006import java.lang.annotation.Target;
007import javax.annotation.Nonnull;
008
009/**
010 * Marks a template method that returns the {@link ComputableValue} instance for
011 * the {@link Memoize} annotated property. Each property marked with the {@link Memoize} annotation is backed
012 * by an {@link ComputableValue} instance and some frameworks make use of this value to implement
013 * advanced functionality.
014 *
015 * <p>The method that is annotated with this annotation must also comply with the following constraints:</p>
016 * <ul>
017 * <li>Must have the exact same parameter types as the associated {@link Memoize} annotated method</li>
018 * <li>Must not be annotated with any other arez annotation</li>
019 * <li>Must be abstract</li>
020 * <li>Must not throw any exceptions</li>
021 * <li>Must return an instance of {@link ComputableValue}.</li>
022 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
023 * <li>
024 *   Should not be public as not expected to be invoked outside the component. A warning will be generated but can
025 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key
026 *   "Arez:PublicRefMethod". This warning is also suppressed by the annotation processor if it is implementing
027 *   an interface method.
028 * </li>
029 * <li>
030 *   Should not be protected if in the class annotated with the {@link ArezComponent} annotation as the method is not
031 *   expected to be invoked outside the component. A warning will be generated but can be suppressed by the
032 *   {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key "Arez:ProtectedMethod".
033 * </li>
034 * </ul>
035 *
036 * <p>This annotation is only supported on elements contained within a type annotated by
037 * {@link ArezComponent} or {@link ArezComponentLike}. Other usages will fail compilation.</p>
038 */
039@Documented
040@Target( ElementType.METHOD )
041public @interface ComputableValueRef
042{
043  /**
044   * Return the name of the associated Memoize property that this ref relates to.
045   * This value will be derived if the method name matches the pattern "get[Name]ComputableValue",
046   * otherwise it must be specified.
047   *
048   * @return the name of the associated ComputableValue.
049   */
050  @Nonnull
051  String name() default "<default>";
052}