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