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 a method that will be invoked after an inverse reference is added to a component.
010 * This method MUST be paired with a method annotated with {@link Inverse} with the same name.
011 *
012 * <p>If there are multiple methods annotated with this annotation then the methods declared in parent
013 * classes will be invoked first and multiple methods within a single class will be invoked in declaration
014 * order.</p>
015 *
016 * <p>The method that is annotated with this annotation must comply with the additional constraints:</p>
017 * <ul>
018 * <li>Must not be annotated with any other arez annotation</li>
019 * <li>Must not be private</li>
020 * <li>Must not be static</li>
021 * <li>Must not be abstract</li>
022 * <li>Must have have a single parameter of type that matches the related reference value</li>
023 * <li>Must not return a value</li>
024 * <li>Must not throw an exception</li>
025 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
026 * <li>
027 *   Should not be public as not expected to be invoked outside the component. A warning will be generated but can
028 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key
029 *   "Arez:PublicHookMethod". This warning is also suppressed by the annotation processor if it is implementing
030 *   an interface method.
031 * </li>
032 * <li>
033 *   Should not be protected if in the class annotated with the {@link ArezComponent} annotation as the method is not
034 *   expected to be invoked outside the component. A warning will be generated but can be suppressed by the
035 *   {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key "Arez:ProtectedMethod".
036 * </li>
037 * </ul>
038 */
039@Documented
040@Target( ElementType.METHOD )
041public @interface PostInverseAdd
042{
043  /**
044   * Return the name of the Inverse that this method is associated with.
045   * This value will be derived if the method name matches the pattern "on[Name]Remove",
046   * otherwise it must be specified.
047   *
048   * @return the name of the Inverse.
049   */
050  @Nonnull
051  String name() default "<default>";
052}