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}