OptionalUI.java

package swingtree;

import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.awt.Component;
import java.util.NoSuchElementException;
import java.util.Objects;
import java.util.Optional;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Predicate;
import java.util.function.Supplier;

/**
 * A container object for AWT {@link Component} types
 * which may or may not contain a non-{@code null} value.
 * If a value is present, {@code isPresent()} returns {@code true}. If no
 * value is present, the object is considered <i>empty</i> and
 * {@code isPresent()} returns {@code false}.
 *
 * <p>Additional methods that depend on the presence or absence of a contained
 * value are provided, such as {@link #orElse(Component) orElse()}
 * (returns a default value if no value is present) and
 * {@link #ifPresent(Consumer) ifPresent()} (performs an
 * action if a value is present).
 *
 * <p>This is a <b>value-based</b>
 * class; use of identity-sensitive operations (including reference equality
 * ({@code ==}), identity hash code, or synchronization) on instances of
 * {@code OptionalUI} may have unpredictable results and should be avoided.
 * <p>
 * Note that
 * {@code 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 {@code null} as well
 * as expose the UI components to the application thread directly
 * is likely to cause errors. A variable whose type is {@code OptionalUI} should
 * never itself be {@code null}; it should always point to an {@code OptionalUI}
 * instance.
 *  <p>
 *  <b>Please take a look at the <a href="https://globaltcad.github.io/swing-tree/">living swing-tree documentation</a>
 *  where you can browse a large collection of examples demonstrating how to use the API of this class.</b>
 *
 * @param <C> the type of component held by this instance
 */
public final class OptionalUI<C extends Component> {

    private static final Logger log = LoggerFactory.getLogger(OptionalUI.class);

    /**
     * Common instance for {@code empty()}.
     */
    private static final OptionalUI<?> EMPTY = new OptionalUI<>(null);

    /**
     * If non-null, the value; if null, indicates no value is present
     */
    private final @Nullable C _component;

    /**
     * Returns an empty {@code OptionalUI} instance.  No value is present for this
     * {@code OptionalUI}.
     *
     * @apiNote
     * Though it may be tempting to do so, avoid testing if an object is empty
     * by comparing with {@code ==} against instances returned by
     * {@code OptionalUI.empty()}.  There is no guarantee that it is a singleton.
     * Instead, use {@link #isPresent()}.
     *
     * @param <T> The type of the non-existent value
     * @return an empty {@code OptionalUI}
     */
    static<T extends Component> OptionalUI<T> empty() {
        @SuppressWarnings("unchecked")
        OptionalUI<T> t = (OptionalUI<T>) EMPTY;
        return t;
    }

    /**
     * Constructs an instance with the described value.
     *
     * @param value the value to describe; it's the caller's responsibility to
     *        ensure the value is non-{@code null} unless creating the singleton
     *        instance returned by {@code empty()}.
     */
    private OptionalUI( @Nullable C value ) { this._component = value; }

    /**
     * Returns an {@code OptionalUI} describing the given value, if
     * non-{@code null}, otherwise returns an empty {@code OptionalUI}.
     *
     * @param component the possibly-{@code null} value to describe
     * @param <T> the type of the value
     * @return an {@code OptionalUI} with a present value if the specified value
     *         is non-{@code null}, otherwise an empty {@code OptionalUI}
     */
    @SuppressWarnings("unchecked")
    static <T extends Component> OptionalUI<T> ofNullable(@Nullable T component) {
        return component == null ? (OptionalUI<T>) EMPTY
                : new OptionalUI<>(component);
    }

    /**
     * If a component is present, returns {@code true}, otherwise {@code false}.
     *
     * @return {@code true} if a component is present, otherwise {@code false}
     */
    public boolean isPresent() { return _component != null; }

    /**
     * If a component is  not present, returns {@code true}, otherwise
     * {@code false}.
     *
     * @return  {@code true} if a component is not present, otherwise {@code false}
     */
    public boolean isEmpty() { return _component == null; }

    /**
     * If a component is present, performs the given action with the component,
     * otherwise does nothing.
     *
     * @param action the action to be performed, if a component is present
     * @throws NullPointerException if component is present and the given action is
     *         {@code null}
     */
    public void ifPresent( Consumer<? super C> action ) {
        if ( _component != null )
            UI.run(() -> action.accept(_component));
    }

