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 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 * <p>This annotation is only supported on elements contained within a type annotated by
028 * {@link ArezComponent} or {@link ArezComponentLike}. Other usages will fail compilation.</p>
029 */
030@Documented
031@Target( ElementType.METHOD )
032public @interface Inverse
033{
034  /**
035   * Return the name of the inverse relative to the component. The value must conform
036   * to the requirements of a java identifier. If not specified, the name will be derived by assuming
037   * the naming convention "get[Name]" or failing that the name will be the method name.
038   *
039   * @return the name of the inverse relative to the component.
040   */
041  @Nonnull
042  String name() default "<default>";
043
044  /**
045   * Return the name of the reference that the inverse is associated with. The value must conform
046   * to the requirements of a java identifier. If not specified, the name will be derived by assuming
047   * that the reference name is the camelCase name of the class on which the {@code Inverse} annotation
048   * appears unless the {@code Inverse} appears on an interface in which case it is the class annotated
049   * with {@link ArezComponent}.
050   *
051   * @return the name of the reference relative to the component.
052   */
053  @Nonnull
054  String referenceName() default "<default>";
055}