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 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 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@Documented 039@Target( ElementType.METHOD ) 040public @interface OnDepsChange 041{ 042 /** 043 * Return the name of the paired Tracked relative to the component. 044 * The value must conform to the requirements of a java identifier. 045 * The name need not be specified. If the {@link Observe} annotated method is 046 * named "render" then this will default to being named "onRenderDepsChange". 047 * 048 * @return the name of the paired {@link Observe} annotated method relative to the component. 049 */ 050 @Nonnull 051 String name() default "<default>"; 052}