    /**
     * If a component is present, performs the given action with the component,
     * otherwise performs the given empty-based action.
     *
     * @param action the action to be performed, if a component is present
     * @param 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 {@code null}, or no component is present and the given empty-based
     *         action is {@code null}.
     */
    public void ifPresentOrElse( Consumer<? super C> action, Runnable emptyAction ) {
        UI.run(()->{
            try {
                if (_component != null)
                    action.accept(_component);
                else
                    emptyAction.run();
            } catch (Exception e) {
                log.error("Error performing action on UI component of OptionalUI instance.", e);
            }
        });
    }

    /**
     * If a component is present, and the component matches the given predicate,
     * returns an {@code OptionalUI} describing the component, otherwise returns an
     * empty {@code OptionalUI}.
     *
     * @param predicate the predicate to apply to a component, if present
     * @return an {@code OptionalUI} describing the component of this
     *         {@code OptionalUI}, if a component is present and the component matches the
     *         given predicate, otherwise an empty {@code OptionalUI}
     * @throws NullPointerException if the predicate is {@code null}
     */
    public OptionalUI<C> filter(Predicate<? super C> predicate) {
        Objects.requireNonNull(predicate);
        if (!isPresent()) {
            return this;
        } else {
            try {
                if (!UI.thisIsUIThread()) {
                    try {
                        return UI.runAndGet(() -> filter(predicate));
                    } catch (Exception e) {
                        throw new RuntimeException(e);
                    }
                } else
                    return predicate.test(_component) ? this : empty();
            } catch (Exception e) {
                log.error(
                    "Error filtering UI component of OptionalUI instance. " +
                    "Returning current OptionalUI instance instead.",
                    e
                );
            }
        }
        return this;
    }

    /**
     * If a component is present, returns an {@code OptionalUI} describing (as if by
     * {@link #ofNullable}) the result of applying the given mapping function to
     * the component, otherwise returns an empty {@code OptionalUI}.
     *
     * <p>If the mapping function returns a {@code null} result then this method
     * returns an empty {@code OptionalUI}.
     *
     * @param mapper the mapping function to apply to a component, if present
     * @param <U> The type of the component returned from the mapping function
     * @return an {@code Optional} describing the result of applying a mapping
     *         function to the UI component of this {@code OptionalUI}, if a component is
     *         present, otherwise an empty {@code OptionalUI}
     * @throws NullPointerException if the mapping function is {@code null}
     */
    public <U> Optional<U> map( Function<? super C, ? extends U> mapper ) {
        Objects.requireNonNull(mapper);
        if ( !this.isPresent() ) return Optional.empty();
        else {
            try {
                if (UI.thisIsUIThread())
                    return Optional.ofNullable(mapper.apply(_component));
                else {
                    try {
                        Optional<U> opt = UI.runAndGet(() -> map(mapper));
                        if (opt.isPresent() && (opt.get() instanceof Component || opt.get() instanceof UIForAnySwing))
                            throw new RuntimeException("A Swing component may not leak to another thread!");
                        else return opt;
                    } catch (Exception ex) {
                        throw new RuntimeException(ex);
                    }
                }
            } catch (Exception ex) {
                log.error(
                    "Error mapping OptionalUI to Optional instance! " +
                    "Returning current OptionalUI instance instead.",
                    ex
                );
            }
        }
        return Optional.empty();
    }

    /**
     *  An alternative to {@link #map(Function)} that maps to the same type in yet another
     *  {@code OptionalUI} instance. This is useful for chaining UI centric operations.
     *  The mapping function should return an {@code OptionalUI} instance.
     *
     * @param mapper The mapping function to apply to a component, if present.
     * @return an {@code OptionalUI} describing the result of applying a mapping
     *         function to the UI component of this {@code OptionalUI}, if a component is
     *         present, otherwise an empty {@code OptionalUI}
     * @throws NullPointerException if the mapping function is {@code null}
     */
    public OptionalUI<C> update( Function<C, C> mapper ) {
        Objects.requireNonNull(mapper);
        if ( !this.isPresent() ) return this;
        else {
            try {
                if (UI.thisIsUIThread())
                    return OptionalUI.ofNullable(mapper.apply(_component));
                else {
                    try {
                        return UI.runAndGet(() -> update(mapper));
                    } catch (Exception ex) {
                        throw new RuntimeException(ex);
                    }
                }
            } catch (Exception ex) {
                log.error(
                    "Error creating an updated OptionalUI instance! " +
                    "Returning current OptionalUI instance instead.",
                    ex
                );
            }
            return this;
        }
    }

