react4j.annotations

Annotation Type Prop

@Documented
 @Target(value=METHOD)
public @interface Prop

Annotation used to specify an abstract method that returns a prop. The property is extracted from Reacts underlying props object.

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

• Must not be annotated with any other react annotation
• Must have 0 parameters
• Must return a value
• Must be an abstract instance method
• Must not throw exceptions
• Must be accessible from the same package as the class annotated by ReactComponent
• Should not be public as not expected to be invoked outside the component. A warning will be generated but can be suppressed by the SuppressWarnings or SuppressReact4jWarnings annotations with a key "React4j:PublicMethod". 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 ReactComponent annotation as the method is not expected to be invoked outside the component. A warning will be generated but can be suppressed by the SuppressWarnings or SuppressReact4jWarnings annotations with a key "React4j:ProtectedMethod".

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Feature	disposable Return an enum indicating whether the component should check whether the value of the prop is disposed prior to rendering.
boolean	immutable True if the prop is not expected to change after initial value is set.
java.lang.String	name Return the name of the prop.
Feature	observable Indicate whether the prop should be annotated by Observable.
Feature	require Return enum indicating whether prop should be when component is constructed.
Feature	shouldUpdateOnChange Indicate whether changing the value of the prop should schedule a re-render.

Element Detail

name

@Nonnull
public abstract java.lang.String name

Return the name of the prop. If the underlying method conforms to java beans accessor conventions (i.e. starts with "is" and is a boolean or starts with "get") then the name is the same as the java bean convention dictates, otherwise the name of the method is used as the default value for the prop.

Returns:

the name of the prop.

Default:

"<default>"

require

public abstract Feature require

Return enum indicating whether prop should be when component is constructed. This influences validation when enabled and how the Builder class is created. If set to Feature.ENABLE then the user MUST supply the prop and the builder will require the user to specify the value. If set to Feature.DISABLE then the user can optionally supply the prop. If set to Feature.AUTODETECT then the annotation processor will treat it as Feature.DISABLE if there is a corresponding PropDefault for the prop, otherwise it will be treated as Feature.ENABLE.

Returns:

the flag indicating whether the prop needs to be supplied.

Default:

react4j.annotations.Feature.AUTODETECT

shouldUpdateOnChange

public abstract Feature shouldUpdateOnChange

Indicate whether changing the value of the prop should schedule a re-render. If set to Feature.AUTODETECT then the annotation processor will treat it as Feature.ENABLE unless immutable() is set to true.

Returns:

the enum indicating whether prop should trigger a render if it is modified.

Default:

react4j.annotations.Feature.AUTODETECT

observable

public abstract Feature observable

Indicate whether the prop should be annotated by Observable.

If set to Feature.AUTODETECT then the prop will be observable if and only if:

• shouldUpdateOnChange() is not set to Feature.DISABLE.
• the component has at least one method annotated with Memoize or Observe.

Returns:

the enum indicating whether prop is observable.

Default:

react4j.annotations.Feature.AUTODETECT

disposable

public abstract Feature disposable

Return an enum indicating whether the component should check whether the value of the prop is disposed prior to rendering. If the value is disposed then the render method will exit early and return null. If this parameter is set to Feature.AUTODETECT then the annotation processor will inspect the type of the prop and treat it as Feature.ENABLE if the type is annotated with the ArezComponent annotation or the ActAsComponent annotation.

Returns:

an enum indicating whether the component should check whether the value of the prop is disposed prior to rendering.

Default:

react4j.annotations.Feature.AUTODETECT

immutable

public abstract boolean immutable

True if the prop is not expected to change after initial value is set. If the value of the prop does change then it is expected that the react component will be unmounted and a new component created. This is implemented by synthesizing a key for the component every time the component that is derived from this prop. To enable this the annotation processor must be able to identify the type of the prop so that a key can be synthesized. The following types are supported by the annotation processor;

• primitive types (i.e. boolean, short etc) and their corresponding boxed types (i.e. Boolean, Short etc).
• the String type
• any class that implements Keyed
• any class that is annotated with ArezComponent where the ArezComponent.requireId() parameter does not resolve to Feature.DISABLE
• any class or interface that is annotated with ActAsComponent. It is assumed that every implementation is an Arez component where the ArezComponent.requireId() parameter does not resolve to Feature.DISABLE

It should be noted that if a type implements Keyed and is annotated with either ArezComponent or ActAsComponent then the annotation processor will assume the Keyed interface is to used in preference to other alternative strategies.

In the future, the annotation processor may include additional allowable types such as those that implement Identifiable directly or other primitive types within the runtime library. These other types will be added if demand is established, othewise an additional hook will be added to allow users to customize key generation using a static method on the component.

Returns:

true if changing the prop recreates the component.

Default:

false