001package arez.annotations;
002
003import java.lang.annotation.Documented;
004import java.lang.annotation.ElementType;
005import java.lang.annotation.Target;
006
007/**
008 * Annotate the method that will be overridden to provide the "name" of the Arez component.
009 * This is useful when the user wants to manually create Arez elements (i.e. {@link arez.ObservableValue} instances,
010 * {@link arez.Observer} instances or {@link arez.ComputableValue} instances etc) and wants to use the same naming
011 * convention as the generated Arez subclass.
012 *
013 * <p>The method that is annotated with the annotation must comply with the additional constraints:</p>
014 * <ul>
015 * <li>Must not be annotated with any other arez annotation</li>
016 * <li>Must have 0 parameters</li>
017 * <li>Must return a String</li>
018 * <li>Must be abstract</li>
019 * <li>Must not throw exceptions</li>
020 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li>
021 * <li>
022 *   Should not be public as not expected to be invoked outside the component. A warning will be generated but can
023 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key
024 *   "Arez:PublicRefMethod". This warning is also suppressed by the annotation processor if it is implementing
025 *   an interface method.
026 * </li>
027 * <li>
028 *   Should not be protected if in the class annotated with the {@link ArezComponent} annotation as the method is not
029 *   expected to be invoked outside the component. A warning will be generated but can be suppressed by the
030 *   {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key "Arez:ProtectedMethod".
031 * </li>
032 * </ul>
033 *
034 * @see ComponentId
035 * @see ComponentTypeNameRef
036 */
037@Documented
038@Target( ElementType.METHOD )
039public @interface ComponentNameRef
040{
041}