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(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.
    C
    orElseNullable(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.
    @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.

    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
      Since:
      11

    • 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.
      Since:
      9

    • 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

    • 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 for alternative UI tree querying operations.
      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
      Since:
      9

    • orElseNullable

      public C orElseNullable(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(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
      Since:
      10

    • 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