Package arez.annotations

Annotation Interface Observe

@Documented @Target(METHOD) public @interface Observe
Annotation that marks a method as observed. Any ObservableValue instances or ComputableValue instances accessed within the scope of the method will be added as a dependency of the observer. If any of these dependencies are changed then the runtime will invoke the associated OnDepsChange method if present or re-schedule the observed method for execution if there is no OnDepsChange method present. Note that Arez will attempt to detect the OnDepsChange method using naming conventions even if there is no method explicitly annotated.

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

  • Must not be annotated with any other arez annotation
  • Must not be private
  • Must not be static
  • Must not be final
  • Must not be abstract

If the executor() is set to Executor.INTERNAL then the method must also comply with the following additional constraints:

  • Must not be public
  • Must have 0 parameters
  • Must not return a value
  • 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 Observer is derived from arez elements and/or external dependencies.
    Executor
    executor
    The actor responsible for calling the observed method.
    boolean
    mutation
    Does the observer's tracking method change arez state or not.
    String
    name
    Return the name of the Observer relative to the component.
    boolean
    nestedActionsAllowed
    Can the observer invoke actions.
    boolean
    observeLowerPriorityDependencies
    Flag controlling whether the observer can observe ComputableValue instances with lower priorities.
    Priority
    priority
    The priority of the underlying observer
    boolean
    reportParameters
    Return true if the parameters should be reported to the core Arez runtime.
    boolean
    reportResult
    Return true if the return value of the observed function (if any) should be reported to the Arez spy subsystem.

  • Element Details

    • name

      @Nonnull String name
      Return the name of the Observer relative to the component. 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 name of the Observer relative to the component.
      Default:
      "<default>"

    • mutation

      boolean mutation
      Does the observer's tracking method change arez state or not. Observers are primarily used to reflect Arez state onto external systems (i.e. views, network layers etc.) and thus the default value is false thus making the transaction mode read-only.
      Returns:
      true if the observer should use a read-write transaction, false if it should use a read-only transaction.
      Default:
      false

    • priority

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

    • executor

      Executor executor
      The actor responsible for calling the observed method.
      Returns:
      the actor responsible for calling the observed method.
      Default:
      INTERNAL

    • observeLowerPriorityDependencies

      boolean observeLowerPriorityDependencies
      Flag controlling whether the 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 that 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

    • nestedActionsAllowed

      boolean nestedActionsAllowed
      Can the observer invoke actions. An action that specifies Action.requireNewTransaction() as true will start a new transaction and any observables accessed within the action will not be dependencies of the observer. Sometimes this behaviour is desired. Sometimes an action that specifies Action.requireNewTransaction() as false will be used instead and any observable accessed within the scope of the action will be a dependency of the observer and thus changes in the observable will reschedule the observer. Sometimes this behaviour is desired. Either way the developer must be conscious of these decisions and thus must explicitly set this flag to true to invoke any actions within the scope of the observers reaction.
      Returns:
      true if the observer can invoke actions, false otherwise.
      Default:
      false

    • reportParameters

      boolean reportParameters
      Return true if the parameters should be reported to the core Arez runtime. It is useful to disable reporting for large, circular or just uninteresting parameters to the spy infrastructure.
      Returns:
      true to report the parameters, false otherwise.
      Default:
      true

    • reportResult

      boolean reportResult
      Return true if the return value of the observed function (if any) 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. This is only useful if the value of executor() is set to Executor.EXTERNAL as otherwise the result is not reported anyway.
      Returns:
      true to report the return value, false otherwise.
      Default:
      true

    • depType

      @Nonnull DepType depType
      Enum indicating whether the Observer is derived from arez elements and/or external dependencies. If set to DepType.AREZ then the arez runtime 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 observed to exist with no dependencies. If set to DepType.AREZ_OR_EXTERNAL then the component must define a ObserverRef method and should invoke Observer.reportStale() when the non-arez dependencies are changed.
      Returns:
      the type of dependencies allowed in the observed method.
      Default:
      AREZ