Module io.inverno.mod.base
Package io.inverno.mod.base

Class Settable<T>

java.lang.Object
io.inverno.mod.base.Settable<T>
Type Parameters:
T - the type of value
public final class Settable<T> extends Object

A container object which may or may not contain a value which can be null. If a value has been set, isSet() returns true. If not value has been set, the object is considered undefined and isUndefined() returns false.

Unlike Optional which is used to represent "no result": a value or null, a Settable is used to represent undefined values: a value, null or undefined.

This basically allows to implement overriding logic where a base value can be left untouched or overridden with a new value or null depending on whether a corresponding Settable was set or not.

It should be used as return method type where there is a need to represent undefined values for which it is important to determine whether a value, including null, was set or not. A variable whose type is Settable should never itself be null; it should always point to a Settable instance.

Since:
1.12
Author:
Jeremy Kuhn

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object o)
     
    <U> Settable<U>
    flatMap(Function<? super T,? extends Settable<? extends U>> mapper)
    If a value is set, returns the result of applying the given Settable-bearing mapping function to the value, otherwise returns an undefined Settable.
    T
    get()
    If a value is set, returns the value, otherwise throws NoSuchElementException.
    int
    hashCode()
     
    void
    ifSet(Consumer<? super T> action)
    If a value is set, performs the given action with the value, otherwise does nothing.
    void
    ifSetOrElse(Consumer<? super T> action, Runnable undefinedAction)
    If a value is set, performs the given action with the value, otherwise performs the given empty-based action.
    boolean
    isSet()
    If a value is set, returns true, otherwise false.
    boolean
    isUndefined()
    If no value is set, returns true, otherwise false.
    <U> Settable<U>
    map(Function<? super T,? extends U> mapper)
    If a value is set, returns an Settable describing the result of applying the given mapping function to the value, otherwise returns an undefined Settable.
    static <T> Settable<T>
    of(T value)
    Returns an Settable describing the given value which can be null.
    T
    orElse(T other)
    If a value is set, returns the value, otherwise returns other.
    T
    orElseGet(Supplier<? extends T> supplier)
    If a value is set, returns the value, otherwise returns the result produced by the supplying function.
    T
    orElseThrow()
    If a value is set, returns the value, otherwise throws NoSuchElementException.
    <X extends Throwable>
    T
    orElseThrow(Supplier<? extends X> exceptionSupplier)
    If a value is set, returns the value, otherwise throws an exception produced by the exception supplying function.
    Optional<T>
    toOptional()
    Converts the Settable to an Optional.
    static <T> Settable<T>
    undefined()
    Returns an undefined Settable instance.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • flatMap

      public <U> Settable<U> flatMap(Function<? super T,? extends Settable<? extends U>> mapper) throws NullPointerException

      If a value is set, returns the result of applying the given Settable-bearing mapping function to the value, otherwise returns an undefined Settable.

      This method is similar to map(Function), but the mapping function is one whose result is already an Settable, and if invoked, flatMap does not wrap it within an additional Settable.

      Type Parameters:
      U - the type of value of the Settable returned by the mapping function
      Parameters:
      mapper - the mapping function to apply to a value, if set
      Returns:
      the result of applying an Settable-bearing mapping function to the value of this Settable, if a value is set, otherwise an undefined Settable
      Throws:
      NullPointerException - if the mapping function is null or returns a null result

    • get

      public T get() throws NoSuchElementException

      If a value is set, returns the value, otherwise throws NoSuchElementException.

      The preferred alternative to this method is orElseThrow().

      Returns:
      the value described by this Settable which can be null
      Throws:
      NoSuchElementException - if no value is set

    • ifSet

      public void ifSet(Consumer<? super T> action) throws NullPointerException

      If a value is set, performs the given action with the value, otherwise does nothing.

      Parameters:
      action - the action to be performed, if a value is set
      Throws:
      NullPointerException - if value is set and the given action is null

    • ifSetOrElse

      public void ifSetOrElse(Consumer<? super T> action, Runnable undefinedAction) throws NullPointerException

      If a value is set, performs the given action with the value, otherwise performs the given empty-based action.

      Parameters:
      action - the action to be performed, if a value is set
      undefinedAction - the empty-based action to be performed, if no value is set
      Throws:
      NullPointerException - if a value is set and the given action is null, or no value is set and the given empty-based action is null.

    • isSet

      public boolean isSet()

      If a value is set, returns true, otherwise false.

      Returns:
      true if a value is set, otherwise false

    • isUndefined

      public boolean isUndefined()

      If no value is set, returns true, otherwise false.

      Returns:
      true if no value is set, otherwise false

    • map

      public <U> Settable<U> map(Function<? super T,? extends U> mapper) throws NullPointerException

      If a value is set, returns an Settable describing the result of applying the given mapping function to the value, otherwise returns an undefined Settable.

      By the definition, the mapping function can return a null resulting in a Settable with a null value being returned.

      Type Parameters:
      U - the type of the value returned from the mapping function
      Parameters:
      mapper - the mapping function to apply to a value, if set
      Returns:
      a Settable describing the result of applying a mapping function to the value of this Settable, if a value is set, otherwise an empty Settable
      Throws:
      NullPointerException - if the mapping function is null

    • orElse

      public T orElse(T other)

      If a value is set, returns the value, otherwise returns other.

      Parameters:
      other - the value to be returned, if no value is set. May be null.
      Returns:
      the value, if set, otherwise other

    • orElseGet

      public T orElseGet(Supplier<? extends T> supplier) throws NullPointerException

      If a value is set, returns the value, otherwise returns the result produced by the supplying function.

      Parameters:
      supplier - the supplying function that produces a value to be returned
      Returns:
      the value, if set, otherwise the result produced by the supplying function
      Throws:
      NullPointerException - if no value is set and the supplying function is null

    • orElseThrow

      public T orElseThrow() throws NoSuchElementException

      If a value is set, returns the value, otherwise throws NoSuchElementException.

      Returns:
      the value described by this Settable which can be null
      Throws:
      NoSuchElementException - if no value is set

    • orElseThrow

      public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X, NullPointerException

      If a value is set, returns the value, otherwise throws an exception produced by the exception supplying function.

      Type Parameters:
      X - the type of the exception to be thrown
      Parameters:
      exceptionSupplier - the supplying function that produces an exception to be thrown
      Returns:
      the value described by this Settable which can be null
      Throws:
      X - if no value is set
      NullPointerException - if no value is set and the exception supplying function is null

    • toOptional

      public Optional<T> toOptional()

      Converts the Settable to an Optional.

      The returned Optional is empty when the Settable is undefined or if its value is null.

      Returns:
      an Optional with a present value if the Settable is set with a non-null value or an empty Optional if it is not set or set with a null value

    • undefined

      public static <T> Settable<T> undefined()

      Returns an undefined Settable instance. No value is set for this Settable.

      Though it may be tempting to do so, avoid testing if an object is undefined by comparing with == or != against instances returned by Settable.undefined(). There is no guarantee that it is a singleton. Instead, use isUndefined() or isSet().

      Type Parameters:
      T - The type of the non-existent value
      Returns:
      an undefined Settable

    • of

      public static <T> Settable<T> of(T value)

      Returns an Settable describing the given value which can be null.

      Type Parameters:
      T - the type of the value
      Parameters:
      value - the value to describe, which can be null
      Returns:
      a Settable with the value set

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object