Package arez.annotations

Annotation Interface Observable

@Documented
@Target(METHOD)
public @interface Observable

Annotation applied to methods that expose an ObservableValue value in Arez. Methods annotated with this either query state or mutate state. The query method is expected to have 0 parameters and return a value and by default is named with "get" or "is" prefixed to the property name. The mutation method is expected to have a single parameter and return no value and by default is named with "set" prefixed to property name. The setter or getter can also be named matching the property name without the prefix.

Only one of the query or mutation method needs to be annotated with this annotation if the other method follows the normal conventions. If the other method does not conform to conventions, then you will need to annotate the pair and specify a value for name().

The method should only invoked within the scope of a transaction. The mutation method requires that the transaction be READ_WRITE.

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 not be private
• Must not be static
• Must not be final
• May be abstract but if abstract then the paired setter or getter must also be abstract
• Must be accessible to the class annotated by the ArezComponent annotation.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
boolean	expectSetter	Set this to false if there is no setter method and the component is expected to use ObservableValueRef to indicate when value has changed.
Feature	initializer	Indicate whether the generated component class should add a parameter to the constructor to initialize this property.
String	name	Return the name of the ObservableValue relative to the component.
Feature	readOutsideTransaction	Indicate whether the observable can be read outside a transaction.
boolean	setterAlwaysMutates	Return false if the setter should verify observable value has changed before propagating change.
Feature	writeOutsideTransaction	Return true if the observable will create an action if the write occurs outside a transaction.

Element Details

name

@Nonnull String name

Return the name of the ObservableValue relative to the component. If not specified will default to the name of the property by convention as described above. 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 ObservableValue relative to the component.

Default:

"<default>"

expectSetter

boolean expectSetter

Set this to false if there is no setter method and the component is expected to use ObservableValueRef to indicate when value has changed.

Returns:

true if there is expected to be a setter, false if there should be no setter.

Default:

true

initializer

Feature initializer

Indicate whether the generated component class should add a parameter to the constructor to initialize this property. This parameter should only be set to Feature.ENABLE when the observable property is defined by a pair of abstract methods. If set to Feature.AUTODETECT then an initializer will be added for an observable property if it is defined by a pair of abstract methods and the values is annotated with the Nonnull annotation and it is not annotated by Inverse.

The initializer parameters will be added as additional parameters at the end of the parameter list in the generated classes constructors. The initializers will be defined in the order that the observable properties are declared. They properties be assigned after the parent constructor has been invoked.

Returns:

flag controlling whether a parameter should be added to the constructor to initialize the property.

Default:

AUTODETECT

readOutsideTransaction

Feature readOutsideTransaction

Indicate whether the observable 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 observable can be read outside a transaction and the ObservableValue.reportObserved() will only be invoked if the observables is accessed from within a tracking transaction (i.e. when an Observer or ComputableValue creates the transaction). Thus, Action annotated methods that only access observables that set the readOutsideTransaction parameter to Feature.ENABLE and neither access nor modify other arez elements no longer need to be annotated with Action annotations.

Returns:

flag that determines whether the observable allows reads outside a transaction, false to require a transaction to read the observable.

Default:

AUTODETECT

writeOutsideTransaction

Feature writeOutsideTransaction

Return true if the observable will create an action if the write occurs outside a transaction.

Returns:

true to allow writes to create an action if needed, false to require a transaction to write observable.

Default:

AUTODETECT

setterAlwaysMutates

boolean setterAlwaysMutates

Return false if the setter should verify observable value has changed before propagating change. In some scenarios, the setter method will modify the value before updating the observable or may decide to abort the update. This setting will force the generated code to check the value of the observable property after the setter and only invoke ObservableValue.reportChanged() if a change has actually occurred.

This parameter should not be set to false if the associated setter is abstract. It is also invalid to set this value to false if expectSetter() is false.

Returns:

false if the setter should verify observable value has changed before propagating change.

Default:

true