Interface State

All Superinterfaces:
ObservableState, Observer<Boolean>, Sensor

public interface State extends ObservableState
A class encapsulating a boolean state.
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();
A factory for 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:
  • Method Details

    • set

      void set(boolean value)
      Sets the value

      A 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 an ObservableState notified each time the state changes, setting it to its current value notifying no one.
      Returns:
      an ObservableState notified each time the state changes
    • value

      Value<Boolean> value()

      Returns the Value this state is a view over.

      Writing through it is equivalent to set(boolean): the validators, the Value.locked() state, the notification and any State.Group this state belongs to all live on the value, so nothing is stepped around. What it adds is the nullable Boolean surface, where null lands on the false substitute, and the Value operations a State has no equivalent for.

      It is exposed because a State is built on a Value rather than beside one - link(State) links the two values, and the validators and the lock are the value's throughout.

      Returns:
      the Value instance this state is a view over
    • link

      void link(State originalState)
      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 as originalState.
      Parameters:
      originalState - the original state to link this state to
      Throws:
      IllegalStateException - in case the states are already linked or if a cycle is detected
      IllegalArgumentException - in case the original state is not valid according to this state's validators
    • unlink

      void unlink(State originalState)
      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

      boolean addValidator(Value.Validator<? super Boolean> validator)
      Adds a validator to this State. 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

      boolean removeValidator(Value.Validator<? super Boolean> validator)
      Removes the given validator from this state
      Parameters:
      validator - the validator
      Returns:
      true if this state contained the specified validator
    • state

      static State state()
      Creates a new 'false' State instance.
      Returns:
      a new State instance
    • state

      static State state(boolean value)
      Creates a new State instance.
      Parameters:
      value - the initial state value
      Returns:
      a new State instance
    • builder

      static State.Builder builder()
      Returns:
      a new State.Builder instance
    • present

      static <T> ObservableState present(Observable<T> observable)
      Subscribed to the observable for as long as it lives, see State.
      Type Parameters:
      T - the value type
      Parameters:
      observable - the observable
      Returns:
      an ObservableState active when the given observable has a value present, determined by Observable.optional().
    • is

      static <T> ObservableState is(Observable<T> observable, @Nullable T value)
      Subscribed to the observable for as long as it lives, see State.
      Type Parameters:
      T - the value type
      Parameters:
      observable - the observable
      value - the value
      Returns:
      an ObservableState active when the given observable's value is equal to the given one, determined by Observable.is(Object).
    • isNot

      static <T> ObservableState isNot(Observable<T> observable, @Nullable T value)
      Subscribed to the observable for as long as it lives, see State.
      Type Parameters:
      T - the value type
      Parameters:
      observable - the observable
      value - the value
      Returns:
      an ObservableState active when the given observable's value is not equal to the given one, determined by Observable.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, see State.
      Type Parameters:
      T - the value type
      Parameters:
      observable - the observable
      predicate - the predicate, tested when the state is created and each time the value changes, null included
      Returns:
      an ObservableState active when the given observable's value satisfies the given predicate
    • contains

      static <T> State contains(ValueSet<T> valueSet, T value)
      Creates a State synchronized with whether the given value is contained in the given ValueSet. 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)
      The initial state reflects whether the value is currently contained in the set.

      Setting the state asks the set first, so a change the set refuses, being locked or 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 State is reachable, the synchronization remains active
      • Once the returned State is 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 set
      value - the value
      Returns:
      a state synchronized with the set's containment of the value
    • and

      static ObservableState and(ObservableState... observableStates)
      Creates a new ObservableState instance using AND.

      An empty combination is false, rather than the true of 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 ObservableState instance
    • and

      static ObservableState and(Collection<? extends ObservableState> observableStates)
      Creates a new ObservableState instance using AND.

      An empty combination is false, rather than the true of 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 ObservableState instance
    • or

      static ObservableState or(ObservableState... observableStates)
      Creates a new ObservableState instance using OR.

      An empty combination is false. Empty is never an error, so an empty OR and an empty AND are alike false, see and(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 ObservableState instance
    • or

      static ObservableState or(Collection<? extends ObservableState> observableStates)
      Creates a new ObservableState instance using OR.

      An empty combination is false. Empty is never an error, so an empty OR and an empty AND are alike false, see and(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 ObservableState instance
    • group

      static State.Group group(State... states)
      Creates a new State.Group instance, 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.Group instance
      See Also:
    • group

      static State.Group group(Collection<? extends State> states)
      Creates a new State.Group instance, 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.Group instance
      See Also: