Package arez.annotations

Annotation Interface Memoize

@Documented @Target(METHOD) public @interface Memoize
Methods marked with this annotation are memoized while activated which typically means they have an observer. These methods are typically backed with one or more ComputableValue instances.

The return value should be derived from the method parameters and any other Observable properties or Memoize properties accessed within the scope of the method. The he value returned by the method should not change unless the state of the Observable properties or Memoize properties change. If the return value can change outside of the above scenarios it is important to set the depType() to DepType.AREZ_OR_EXTERNAL and explicitly report possible changes to the derived value by invoking the ComputableValue.reportPossiblyChanged() on the ComputableValue returned from a method annotated by the ComputableValueRef that is linked to the method marked with this annotation.

The method is wrapped in a READ_ONLY transaction and thus can not modify other state in the system.

The enhanced method is implemented by creating a separate ComputableValue instance for each unique combination of parameters that are passed to the method. When the ComputableValue is deactivated, a hook triggers that removes the ComputableValue from the local cache. If the method has zero parameter then the method is backed by a single ComputableValue instance.

The method that is annotated with this annotation must comply with the additional constraints:

  • Must not be annotated with any other arez annotation
  • Must return a value
  • Must not be private
  • Must not be static
  • Must not be final
  • Must not be abstract
  • Must not throw exceptions
  • Must be accessible to the class annotated by the ArezComponent annotation.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    DepType
    depType
    Enum indicating whether the value of the computable is derived from arez elements and/or external dependencies.
    boolean
    keepAlive
    A flag indicating whether the computable should be "kept alive".
    String
    name
    Return the root name of the element value relative to the component.
    boolean
    observeLowerPriorityDependencies
    Flag controlling whether the underlying observer can observe ComputableValue instances with lower priorities.
    Priority
    priority
    The priority of the underlying ComputableValue observer
    Feature
    readOutsideTransaction
    Indicate whether the memoized value can be read outside a transaction.
    boolean
    reportResult
    Return true if the return value of the memoized value should be reported to the Arez spy subsystem.

  • Element Details

    • name

      @Nonnull String name
      Return the root name of the element value relative to the component. If the method has parameters then the name will be used in combination with a sequence when naming the synthesized ComputableValue instances. The value must conform to the requirements of a java identifier. The name must also be unique across Observables, Memoizes and Actions within the scope of the ArezComponent annotated element.
      Returns:
      the root name of the element relative to the component.
      Default:
      "<default>"

    • keepAlive

      boolean keepAlive
      A flag indicating whether the computable should be "kept alive". A computable that is kept alive is activated on creation and never deactivates. This is useful if the computable property is only accessed from within actions but should be kept up to date and not recomputed on each access. This MUST not be set if the target method has any parameters as can not keep computed value active if parameter values are unknown.
      Returns:
      true to keep computable alive.
      Default:
      false

    • priority

      Priority priority
      The priority of the underlying ComputableValue observer
      Returns:
      the priority of the ComputableValue observer.
      Default:
      DEFAULT

    • observeLowerPriorityDependencies

      boolean observeLowerPriorityDependencies
      Flag controlling whether the underlying observer can observe ComputableValue instances with lower priorities. The default value of false will result in an invariant failure (in development mode) if a lower priority dependency is observed by the observer. This is to prevent priority inversion when scheduling a higher priority observer is dependent upon a lower priority computable value. If the value is true then the no invariant failure is triggered and the component relies on the component author to handle possible priority inversion.
      Returns:
      false if observing lower priority dependencies should result in invariant failure in development mode.
      Default:
      false

    • depType

      @Nonnull DepType depType
      Enum indicating whether the value of the computable is derived from arez elements and/or external dependencies. If set to DepType.AREZ then Arez will verify that the method annotated by this annotation accesses arez elements (i.e. instances of ObservableValue or instances of ComputableValue). If set to DepType.AREZ_OR_NONE then the runtime will allow computable to exist with no dependencies. If set to DepType.AREZ_OR_EXTERNAL then the component must define a ComputableValueRef method and should invoke ComputableValue.reportPossiblyChanged() when the non-arez dependencies are changed.
      Returns:
      the types of dependencies allowed on the computable.
      Default:
      AREZ

    • reportResult

      boolean reportResult
      Return true if the return value of the memoized value should be reported to the Arez spy subsystem. It is useful to disable reporting for large, circular or just uninteresting parameters to the spy infrastructure.
      Returns:
      true to report the return value, false otherwise.
      Default:
      true

    • readOutsideTransaction

      Feature readOutsideTransaction
      Indicate whether the memoized value can be read outside a transaction. If the value is Feature.AUTODETECT then the value will be derived from the ArezComponent.defaultReadOutsideTransaction() parameter on the ArezComponent annotation. If the value is set to Feature.ENABLE then the memoized value can be read outside a transaction. It should be noted that in this scenario the memoized value will be recalculated each time it is accessed.
      Returns:
      flag that determines whether the memoized value allows reads outside a transaction, false to require a transaction to read the memoized value.
      Default:
      AUTODETECT