001package arez.annotations;
002
003import java.lang.annotation.Documented;
004import java.lang.annotation.ElementType;
005import java.lang.annotation.Target;
006
007/**
008 * Marks a template method that returns the {@link arez.Component} instance for the component.
009 *
010 * <p>The method that is annotated with this annotation must also comply with the following constraints:</p>
011 * <ul>
012 * <li>Must not be annotated with any other arez annotation</li>
013 * <li>Must be abstract</li>
014 * <li>Must not throw any exceptions</li>
015 * <li>Must return an instance of {@link arez.Component}.</li>
016 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
017 * <li>
018 *   Should not be public as not expected to be invoked outside the component. A warning will be generated but can
019 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key
020 *   "Arez:PublicRefMethod". This warning is also suppressed by the annotation processor if it is implementing
021 *   an interface method.
022 * </li>
023 * <li>
024 *   Should not be protected if in the class annotated with the {@link ArezComponent} annotation as the method is not
025 *   expected to be invoked outside the component. A warning will be generated but can be suppressed by the
026 *   {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key "Arez:ProtectedMethod".
027 * </li>
028 * </ul>
029 */
030@Documented
031@Target( ElementType.METHOD )
032public @interface ComponentRef
033{
034}