Package swingtree

Class OptionalUI<C extends Component>

java.lang.Object
swingtree.OptionalUI<C>
Type Parameters:
C - the type of component held by this instance
public final class OptionalUI<C extends Component> extends Object
A container object for AWT Component types which may or may not contain a non-null value. If a value is present, isPresent() returns true. If no value is present, the object is considered empty and isPresent() returns false.

Additional methods that depend on the presence or absence of a contained value are provided, such as orElse() (returns a default value if no value is present) and ifPresent() (performs an action if a value is present).

This is a value-based class; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of OptionalUI may have unpredictable results and should be avoided.

Note that OptionalUI is primarily intended for use as a SwingTree query return type where there is a clear need to represent "no result," and where returning null as well as expose the UI components to the application thread directly is likely to cause errors. A variable whose type is OptionalUI should never itself be null; it should always point to an OptionalUI instance.

Please take a look at the living swing-tree documentation where you can browse a large collection of examples demonstrating how to use the API of this class.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object obj)
    Indicates whether some other object is "equal to" this OptionalUI.
    OptionalUI<C>
    filter(Predicate<? super C> predicate)
    If a component is present, and the component matches the given predicate, returns an OptionalUI describing the component, otherwise returns an empty OptionalUI.
    int
    hashCode()
    Returns the hash code of the component, if present, otherwise 0 (zero) if no component is present.
    void
    ifPresent(Consumer<? super C> action)
    If a component is present, performs the given action with the component, otherwise does nothing.
    void
    ifPresentOrElse(Consumer<? super C> action, Runnable emptyAction)
    If a component is present, performs the given action with the component, otherwise performs the given empty-based action.
    boolean
    isEmpty()
    If a component is not present, returns true, otherwise false.
    boolean
    isPresent()
    If a component is present, returns true, otherwise false.
    <U> Optional<U>
    map(Function<? super C,? extends U> mapper)
    If a component is present, returns an OptionalUI describing (as if by ofNullable(T)) the result of applying the given mapping function to the component, otherwise returns an empty OptionalUI.
    OptionalUI<C>
    or(Supplier<? extends OptionalUI<? extends C>> supplier)
    If a component is present, returns an OptionalUI describing the component, otherwise returns an OptionalUI produced by the supplying function.
    C
    orElse(@NonNull C other)
    If a component is present, returns the component, otherwise returns other.
    C
    orElseGet(Supplier<? extends C> supplier)
    If a component is present, returns the component, otherwise returns the result produced by the supplying function.
    @Nullable C
    orElseNullable(@Nullable C other)
    If a component is present, returns the component, otherwise returns other or throws a null pointer exception if other is null.
    C
    orElseThrow()
    If a component is present, returns the component, otherwise throws NoSuchElementException.
    <X extends Throwable>
    C
    orElseThrow(Supplier<? extends X> exceptionSupplier)
    If a component is present, returns the component, otherwise throws an exception produced by the exception supplying function.
    OptionalUI<C>
    orGet(Supplier<? extends C> supplier)
    If no component is present, the supplying function is called to provide an alternative UI component to be used in place of the missing component.
    OptionalUI<C>
    orGetIf(boolean condition, Supplier<? extends C> supplier)
    If no component is present and the supplied boolean is true, the supplying function is called to provide an alternative UI component to be used in place of the missing component.
    <A extends B, B extends C>
    OptionalUI<C>
    orGetUi(Supplier<UIForAnything<?,A,B>> supplier)
    If a component is present, returns an OptionalUI describing the component, otherwise returns a OptionalUI containing the component built by the UI declaration inside the supplying function.
    <A extends B, B extends C>
    OptionalUI<C>
    orGetUiIf(boolean condition, Supplier<UIForAnything<?,A,B>> supplier)
    If no component is present and the supplied boolean is true, the supplying function is called to provide an alternative UI declaration to be used to build the missing component.
    @Nullable C
    orNull()
    If a component is present, returns the component, otherwise returns null.
    String
    toString()
    Returns a non-empty string representation of this OptionalUI suitable for debugging.
    OptionalUI<C>
    update(Function<C,C> mapper)
    An alternative to map(Function) that maps to the same type in yet another OptionalUI instance.
    OptionalUI<C>
    updateIf(boolean condition, Function<C,C> mapper)
    An alternative to update(Function) and map(Function) that maps to the same type in yet another OptionalUI instance but with the difference that the mapping function is only applied if the component is present and the supplied boolean is true.
    <U extends C>
    OptionalUI<C>
    updateIf(Class<U> type, Function<U,U> mapper)
    An alternative to update(Function) and map(Function) that maps to the same type in yet another OptionalUI instance but with the difference that the mapping function is only applied if the component is present and assignable to the given type.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • isPresent

      public boolean isPresent()
      If a component is present, returns true, otherwise false.
      Returns:
      true if a component is present, otherwise false

    • isEmpty

      public boolean isEmpty()
      If a component is not present, returns true, otherwise false.
      Returns:
      true if a component is not present, otherwise false

    • ifPresent

      public void ifPresent(Consumer<? super C> action)
      If a component is present, performs the given action with the component, otherwise does nothing.
      Parameters:
      action - the action to be performed, if a component is present
      Throws:
      NullPointerException - if component is present and the given action is null

    • ifPresentOrElse

      public void ifPresentOrElse(Consumer<? super C> action, Runnable emptyAction)
      If a component is present, performs the given action with the component, otherwise performs the given empty-based action.
      Parameters:
      action - the action to be performed, if a component is present
      emptyAction - the empty-based action to be performed, if no component is present
      Throws:
      NullPointerException - if a component is present and the given action is null, or no component is present and the given empty-based action is null.

    • filter

      public OptionalUI<C> filter(Predicate<? super C> predicate)
      If a component is present, and the component matches the given predicate, returns an OptionalUI describing the component, otherwise returns an empty OptionalUI.
      Parameters:
      predicate - the predicate to apply to a component, if present
      Returns:
      an OptionalUI describing the component of this OptionalUI, if a component is present and the component matches the given predicate, otherwise an empty OptionalUI
      Throws:
      NullPointerException - if the predicate is null

    • map

      public <U> Optional<U> map(Function<? super C,? extends U> mapper)
      If a component is present, returns an OptionalUI describing (as if by ofNullable(T)) the result of applying the given mapping function to the component, otherwise returns an empty OptionalUI.

      If the mapping function returns a null result then this method returns an empty OptionalUI.

      Type Parameters:
      U - The type of the component returned from the mapping function
      Parameters:
      mapper - the mapping function to apply to a component, if present
      Returns:
      an Optional describing the result of applying a mapping function to the UI component of this OptionalUI, if a component is present, otherwise an empty OptionalUI
      Throws:
      NullPointerException - if the mapping function is null

    • update

      public OptionalUI<C> update(Function<C,C> mapper)
      An alternative to map(Function) that maps to the same type in yet another OptionalUI instance. This is useful for chaining UI centric operations. The mapping function should return an OptionalUI instance.
      Parameters:
      mapper - The mapping function to apply to a component, if present.
      Returns:
      an OptionalUI describing the result of applying a mapping function to the UI component of this OptionalUI, if a component is present, otherwise an empty OptionalUI
      Throws:
      NullPointerException - if the mapping function is null

    • updateIf

      public <U extends C> OptionalUI<C> updateIf(Class<U> type, Function<U,U> mapper)
      An alternative to update(Function) and map(Function) that maps to the same type in yet another OptionalUI instance but with the difference that the mapping function is only applied if the component is present and assignable to the given type.
      It is a type conditional mapping operation.
      Type Parameters:
      U - The type of the component returned from the mapping function.
      Parameters:
      type - The type to check if the component is assignable to.
      mapper - The mapping function to apply to a component of the given type, if present.
      Returns:
      An OptionalUI describing the result of applying a mapping function to the UI component of this OptionalUI, if a component is present and the component is assignable to the given type, otherwise an empty OptionalUI.
      Throws:
      NullPointerException - if the mapping function is null
      NullPointerException - if the given type is null

    • updateIf

      public OptionalUI<C> updateIf(boolean condition, Function<C,C> mapper)
      An alternative to update(Function) and map(Function) that maps to the same type in yet another OptionalUI instance but with the difference that the mapping function is only applied if the component is present and the supplied boolean is true.
      It is a conditional mapping operation.
      Parameters:
      condition - The boolean to check before applying the mapping function.
      mapper - The mapping function to apply to a component, if present and the condition is true.
      Returns:
      An OptionalUI describing the result of applying a mapping function to the UI component of this OptionalUI, if a component is present and the condition is true, otherwise an empty OptionalUI.
      Throws:
      NullPointerException - if the mapping function is null

    • or

      public OptionalUI<C> or(Supplier<? extends OptionalUI<? extends C>> supplier)
      If a component is present, returns an OptionalUI describing the component, otherwise returns an OptionalUI produced by the supplying function. Use this to provide alternative UI components.
      Parameters:
      supplier - the supplying function that produces an OptionalUI to be returned
      Returns:
      returns an OptionalUI describing the component of this OptionalUI, if a component is present, otherwise an OptionalUI produced by the supplying function.
      Throws:
      NullPointerException - if the supplying function is null or produces a null result

    • orGet

      public OptionalUI<C> orGet(Supplier<? extends C> supplier)
      If no component is present, the supplying function is called to provide an alternative UI component to be used in place of the missing component. Otherwise, returns a OptionalUI containing the current component and the supplying function is not called. Use this to define alternative UI components.
      Parameters:
      supplier - the supplying function that produces a UI component to be used if no component is present.
      Returns:
      returns an OptionalUI describing the component of this OptionalUI, if a component is present, otherwise an OptionalUI produced by the supplying function.
      Throws:
      NullPointerException - if the supplying function is null or produces a null result

    • orGetIf

      public OptionalUI<C> orGetIf(boolean condition, Supplier<? extends C> supplier)
      If no component is present and the supplied boolean is true, the supplying function is called to provide an alternative UI component to be used in place of the missing component. Otherwise, returns a OptionalUI containing the current component and the supplying function is not called. Use this to define alternative UI components if a condition is met.
      Parameters:
      condition - The boolean condition to check before calling the supplying function. If false, the supplying function is simply ignored.
      supplier - the supplying function that produces a UI component to be used if no component is present.
      Returns:
      returns an OptionalUI describing the component of this OptionalUI, if a component is present, otherwise an OptionalUI produced by the supplying function.
      Throws:
      NullPointerException - if the supplying function is null or produces a null result

    • orGetUi

      public <A extends B, B extends C> OptionalUI<C> orGetUi(Supplier<UIForAnything<?,A,B>> supplier)
      If a component is present, returns an OptionalUI describing the component, otherwise returns a OptionalUI containing the component built by the UI declaration inside the supplying function. Use this to provide alternative UI components.
      Type Parameters:
      A - The type of the component to be built.
      B - The base type of the component to be built.
      Parameters:
      supplier - the supplying function that produces a UI declaration to be used if no component is present.
      Returns:
      returns an OptionalUI describing the component of this OptionalUI, if a component is present, otherwise an OptionalUI produced by the supplying function.
      Throws:
      NullPointerException - if the supplying function is null or produces a null result

    • orGetUiIf

      public <A extends B, B extends C> OptionalUI<C> orGetUiIf(boolean condition, Supplier<UIForAnything<?,A,B>> supplier)
      If no component is present and the supplied boolean is true, the supplying function is called to provide an alternative UI declaration to be used to build the missing component. Otherwise, returns the current OptionalUI and the supplying function is not called. Use this to define alternative UI declaration if a condition is met.
      Type Parameters:
      A - The type of the component to be built.
      B - The base type of the component to be built.
      Parameters:
      condition - The boolean condition to check before calling the supplying function. If false, the supplying function is simply ignored.
      supplier - the supplying function that produces a UI declaration to be used if no component is present.
      Returns:
      returns an OptionalUI describing the component of this OptionalUI, if a component is present, otherwise an OptionalUI produced by the supplying function.
      Throws:
      NullPointerException - if the supplying function is null or produces a null result

    • orElseNullable

      public @Nullable C orElseNullable(@Nullable C other)
      If a component is present, returns the component, otherwise returns other or throws a null pointer exception if other is null.
      Parameters:
      other - the component to be returned, if no component is present. May not be null.
      Returns:
      the component, if present, otherwise other

    • orElse

      public C orElse(@NonNull C other)
      If a component is present, returns the component, otherwise returns other.
      Parameters:
      other - the component to be returned, if no component is present. May not be null, use orElseNullable(Component) if it can be null.
      Returns:
      the component, if present, otherwise other

    • orNull

      public @Nullable C orNull()
      If a component is present, returns the component, otherwise returns null.
      Returns:
      The component wrapped in this OptionalUI, or null if no component is present.

    • orElseGet

      public C orElseGet(Supplier<? extends C> supplier)
      If a component is present, returns the component, otherwise returns the result produced by the supplying function.
      Parameters:
      supplier - the supplying function that produces a component to be returned
      Returns:
      the component, if present, otherwise the result produced by the supplying function
      Throws:
      NullPointerException - if no component is present and the supplying function is null

    • orElseThrow

      public C orElseThrow()
      If a component is present, returns the component, otherwise throws NoSuchElementException.
      Returns:
      the non-null component described by this OptionalUI
      Throws:
      NoSuchElementException - if no component is present

    • orElseThrow

      public <X extends Throwable> C orElseThrow(Supplier<? extends X> exceptionSupplier) throws X
      If a component is present, returns the component, otherwise throws an exception produced by the exception supplying function.

      Note that A method reference to the exception constructor with an empty argument list can be used as the supplier. For example, IllegalStateException::new

      Type Parameters:
      X - Type of the exception to be thrown
      Parameters:
      exceptionSupplier - the supplying function that produces an exception to be thrown
      Returns:
      the component, if present
      Throws:
      X - if no component is present
      NullPointerException - if no component is present and the exception supplying function is null

    • equals

      public boolean equals(Object obj)
      Indicates whether some other object is "equal to" this OptionalUI. The other object is considered equal if:
      • it is also an OptionalUI and;
      • both instances have no component present or;
      • the present components are "equal to" each other via equals().
      Overrides:
      equals in class Object
      Parameters:
      obj - an object to be tested for equality
      Returns:
      true if the other object is "equal to" this object otherwise false

    • hashCode

      public int hashCode()
      Returns the hash code of the component, if present, otherwise 0 (zero) if no component is present.
      Overrides:
      hashCode in class Object
      Returns:
      hash code component of the present component or 0 if no component is present

    • toString

      public String toString()
      Returns a non-empty string representation of this OptionalUI suitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.

      If a component is present the result must include its string representation in the result. Empty and present OptionalUIs must be unambiguously differentiable.

      Overrides:
      toString in class Object
      Returns:
      the string representation of this instance