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 before a view is updated or re-rendered.
009 * There must only be one method annotated with this annotation in a view.
010 * This method is invoked in the "commit" phase using reacts <code>getSnapshotBeforeUpdate()</code>
011 * lifecycle method.
012 *
013 * <p>This method is used to get access to the DOM prior to it being updated. This is useful if there is
014 * state stored on the DOM that is not present in the VirtualDOM. The method annotated with {@link PreUpdate}
015 * can query the DOM and then apply the necessary changes in {@link PostMountOrUpdate}. Scroll position is an example
016 * of data stored on the DOM but not present in the VirtualDOM and implementing auto-scrolling to new content
017 * would require use of this lifecycle method to calculate the new offset.</p>
018 *
019 * <p>The method must also conform to the following constraints:</p>
020 * <ul>
021 * <li>Must not be annotated with any other react4j annotation</li>
022 * <li>Must have 0 parameters</li>
023 * <li>Must not return a value</li>
024 * <li>Must not be private</li>
025 * <li>Must not be public</li>
026 * <li>Must not be static</li>
027 * <li>Must not be abstract</li>
028 * <li>Must not throw exceptions</li>
029 * <li>Must be accessible from the same package as the class annotated by {@link View}</li>
030 * <li>
031 *   Should not be public as not expected to be invoked outside the view. A warning will be generated but can
032 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressReact4jWarnings} annotations with a key
033 *   "React4j:PublicMethod". This warning is also suppressed by the annotation processor if it is implementing
034 *   an interface method.
035 * </li>
036 * <li>
037 *   Should not be protected if in the class annotated with the {@link View} annotation as the method is not
038 *   expected to be invoked outside the view. A warning will be generated but can be suppressed by the
039 *   {@link SuppressWarnings} or {@link SuppressReact4jWarnings} annotations with a key "React4j:ProtectedMethod".
040 * </li>
041 * </ul>
042 */
043@Documented
044@Target( ElementType.METHOD )
045public @interface PreUpdate
046{
047}