Interface State
- All Superinterfaces:
ObservableState, Observer<Boolean>, Sensor
State state = State.state();
ObservableState observable = state.observable();
observable.addConsumer(this::onStateChange);
state.set(true);
state.set(false);
boolean value = state.is();
ObservableState opposite = state.not();
State instances.
The state is set before its listeners and consumers are notified, so an exception thrown by one propagates
from set(boolean) with the state set, and ends the notification, those after it not notified, a linked
state among them.
A state derived from others, by and(ObservableState...), or(ObservableState...),
present(Observable), is(Observable, Object), isNot(Observable, Object) or
matches(Observable, Predicate), subscribes to its sources when created and stays subscribed for as long
as they live, whether it is still used or not. Derive it from sources that live no longer than whatever uses it,
a panel from the panel's own states for example, or create it once, alongside long-lived sources, rather than
once for each short-lived user. contains(ValueSet, Object) subscribes weakly instead, for as long as the
state it returns is reachable.
Thread Safety: Listener management (add/remove) is thread-safe and supports concurrent access, and
reading the state takes no lock, never waiting for a change being notified.
However, state modifications via set(boolean) and notification are NOT thread-safe and should be
performed from a single thread (such as an application UI thread).
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interfaceBuilds aStateinstance.static interfaceAState.Groupdeactivates all other states when a state in the group is activated. -
Method Summary
Modifier and TypeMethodDescriptionbooleanaddValidator(Value.Validator<? super Boolean> validator) Adds a validator to thisState.static ObservableStateand(ObservableState... observableStates) Creates a newObservableStateinstance using AND.static ObservableStateand(Collection<? extends ObservableState> observableStates) Creates a newObservableStateinstance using AND.static State.Builderbuilder()static <T> Statestatic State.GroupCreates a newState.Groupinstance, which guarantees that only a single state within the group is active at a timestatic State.Groupgroup(Collection<? extends State> states) Creates a newState.Groupinstance, which guarantees that only a single state within the group is active at a timestatic <T> ObservableStateis(Observable<T> observable, @Nullable T value) Subscribed to the observable for as long as it lives, seeState.static <T> ObservableStateisNot(Observable<T> observable, @Nullable T value) Subscribed to the observable for as long as it lives, seeState.voidCreates a bidirectional link between this and the given original state, so that changes in one are reflected in the other.static <T> ObservableStatematches(Observable<T> observable, Predicate<? super @Nullable T> predicate) Subscribed to the observable for as long as it lives, seeState.Returns anObservableStatenotified each time the state changes, setting it to its current value notifying no one.static ObservableStateor(ObservableState... observableStates) Creates a newObservableStateinstance using OR.static ObservableStateor(Collection<? extends ObservableState> observableStates) Creates a newObservableStateinstance using OR.static <T> ObservableStatepresent(Observable<T> observable) Subscribed to the observable for as long as it lives, seeState.booleanremoveValidator(Value.Validator<? super Boolean> validator) Removes the given validator from this statevoidset(boolean value) Sets the valuestatic Statestate()Creates a new 'false'Stateinstance.static Statestate(boolean value) Creates a newStateinstance.voidtoggle()Toggles this statevoidUnlinks this state from the given original statevalue()Returns theValuethis state is a view over.Methods inherited from interface ObservableState
is, notMethods inherited from interface Observer
addConsumer, addWeakConsumer, observer, removeConsumer, removeWeakConsumer, sensor, when, whenMethods inherited from interface Sensor
addListener, addWeakListener, removeListener, removeWeakListener
-
Method Details
-
set
void set(boolean value) Sets the valueA listener or consumer setting the state again, reverting a change, starts a nested notification of the new value, which supersedes the one in progress: once it has run, the notification of the value it replaced ends, so the listeners and consumers after the one setting it hear the new value alone.
- Parameters:
value- the new value
-
toggle
void toggle()Toggles this state -
observable
ObservableState observable()Returns anObservableStatenotified each time the state changes, setting it to its current value notifying no one.- Returns:
- an
ObservableStatenotified each time the state changes
-
value
Returns the
Valuethis state is a view over.Writing through it is equivalent to
set(boolean): the validators, theValue.locked()state, the notification and anyState.Groupthis state belongs to all live on the value, so nothing is stepped around. What it adds is the nullableBooleansurface, where null lands on thefalsesubstitute, and theValueoperations aStatehas no equivalent for.It is exposed because a
Stateis built on aValuerather than beside one -link(State)links the two values, and the validators and the lock are the value's throughout.- Returns:
- the
Valueinstance this state is a view over
-
link
Creates a bidirectional link between this and the given original state, so that changes in one are reflected in the other. Note that after a call to this method this state is the same asoriginalState.- Parameters:
originalState- the original state to link this state to- Throws:
IllegalStateException- in case the states are already linked or if a cycle is detectedIllegalArgumentException- in case the original state is not valid according to this state's validators
-
unlink
Unlinks this state from the given original state- Parameters:
originalState- the original value to unlink from this one- Throws:
IllegalStateException- in case the states are not linked
-
addValidator
Adds a validator to thisState. Adding the same validator again has no effect.- Parameters:
validator- the validator- Returns:
- true if this state did not already contain the specified validator
- Throws:
IllegalArgumentException- in case the current value is invalid according to the validator
-
removeValidator
Removes the given validator from this state- Parameters:
validator- the validator- Returns:
- true if this state contained the specified validator
-
state
-
state
-
builder
- Returns:
- a new
State.Builderinstance
-
present
Subscribed to the observable for as long as it lives, seeState.- Type Parameters:
T- the value type- Parameters:
observable- the observable- Returns:
- an
ObservableStateactive when the given observable has a value present, determined byObservable.optional().
-
is
Subscribed to the observable for as long as it lives, seeState.- Type Parameters:
T- the value type- Parameters:
observable- the observablevalue- the value- Returns:
- an
ObservableStateactive when the given observable's value is equal to the given one, determined byObservable.is(Object).
-
isNot
Subscribed to the observable for as long as it lives, seeState.- Type Parameters:
T- the value type- Parameters:
observable- the observablevalue- the value- Returns:
- an
ObservableStateactive when the given observable's value is not equal to the given one, determined byObservable.isNot(Object).
-
matches
static <T> ObservableState matches(Observable<T> observable, Predicate<? super @Nullable T> predicate) Subscribed to the observable for as long as it lives, seeState.- Type Parameters:
T- the value type- Parameters:
observable- the observablepredicate- the predicate, tested when the state is created and each time the value changes, null included- Returns:
- an
ObservableStateactive when the given observable's value satisfies the given predicate
-
contains
Creates aStatesynchronized with whether the given value is contained in the givenValueSet. The state is bidirectionally synchronized:- When the value is added to or removed from the set, the state is updated accordingly
- When the state is set to
true, the value is added to the set (if not already present) - When the state is set to
false, the value is removed from the set (if present)
Setting the state asks the set first, so a change the set refuses, being
lockedor by a validator, is refused by the state as well, with the same exception, neither changing.The state is set on whichever thread changes the set, so change the set and the state on the same thread: the set changed on one thread while the state is set on another can deadlock, each holding its own lock through its notification while waiting for the other's.
The synchronization is maintained via a weak listener on the
ValueSet, meaning:- As long as the returned
Stateis reachable, the synchronization remains active - Once the returned
Stateis no longer reachable and is garbage collected, the synchronization is automatically cleaned up
ValueSet<String> tags = ValueSet.valueSet(); State containsImportant = State.contains(tags, "important"); // State → Set containsImportant.set(true); tags.contains("important"); // true // Set → State tags.remove("important"); containsImportant.is(); // false- Type Parameters:
T- the value type- Parameters:
valueSet- the value setvalue- the value- Returns:
- a state synchronized with the set's containment of the value
-
and
Creates a newObservableStateinstance using AND.An empty combination is
false, rather than thetrueof vacuous truth. These states typically gate something, and one assembled from a list that came out empty should leave whatever it gates alone, not enable something whose conditions were never checked.Empty is never an error - an empty combination assembled from data is a quiet "nothing to require yet", not a reason to fail - which does mean an empty AND and an empty OR are alike
false.Subscribed to the observable states for as long as they live, see
State.- Parameters:
observableStates- the observable states to base this state combination on- Returns:
- a new
ObservableStateinstance
-
and
Creates a newObservableStateinstance using AND.An empty combination is
false, rather than thetrueof vacuous truth. These states typically gate something, and one assembled from a list that came out empty should leave whatever it gates alone, not enable something whose conditions were never checked.Empty is never an error - an empty combination assembled from data is a quiet "nothing to require yet", not a reason to fail - which does mean an empty AND and an empty OR are alike
false.Subscribed to the observable states for as long as they live, see
State.- Parameters:
observableStates- the observable states to base this state combination on- Returns:
- a new
ObservableStateinstance
-
or
Creates a newObservableStateinstance using OR.An empty combination is
false. Empty is never an error, so an empty OR and an empty AND are alikefalse, seeand(ObservableState...).Subscribed to the observable states for as long as they live, see
State.- Parameters:
observableStates- the observable states to base this state combination on- Returns:
- a new
ObservableStateinstance
-
or
Creates a newObservableStateinstance using OR.An empty combination is
false. Empty is never an error, so an empty OR and an empty AND are alikefalse, seeand(ObservableState...).Subscribed to the observable states for as long as they live, see
State.- Parameters:
observableStates- the observable states to base this state combination on- Returns:
- a new
ObservableStateinstance
-
group
Creates a newState.Groupinstance, which guarantees that only a single state within the group is active at a time- Parameters:
states- the states to add to the group initially, not required- Returns:
- a new
State.Groupinstance - See Also:
-
group
Creates a newState.Groupinstance, which guarantees that only a single state within the group is active at a time- Parameters:
states- the states to add to the group initially- Returns:
- a new
State.Groupinstance - See Also:
-