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 will be invoked when the dependencies of the paired {@link Observe} annotated method are changed.
010 *
011 * <p>The method 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 abstract</li>
017 * <li>Must have either no parameters or a single parameter of type {@link arez.Observer}</li>
018 * <li>Must not return a value</li>
019 * <li>Must not throw an exception</li>
020 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
021 * <li>
022 *   Should not be public as not expected to be invoked outside the component. A warning will be generated but can
023 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key
024 *   "Arez:PublicHookMethod". This warning is also suppressed by the annotation processor if it is implementing
025 *   an interface method.
026 * </li>
027 * <li>
028 *   Should not be protected if in the class annotated with the {@link ArezComponent} annotation as the method is not
029 *   expected to be invoked outside the component. A warning will be generated but can be suppressed by the
030 *   {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key "Arez:ProtectedMethod".
031 * </li>
032 * </ul>
033 *
034 * <p>If the annotated method has a parameter of type {@link arez.Observer} then the underlying {@link arez.Observer}
035 * instance associated with the {@link Observe}/{@link OnDepsChange} annotated method is passed to the method when
036 * dependencies change. This is extremely useful when implementing asynchronous callbacks.</p>
037 *
038 * <p>This annotation is only supported on elements contained within a type annotated by
039 * {@link ArezComponent} or {@link ArezComponentLike}. Other usages will fail compilation.</p>
040 */
041@Documented
042@Target( ElementType.METHOD )
043public @interface OnDepsChange
044{
045  /**
046   * Return the name of the paired Tracked relative to the component.
047   * The value must conform to the requirements of a java identifier.
048   * The name need not be specified. If the {@link Observe} annotated method is
049   * named "render" then this will default to being named "onRenderDepsChange".
050   *
051   * @return the name of the paired {@link Observe} annotated method relative to the component.
052   */
053  @Nonnull
054  String name() default "<default>";
055}