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 * The Inverse annotation is used to annotate the reverse direction of the relationship annotated
010 * by the {@link Reference} annotation. The <code>Inverse</code> annotation MUST be paired with a
011 * reference. The method annotated with this annotation must return a class annotated with
012 * the {@link ArezComponent} annotation or a {@link java.util.Collection}, a {@link java.util.List} or a
013 * {@link java.util.Set} where the type parameter refers to a class annotated with the
014 * {@link ArezComponent} annotation. If the method returns a non-collection type then the type
015 * must also be annotated with either {@link javax.annotation.Nonnull} or {@link javax.annotation.Nullable}.
016 *
017 * <p>The method must also conform to the following constraints:</p>
018 * <ul>
019 * <li>Must not be annotated with any other arez annotation</li>
020 * <li>Must have 0 parameters</li>
021 * <li>Must return a value.</li>
022 * <li>Must be abstract</li>
023 * <li>Must not throw exceptions</li>
024 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
025 * </ul>
026 */
027@Documented
028@Target( ElementType.METHOD )
029public @interface Inverse
030{
031  /**
032   * Return the name of the inverse relative to the component. The value must conform
033   * to the requirements of a java identifier. If not specified, the name will be derived by assuming
034   * the naming convention "get[Name]" or failing that the name will be the method name.
035   *
036   * @return the name of the inverse relative to the component.
037   */
038  @Nonnull
039  String name() default "<default>";
040
041  /**
042   * Return the name of the reference that the inverse is associated with. The value must conform
043   * to the requirements of a java identifier. If not specified, the name will be derived by assuming
044   * that the reference name is the camelCase name of the class on which the {@link Inverse} annotation
045   * appears unless the {@link Inverse} appears on an interface in which case it is the class annotated
046   * with {@link ArezComponent}.
047   *
048   * @return the name of the reference relative to the component.
049   */
050  @Nonnull
051  String referenceName() default "<default>";
052}