001package arez.annotations; 002 003import arez.ObservableValue; 004import java.lang.annotation.Documented; 005import java.lang.annotation.ElementType; 006import java.lang.annotation.Target; 007import javax.annotation.Nonnull; 008 009/** 010 * Marks a template method that returns the {@link ObservableValue} instance for 011 * the {@link Observable} annotated property. Each property marked with the {@link Observable} annotation is backed 012 * by an {@link ObservableValue} instance and some frameworks make use of this value to implement 013 * advanced functionality. 014 * 015 * <p>The method that is annotated with this annotation must also comply with the following constraints:</p> 016 * <ul> 017 * <li>Must not be annotated with any other arez annotation</li> 018 * <li>Must be abstract</li> 019 * <li>Must not throw any exceptions</li> 020 * <li>Must be accessible to the class annotated by the {@link ArezComponent} annotation.</li> 021 * <li> 022 * Must return an instance of {@link ObservableValue} and the type parameter must be the 023 * wildcard {@code ?} or the type of the corresponding {@link Observable} method. The value 024 * may also be "raw" (i.e. without a type parameter). 025 * </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:PublicRefMethod". 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 ObservableValueRef 042{ 043 /** 044 * Return the name of the associated ObservableValue property that this ref relates to. 045 * This value will be derived if the method name matches the pattern "get[Name]ObservableValue", 046 * otherwise it must be specified. 047 * 048 * @return the name of the associated ObservableValue. 049 */ 050 @Nonnull 051 String name() default "<default>"; 052}