001package arez.annotations;
002
003import java.lang.annotation.Documented;
004import java.lang.annotation.ElementType;
005import java.lang.annotation.Target;
006import javax.annotation.Nonnull;
007
008/**
009 * Methods marked with this annotation are invoked in an Arez transaction.
010 *
011 * <p>The method that is annotated with this annotation must comply with the additional constraints:</p>
012 * <ul>
013 * <li>Must not be annotated with any other arez annotation</li>
014 * <li>Must not be private</li>
015 * <li>Must not be static</li>
016 * <li>Must not be final</li>
017 * <li>Must not be abstract</li>
018 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
019 * </ul>
020 */
021@Documented
022@Target( ElementType.METHOD )
023public @interface Action
024{
025  /**
026   * Return the name of the Action relative to the component.
027   * The value must conform to the requirements of a java identifier.
028   * The name must also be unique across {@link Observable}s,
029   * {@link Memoize}s and {@link Action}s within the scope of the
030   * {@link ArezComponent} annotated element.
031   *
032   * @return the name of the Action relative to the component.
033   */
034  @Nonnull
035  String name() default "<default>";
036
037  /**
038   * Does the action mutate state or not.
039   *
040   * @return true if method should be wrapped in READ_WRITE transaction, false if it should it should be wrapped in READ_ONLY transaction.
041   */
042  boolean mutation() default true;
043
044  /**
045   * Return true if the parameters should be reported to the Arez spy subsystem.
046   * It is useful to disable reporting for large, circular or just uninteresting parameters to the spy infrastructure.
047   *
048   * @return true to report the parameters, false otherwise.
049   */
050  boolean reportParameters() default true;
051
052  /**
053   * Return true if the return value of the action (if any) should be reported to the Arez spy subsystem.
054   * It is useful to disable reporting for large, circular or just uninteresting parameters to the spy infrastructure.
055   *
056   * @return true to report the return value, false otherwise.
057   */
058  boolean reportResult() default true;
059
060  /**
061   * True if the action should always start a new transaction. A false value indicates that the action will
062   * use the invoking transaction if present, otherwise will create a new transaction to invoke action.
063   *
064   * @return true if the action will create a new transaction, false if it will use the existing transaction if present.
065   */
066  boolean requireNewTransaction() default false;
067
068  /**
069   * Flag indicating whether the code should verify that at least one read or write occurs within
070   * the scope of the action.
071   *
072   * @return true to verify action reads or writes observable data.
073   */
074  boolean verifyRequired() default true;
075}