001package arez.annotations; 002 003import arez.ObservableValue; 004import java.lang.annotation.Documented; 005import java.lang.annotation.ElementType; 006import java.lang.annotation.Target; 007import javax.annotation.Nonnull; 008 009/** 010 * Annotation applied to methods that expose an ObservableValue value in Arez. 011 * Methods annotated with this either query state or mutate state. The query 012 * method is expected to have 0 parameters and return a value and by default 013 * is named with "get" or "is" prefixed to the property name. The mutation 014 * method is expected to have a single parameter and return no value and by 015 * default is named with "set" prefixed to property name. The setter or getter 016 * can also be named matching the property name without the prefix. 017 * 018 * <p>Only one of the query or mutation method needs to be annotated with 019 * this annotation if the other method follows the normal conventions. If 020 * the other method does not conform to conventions, then you will need to 021 * annotate the pair and specify a value for {@link #name()}.</p> 022 * 023 * <p>The method should only invoked within the scope of a transaction. 024 * The mutation method requires that the transaction be READ_WRITE.</p> 025 * 026 * <p>The method that is annotated with this annotation must also comply with the following constraints:</p> 027 * <ul> 028 * <li>Must not be annotated with any other arez annotation</li> 029 * <li>Must not be private</li> 030 * <li>Must not be static</li> 031 * <li>Must not be final</li> 032 * <li>May be abstract but if abstract then the paired setter or getter must also be abstract</li> 033 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li> 034 * </ul> 035 */ 036@Documented 037@Target( ElementType.METHOD ) 038public @interface Observable 039{ 040 /** 041 * Return the name of the ObservableValue relative to the component. If not specified 042 * will default to the name of the property by convention as described above. 043 * The value must conform to the requirements of a java identifier. 044 * The name must also be unique across {@link Observable}s, 045 * {@link Memoize}s and {@link Action}s within the scope of the 046 * {@link ArezComponent} annotated element. 047 * 048 * @return the name of the ObservableValue relative to the component. 049 */ 050 @Nonnull 051 String name() default "<default>"; 052 053 /** 054 * Set this to false if there is no setter method and the component is 055 * expected to use {@link ObservableValueRef} to indicate when value has changed. 056 * 057 * @return true if there is expected to be a setter, false if there should be no setter. 058 */ 059 boolean expectSetter() default true; 060 061 /** 062 * Indicate whether the generated component class should add a parameter to the constructor to initialize this property. 063 * This parameter should only be set to {@link Feature#ENABLE} when the observable property is defined by a 064 * pair of abstract methods. If set to {@link Feature#AUTODETECT} then an initializer will be added for an 065 * observable property if it is defined by a pair of abstract methods and the values is annotated with the 066 * {@link javax.annotation.Nonnull} annotation and it is not annotated by {@link Inverse}. 067 * 068 * <p>The initializer parameters will be added as additional parameters at the end of the parameter list in 069 * the generated classes constructors. The initializers will be defined in the order that the observable 070 * properties are declared. They properties be assigned after the parent constructor has been invoked.</p> 071 * 072 * @return flag controlling whether a parameter should be added to the constructor to initialize the property. 073 */ 074 Feature initializer() default Feature.AUTODETECT; 075 076 /** 077 * Indicate whether the observable can be read outside a transaction. 078 * If the value is {@link Feature#AUTODETECT} then the value will be derived from the 079 * {@link ArezComponent#defaultReadOutsideTransaction()} parameter on the {@link ArezComponent} annotation. If 080 * the value is set to {@link Feature#ENABLE} then the observable can be read outside a transaction and the 081 * {@link ObservableValue#reportObserved()} will only be invoked if the observables is accessed from within 082 * a tracking transaction (i.e. when an {@link arez.Observer} or {@link arez.ComputableValue} creates the 083 * transaction). Thus, {@link Action} annotated methods that only access observables that set the 084 * readOutsideTransaction parameter to {@link Feature#ENABLE} and neither access nor modify other arez elements 085 * no longer need to be annotated with {@link Action} annotations. 086 * 087 * @return flag that determines whether the observable allows reads outside a transaction, false to require a transaction to read the observable. 088 */ 089 Feature readOutsideTransaction() default Feature.AUTODETECT; 090 091 /** 092 * Return true if the observable will create an action if the write occurs outside a transaction. 093 * 094 * @return true to allow writes to create an action if needed, false to require a transaction to write observable. 095 */ 096 Feature writeOutsideTransaction() default Feature.AUTODETECT; 097 098 /** 099 * Return false if the setter should verify observable value has changed before propagating change. 100 * In some scenarios, the setter method will modify the value before updating the observable or may 101 * decide to abort the update. This setting will force the generated code to check the value of the 102 * observable property after the setter and only invoke {@link ObservableValue#reportChanged()} if 103 * a change has actually occurred. 104 * 105 * <p>This parameter should not be set to false if the associated setter is abstract. It is also 106 * invalid to set this value to false if {@link #expectSetter()} is false.</p> 107 * 108 * @return false if the setter should verify observable value has changed before propagating change. 109 */ 110 boolean setterAlwaysMutates() default true; 111}