arez.annotations.ObservableValueRef Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of arez-core Show documentation

Arez Core

There is a newer version: 0.213

package arez.annotations;

import arez.ObservableValue;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
import javax.annotation.Nonnull;

/**
 * Marks a template method that returns the {@link ObservableValue} instance for
 * the {@link Observable} annotated property. Each property marked with the {@link Observable} annotation is backed
 * by an {@link ObservableValue} instance and some frameworks make use of this value to implement
 * advanced functionality.
 *
 * The method that is annotated with this annotation must also comply with the following constraints:
 * 
 * Must not be annotated with any other arez annotation
 * Must be abstract
 * Must not throw any exceptions
 * Must be accessible to the class annotated by the {@link ArezComponent} annotation.
 * 
 *   Must return an instance of {@link ObservableValue} and the type parameter must be the
 *   wildcard {@code ?} or the type of the corresponding {@link Observable} method. The value
 *   may also be "raw" (i.e. without a type parameter).
 * 
 * 
 *   Should not be public as not expected to be invoked outside the component. A warning will be generated but can
 *   be suppressed by the {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key
 *   "Arez:PublicRefMethod". This warning is also suppressed by the annotation processor if it is implementing
 *   an interface method.
 * 
 * 
 *   Should not be protected if in the class annotated with the {@link ArezComponent} annotation as the method is not
 *   expected to be invoked outside the component. A warning will be generated but can be suppressed by the
 *   {@link SuppressWarnings} or {@link SuppressArezWarnings} annotations with a key "Arez:ProtectedMethod".
 * 
 * 
 */
@Documented
@Target( ElementType.METHOD )
public @interface ObservableValueRef
{
  /**
   * Return the name of the associated ObservableValue property that this ref relates to.
   * This value will be derived if the method name matches the pattern "get[Name]ObservableValue",
   * otherwise it must be specified.
   *
   * @return the name of the associated ObservableValue.
   */
  @Nonnull
  String name() default "";
}