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 * Identifies method that is called when the {@link arez.ComputableValue} changes to the INACTIVE state from
010 * any other state.
011 *
012 * <p>This method can only be associated with a {@link Memoize} annotated method that has 0 parameters.
013 * This limitation is in place to limit implementation complexity and because no use case for this
014 * functionality has been found.</p>
015 *
016 * <p>The method must also conform to the following constraints:</p>
017 * <ul>
018 * <li>Must not be annotated with any other arez annotation</li>
019 * <li>Must have 0 parameters</li>
020 * <li>Must not return a value</li>
021 * <li>Must not be private</li>
022 * <li>Must not be static</li>
023 * <li>Must not be abstract</li>
024 * <li>Must not throw exceptions</li>
025 * <li>Must not be for a {@link Memoize} method that has the {@link Memoize#keepAlive} parameter set to true</li>
026 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
027 * <li>
028 *   Should not be public as not expected to be invoked outside the component. A warning will be generated but can
029 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key
030 *   "Arez:PublicHookMethod". This warning is also suppressed by the annotation processor if it is implementing
031 *   an interface method.
032 * </li>
033 * <li>
034 *   Should not be protected if in the class annotated with the {@link ArezComponent} annotation as the method is not
035 *   expected to be invoked outside the component. A warning will be generated but can be suppressed by the
036 *   {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key "Arez:ProtectedMethod".
037 * </li>
038 * </ul>
039 *
040 * <p>This annotation is only supported on elements contained within a type annotated by
041 * {@link ArezComponent} or {@link ArezComponentLike}. Other usages will fail compilation.</p>
042 */
043@Documented
044@Target( ElementType.METHOD )
045public @interface OnDeactivate
046{
047  /**
048   * Return the name of the ComputableValue that this method is associated with.
049   * This value will be derived if the method name matches the pattern "on[Name]Deactivate",
050   * otherwise it must be specified.
051   *
052   * @return the name of the ComputableValue.
053   */
054  @Nonnull
055  String name() default "<default>";
056}