    /**
     *  An alternative to {@link #update(Function)} and {@link #map(Function)} that maps to
     *  the same type in yet another {@code OptionalUI} instance but with the
     *  difference that the mapping function is only applied if the component is
     *  present <b>and assignable to the given type</b>. <br>
     *  It is a type conditional mapping operation.
     *
     * @param type The type to check if the component is assignable to.
     * @param mapper The mapping function to apply to a component of the given type, if present.
     * @return An {@code OptionalUI} describing the result of applying a mapping
     *        function to the UI component of this {@code OptionalUI}, if a component is
     *        present and the component is assignable to the given type, otherwise an
     *        empty {@code OptionalUI}.
     * @param <U> The type of the component returned from the mapping function.
     * @throws NullPointerException if the mapping function is {@code null}
     * @throws NullPointerException if the given type is {@code null}
     */
    public <U extends C> OptionalUI<C> updateIf(Class<U> type, Function<U, U> mapper) {
        Objects.requireNonNull(type);
        Objects.requireNonNull(mapper);
        if ( !this.isPresent() ) return this;
        else {
            try {
                if (UI.thisIsUIThread()) {
                    Objects.requireNonNull(_component);
                    // Check if the component is assignable to the given type
                    if (type.isAssignableFrom(_component.getClass())) {
                        @SuppressWarnings("unchecked")
                        U u = (U) _component;
                        return OptionalUI.ofNullable(mapper.apply(u));
                    } else {
                        return this;
                    }
                } else {
                    try {
                        return UI.runAndGet(() -> updateIf(type, mapper));
                    } catch (Exception ex) {
                        throw new RuntimeException(ex);
                    }
                }
            } catch (Exception ex) {
                log.error(
                    "Error creating an updated OptionalUI instance! " +
                    "Returning current OptionalUI instance instead.",
                    ex
                );
            }
        }
        return this;
    }

    /**
     *  An alternative to {@link #update(Function)} and {@link #map(Function)} that maps to
     *  the same type in yet another {@code OptionalUI} instance but with the
     *  difference that the mapping function is only applied if the component is
     *  present <b>and the supplied boolean is true</b>. <br>
     *  It is a conditional mapping operation.
     *
     * @param condition The boolean to check before applying the mapping function.
     * @param mapper The mapping function to apply to a component, if present and the condition is true.
     * @return An {@code OptionalUI} describing the result of applying a mapping
     *        function to the UI component of this {@code OptionalUI}, if a component is
     *        present and the condition is true, otherwise an empty {@code OptionalUI}.
     * @throws NullPointerException if the mapping function is {@code null}
     */
    public OptionalUI<C> updateIf( boolean condition, Function<C, C> mapper ) {
        Objects.requireNonNull(mapper);
        if ( !condition ) return this;
        else
            return update(mapper);
    }

    /**
     * If a component is present, returns an {@code OptionalUI} describing the component,
     * otherwise returns an {@code OptionalUI} produced by the supplying function.
     * Use this to provide alternative UI components.
     *
     * @param supplier the supplying function that produces an {@code OptionalUI}
     *        to be returned
     * @return returns an {@code OptionalUI} describing the component of this
     *         {@code OptionalUI}, if a component is present, otherwise an
     *         {@code OptionalUI} produced by the supplying function.
     * @throws NullPointerException if the supplying function is {@code null} or
     *         produces a {@code null} result
     */
    public OptionalUI<C> or( Supplier<? extends OptionalUI<? extends C>> supplier ) {
        Objects.requireNonNull(supplier);
        if ( this.isPresent() ) return this;
        else {
            try {
                @SuppressWarnings("unchecked")
                OptionalUI<C> r = (OptionalUI<C>) supplier.get();
                return Objects.requireNonNull(r);
            } catch (Exception e) {
                log.error(
                    "Error creating fetching alternative OptionalUI instance! " +
                    "Returning current OptionalUI instead.",
                    e
                );
            }
        }
        return this;
    }

    /**
     * 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 {@code OptionalUI} containing the current component
     * and the supplying function is not called.
     * Use this to define alternative UI components.
     *
     * @param supplier the supplying function that produces a UI component to be
     *                 used if no component is present.
     * @return returns an {@code OptionalUI} describing the component of this
     *         {@code OptionalUI}, if a component is present, otherwise an
     *         {@code OptionalUI} produced by the supplying function.
     * @throws NullPointerException if the supplying function is {@code null} or
     *         produces a {@code null} result
     */
    public OptionalUI<C> orGet( Supplier<? extends C> supplier ) {
        Objects.requireNonNull(supplier);
        if ( this.isPresent() ) return this;
        else {
            try {
                C c = supplier.get();
                return OptionalUI.ofNullable(c);
            } catch (Exception e) {
                log.error(
                    "Error creating fetching alternative UI component! " +
                    "Returning current OptionalUI instead.",
                    e
                );
            }
        }
        return this;
    }

