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}