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 * Annotate the method that will be overridden to return true if the component is in the specified state.
010 * This is useful when the component must validate methods are only called in certain states or to change
011 * behaviour based on state (i.e. Avoid causing side-effects when disposing).
012 *
013 * <p>The method that is annotated with this component must comply with the constraints:</p>
014 * <ul>
015 * <li>May appear zero or more times on a component</li>
016 * <li>Must not be annotated with any other arez annotation</li>
017 * <li>Must have 0 parameters</li>
018 * <li>Must return a boolean</li>
019 * <li>Must be abstract</li>
020 * <li>Must not throw exceptions</li>
021 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
022 * <li>
023 *   Should not be public as not expected to be invoked outside the component. A warning will be generated but can
024 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key
025 *   "Arez:PublicRefMethod". This warning is also suppressed by the annotation processor if it is implementing
026 *   an interface method.
027 * </li>
028 * <li>
029 *   Should not be protected if in the class annotated with the {@link ArezComponent} annotation as the method is not
030 *   expected to be invoked outside the component. A warning will be generated but can be suppressed by the
031 *   {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key "Arez:ProtectedMethod".
032 * </li>
033 * </ul>
034 *
035 * <p>This annotation is only supported on elements contained within a type annotated by
036 * {@link ArezComponent} or {@link ArezComponentLike}. Other usages will fail compilation.</p>
037 */
038@Documented
039@Target( ElementType.METHOD )
040public @interface ComponentStateRef
041{
042  /**
043   * Return the component state which will cause the annotated method to return true.
044   *
045   * @return the component state which will cause annotated method to return true.
046   */
047  @Nonnull
048  State value() default State.READY;
049}