    /**
     * 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 {@code OptionalUI} containing the current component
     * and the supplying function is not called.
     * Use this to define alternative UI components if a condition is met.
     *
     * @param condition The boolean condition to check before calling the supplying function.
     *                  If false, the supplying function is simply ignored.
     * @param supplier the supplying function that produces a UI component to be
     *                 used if no component is present.
     * @return returns an {@code OptionalUI} describing the component of this
     *         {@code OptionalUI}, if a component is present, otherwise an
     *         {@code OptionalUI} produced by the supplying function.
     * @throws NullPointerException if the supplying function is {@code null} or
     *         produces a {@code null} result
     */
    public OptionalUI<C> orGetIf( boolean condition, Supplier<? extends C> supplier ) {
        Objects.requireNonNull(supplier);
        if ( !condition )
            return this;
        else
            if ( this.isPresent() )
                return this;
        else
        {
            try {
                C c = supplier.get();
                return OptionalUI.ofNullable(c);
            } catch (Exception e) {
                log.error(
                    "Error creating fetching alternative UI component! " +
                    "Returning current OptionalUI instead.",
                    e
                );
            }
        }
        return this;
    }

    /**
     * If a component is present, returns an {@code OptionalUI} describing the component,
     * otherwise returns a {@code OptionalUI} containing the component built by the UI declaration
     * inside the supplying function.
     * Use this to provide alternative UI components.
     *
     * @param <A> The type of the component to be built.
     * @param <B> The base type of the component to be built.
     * @param supplier the supplying function that produces a UI declaration
     *                 to be used if no component is present.
     * @return returns an {@code OptionalUI} describing the component of this
     *         {@code OptionalUI}, if a component is present, otherwise an
     *         {@code OptionalUI} produced by the supplying function.
     * @throws NullPointerException if the supplying function is {@code null} or
     *         produces a {@code null} result
     */
    public <A extends B, B extends C> OptionalUI<C> orGetUi( Supplier<UIForAnything<?,A,B>> supplier ) {
        Objects.requireNonNull(supplier);
        if ( this.isPresent() ) return this;
        else {
            try {
                UIForAnything<?, A, B> ui = supplier.get();
                return OptionalUI.ofNullable(ui.get(ui.getType()));
            } catch (Exception e) {
                log.error(
                    "Error creating fetching alternative UI component! " +
                    "Returning current OptionalUI instead.",
                    e
                );
            }
        }
        return this;
    }

    /**
     * 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 {@code OptionalUI} and the supplying function is not called.
     * Use this to define alternative UI declaration if a condition is met.
     *
     * @param <A> The type of the component to be built.
     * @param <B> The base type of the component to be built.
     * @param condition The boolean condition to check before calling the supplying function.
     *                  If false, the supplying function is simply ignored.
     * @param supplier the supplying function that produces a UI declaration
     *                 to be used if no component is present.
     * @return returns an {@code OptionalUI} describing the component of this
     *         {@code OptionalUI}, if a component is present, otherwise an
     *         {@code OptionalUI} produced by the supplying function.
     * @throws NullPointerException if the supplying function is {@code null} or
     *         produces a {@code null} result
     */
    public <A extends B, B extends C> OptionalUI<C> orGetUiIf( boolean condition, Supplier<UIForAnything<?,A,B>> supplier ) {
        Objects.requireNonNull(supplier);
        if ( !condition )
            return this;
        else
            if ( this.isPresent() )
                return this;
        else
        {
            try {
                UIForAnything<?, A, B> ui = supplier.get();
                return OptionalUI.ofNullable(ui.get(ui.getType()));
            } catch (Exception e) {
                log.error(
                    "Error creating fetching alternative UI component! " +
                    "Returning current OptionalUI instead.",
                    e
                );
            }
        }
        return this;
    }

    /**
     * If a component is present, returns the component, otherwise returns
     * {@code other} or throws a null pointer exception if {@code other} is
     * {@code null}.
     *
     * @param other the component to be returned, if no component is present.
     *        May not be {@code null}.
     * @return the component, if present, otherwise {@code other}
     */
    public @Nullable C orElseNullable( @Nullable C other ) {
        if ( !UI.thisIsUIThread() )
            throw new RuntimeException("The UI component may only be accessed by the UI thread!");
        return _component != null ? _component : other;
    }

