001package react4j.annotations;
002
003import java.lang.annotation.Documented;
004import java.lang.annotation.ElementType;
005import java.lang.annotation.Target;
006
007/**
008 * Identifies a method that is called when the value of one of the specified inputs is changed.
009 * Each parameter of the method is mapped to a input that is tracked. The method will be called
010 * before or after the update has occurred and will be passed the previous values of the inputs
011 * as parameters.
012 *
013 * <p>Each parameter is expected to be named according to the pattern "last[MyInput]", "prev[MyInput]"
014 * or "[myInput]". If name of the parameter does not follow the pattern then the name can be explicitly
015 * mapped via the {@link InputRef} annotation on a parameter.</p>
016 *
017 * <p>The method must also conform to the following constraints:</p>
018 * <ul>
019 * <li>Must not be annotated with any other react4j annotation</li>
020 * <li>Must have 1 or more parameters. Each parameter must map to a input as described above.</li>
021 * <li>Must not return a value</li>
022 * <li>Must not be private</li>
023 * <li>Must not be public</li>
024 * <li>Must not be static</li>
025 * <li>Must not be abstract</li>
026 * <li>Must not throw exceptions</li>
027 * <li>Must be accessible from the same package as the class annotated by {@link View}</li>
028 * <li>
029 *   Should not be public as not expected to be invoked outside the view. A warning will be generated but can
030 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressReact4jWarnings} annotations with a key
031 *   "React4j:PublicMethod". This warning is also suppressed by the annotation processor if it is implementing
032 *   an interface method.
033 * </li>
034 * <li>
035 *   Should not be protected if in the class annotated with the {@link View} annotation as the method is not
036 *   expected to be invoked outside the view. A warning will be generated but can be suppressed by the
037 *   {@link SuppressWarnings} or {@link SuppressReact4jWarnings} annotations with a key "React4j:ProtectedMethod".
038 * </li>
039 * </ul>
040 */
041@Documented
042@Target( ElementType.METHOD )
043public @interface OnInputChange
044{
045  /**
046   * Phase in which method should be invoked.
047   */
048  enum Phase
049  {
050    /**
051     * Method should be invoked before update.
052     */
053    PRE,
054    /**
055     * Method should be invoked after update.
056     */
057    POST
058  }
059
060  /**
061   * The phase in which the method should be invoked.
062   *
063   * @return the phase in which the method should be invoked.
064   */
065  Phase phase() default Phase.PRE;
066}