001package arez.annotations;
002
003import arez.ComputableValue;
004import arez.EqualityComparator;
005import arez.ObjectsEqualsComparator;
006import java.lang.annotation.Documented;
007import java.lang.annotation.ElementType;
008import java.lang.annotation.Target;
009import javax.annotation.Nonnull;
010
011/**
012 * Methods marked with this annotation are <a href="https://en.wikipedia.org/wiki/Memoization">memoized</a> while
013 * activated which typically means they have an observer. These methods are typically backed with one or more
014 * {@link ComputableValue} instances.
015 *
016 * <p>The return value should be derived from the method parameters and any other {@link Observable} properties
017 * or {@link Memoize} properties accessed within the scope of the method. The he value returned by the method
018 * should not change unless the state of the {@link Observable} properties or {@link Memoize} properties change.
019 * If the return value can change outside of the above scenarios it is important to set the {@link #depType()}
020 * to {@link DepType#AREZ_OR_EXTERNAL} and explicitly report possible changes to the derived value by invoking
021 * the {@link ComputableValue#reportPossiblyChanged()} on the {@link ComputableValue} returned from a method
022 * annotated by the {@link ComputableValueRef} that is linked to the method marked with this annotation.</p>
023 *
024 * <p>The method is wrapped in a READ_ONLY transaction and thus can not modify other state in the system.</p>
025 *
026 * <p>The enhanced method is implemented by creating a separate {@link ComputableValue} instance for each unique
027 * combination of parameters that are passed to the method. When the {@link ComputableValue} is deactivated, a hook
028 * triggers that removes the {@link ComputableValue} from the local cache. If the method has zero parameter then
029 * the method is backed by a single {@link ComputableValue} instance.</p>
030 *
031 * <p>The method that is annotated with this annotation must comply with the additional constraints:</p>
032 * <ul>
033 * <li>Must not be annotated with any other arez annotation</li>
034 * <li>Must return a value</li>
035 * <li>Must not be private</li>
036 * <li>Must not be static</li>
037 * <li>Must not be final</li>
038 * <li>Must not be abstract</li>
039 * <li>Must not throw exceptions</li>
040 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
041 * </ul>
042 */
043@Documented
044@Target( ElementType.METHOD )
045public @interface Memoize
046{
047  /**
048   * Return the root name of the element value relative to the component.
049   * If the method has parameters then the name will be used in combination with a sequence
050   * when naming the synthesized {@link ComputableValue} instances. The value must conform to
051   * the requirements of a java identifier. The name must also be unique across {@link Observable}s,
052   * {@code Memoize}s and {@link Action}s within the scope of the {@link ArezComponent} annotated element.
053   *
054   * @return the root name of the element relative to the component.
055   */
056  @Nonnull
057  String name() default "<default>";
058
059  /**
060   * A flag indicating whether the computable should be "kept alive". A computable that is kept alive
061   * is activated on creation and never deactivates. This is useful if the computable property is only
062   * accessed from within actions but should be kept up to date and not recomputed on each access.
063   * This MUST not be set if the target method has any parameters as can not keep computed value active
064   * if parameter values are unknown.
065   *
066   * @return true to keep computable alive.
067   */
068  boolean keepAlive() default false;
069
070  /**
071   * The priority of the underlying ComputableValue observer.
072   *
073   * @return the priority of the ComputableValue observer.
074   */
075  Priority priority() default Priority.DEFAULT;
076
077  /**
078   * Flag controlling whether the underlying observer can observe ComputableValue instances with lower priorities.
079   * The default value of false will result in an invariant failure (in development mode) if a lower priority
080   * dependency is observed by the observer. This is to prevent priority inversion when scheduling a higher
081   * priority observer is dependent upon a lower priority computable value. If the value is true then the no
082   * invariant failure is triggered and the component relies on the component author to handle possible priority
083   * inversion.
084   *
085   * @return false if observing lower priority dependencies should result in invariant failure in development mode.
086   */
087  boolean observeLowerPriorityDependencies() default false;
088
089  /**
090   * Enum indicating whether the value of the computable is derived from arez elements and/or external dependencies.
091   * If set to {@link DepType#AREZ} then Arez will verify that the method annotated by this annotation accesses arez
092   * elements (i.e. instances of {@link arez.ObservableValue} or instances of {@link ComputableValue}). If set to
093   * {@link DepType#AREZ_OR_NONE} then the runtime will allow computable to exist with no dependencies. If set
094   * to {@link DepType#AREZ_OR_EXTERNAL} then the component must define a {@link ComputableValueRef} method and should invoke
095   * {@link ComputableValue#reportPossiblyChanged()} when the non-arez dependencies are changed.
096   *
097   * @return the types of dependencies allowed on the computable.
098   */
099  @Nonnull
100  DepType depType() default DepType.AREZ;
101
102  /**
103   * Return true if the return value of the memoized value should be reported to the Arez spy subsystem.
104   * It is useful to disable reporting for large, circular or just uninteresting parameters to the spy infrastructure.
105   *
106   * @return true to report the return value, false otherwise.
107   */
108  boolean reportResult() default true;
109
110  /**
111   * Indicate whether the memoized value can be read outside a transaction.
112   * If the value is {@link Feature#AUTODETECT} then the value will be derived from the
113   * {@link ArezComponent#defaultReadOutsideTransaction()} parameter on the {@link ArezComponent} annotation. If
114   * the value is set to {@link Feature#ENABLE} then the memoized value can be read outside a transaction. It should
115   * be noted that in this scenario the memoized value will be recalculated each time it is accessed.
116   *
117   * @return flag that determines whether the memoized value allows reads outside a transaction, false to require a transaction to read the memoized value.
118   */
119  Feature readOutsideTransaction() default Feature.AUTODETECT;
120
121  /**
122   * Return the strategy used to compare computed values when deciding whether to
123   * propagate a change.
124   *
125   * @return the comparator type used when checking whether values are equal.
126   */
127  @Nonnull
128  Class<? extends EqualityComparator> equalityComparator() default ObjectsEqualsComparator.class;
129}