    /**
     * If a component is present, returns the component, otherwise returns
     * {@code other}.
     *
     * @param other the component to be returned, if no component is present.
     *        May not be {@code null}, use {@link #orElseNullable(Component)} if it can be null.
     * @return the component, if present, otherwise {@code other}
     */
    public C orElse( @NonNull C other ) {
        if ( !UI.thisIsUIThread() )
            throw new RuntimeException("The UI component may only be accessed by the UI thread!");
        Objects.requireNonNull(other);
        return _component != null ? _component : other;
    }

    /**
     *  If a component is present, returns the component, otherwise returns {@code null}.
     *
     * @return The component wrapped in this OptionalUI, or null if no component is present.
     */
    public @Nullable C orNull() {
        if ( !UI.thisIsUIThread() )
            throw new RuntimeException("The UI component may only be accessed by the UI thread!");
        return _component;
    }

    /**
     * If a component is present, returns the component, otherwise returns the result
     * produced by the supplying function.
     *
     * @param supplier the supplying function that produces a component to be returned
     * @return the component, if present, otherwise the result produced by the
     *         supplying function
     * @throws NullPointerException if no component is present and the supplying
     *         function is {@code null}
     */
    public C orElseGet(Supplier<? extends C> supplier) {
        if ( !UI.thisIsUIThread() )
            throw new RuntimeException("The UI component may only be accessed by the UI thread!");
        return _component != null ? _component : supplier.get();
    }

    /**
     * If a component is present, returns the component, otherwise throws
     * {@code NoSuchElementException}.
     *
     * @return the non-{@code null} component described by this {@code OptionalUI}
     * @throws NoSuchElementException if no component is present
     */
    public C orElseThrow() {
        if ( !UI.thisIsUIThread() )
            throw new RuntimeException("The UI component may only be accessed by the UI thread!");
        if ( _component == null )
            throw new NoSuchElementException("No component present");

        return _component;
    }

    /**
     * If a component is present, returns the component, otherwise throws an exception
     * produced by the exception supplying function.
     * <p>
     * Note that
     * A method reference to the exception constructor with an empty argument
     * list can be used as the supplier. For example,
     * {@code IllegalStateException::new}
     *
     * @param <X> Type of the exception to be thrown
     * @param exceptionSupplier the supplying function that produces an
     *        exception to be thrown
     * @return the component, if present
     * @throws X if no component is present
     * @throws NullPointerException if no component is present and the exception
     *          supplying function is {@code null}
     */
    public <X extends Throwable> C orElseThrow(Supplier<? extends X> exceptionSupplier) throws X {
        if ( !UI.thisIsUIThread() )
            throw new RuntimeException("The UI component may only be accessed by the UI thread!");
        if (_component != null) {
            return _component;
        } else {
            throw exceptionSupplier.get();
        }
    }

    /**
     * Indicates whether some other object is "equal to" this {@code OptionalUI}.
     * The other object is considered equal if:
     * <ul>
     * <li>it is also an {@code OptionalUI} and;
     * <li>both instances have no component present or;
     * <li>the present components are "equal to" each other via {@code equals()}.
     * </ul>
     *
     * @param obj an object to be tested for equality
     * @return {@code true} if the other object is "equal to" this object
     *         otherwise {@code false}
     */
    @Override
    public boolean equals( Object obj ) {
        if ( this == obj ) return true;
        if ( !(obj instanceof OptionalUI) ) return false;
        OptionalUI<?> other = (OptionalUI<?>) obj;
        return Objects.equals(_component, other._component);
    }

    /**
     * Returns the hash code of the component, if present, otherwise {@code 0}
     * (zero) if no component is present.
     *
     * @return hash code component of the present component or {@code 0} if no component is
     *         present
     */
    @Override
    public int hashCode() { return Objects.hashCode(_component); }

    /**
     * Returns a non-empty string representation of this {@code OptionalUI}
     * suitable for debugging.  The exact presentation format is unspecified and
     * may vary between implementations and versions.
     * <p>
     * If a component is present the result must include its string representation
     * in the result.  Empty and present {@code OptionalUI}s must be unambiguously
     * differentiable.
     *
     * @return the string representation of this instance
     */
    @Override
    public String toString() {
        return _component != null
                ? String.format("OptionalUI[%s]", _component)
                : "OptionalUI.empty";
    }

}