com.jongsoft.lang.control.Optional Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of language Show documentation
Java Language Extensions
The newest version!
/*
 * The MIT License
 *
 * Copyright 2016-2019 Jong Soft.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package com.jongsoft.lang.control;

import java.util.Objects;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Predicate;
import java.util.function.Supplier;

import com.jongsoft.lang.Value;
import com.jongsoft.lang.control.impl.Constants;

/**
 * The Optional provides a functional way to detect null values without null reference checks or complicated
 * logic throughout the code base.
 * 
 *     Usage of this Optional is advices as a return type rather then using null as it moves away the change
 *     of potential {@link NullPointerException} in the code calling the operation.
 * 
 *  {@code  // Sample usage of the Optional
 *     API.Option("one")
 *          .ifPresent(System.out::println)
 *          .orElse(() -> System.out.println("No value is present");
 * }
 *
 * @param  the type of entity contained in the Optional
 * @since 0.0.1
 */
public interface Optional extends Value {

    @Override
    Optional filter(Predicate predicate);

    /**
     * This method will provide the entity contained within the {@link Optional}, in case no entity
     * is present the {@link Supplier} is called to create the else situation.
     *
     * @param supplier  the supplier to create an entity of none is contained in the {@link Optional}
     * @return          either the contained entity or the created one using the {@link Supplier}
     */
    T getOrSupply(Supplier supplier);

    /**
     * This method will return the contained entity within the {@link Optional}, in case no entity
     * is present an exception will be thrown using the provided exceptionSupplier.
     *
     * @param exceptionSupplier     the {@link Supplier} used to create the {@link Throwable}
     * @param                    the type of the Throwable that will be thrown
     * @return                      the entity contained within the {@link Optional}
     * @throws X                    in case of no entity
     * @throws NullPointerException in case the exceptionSupplier was null
     */
     T getOrThrow(Supplier exceptionSupplier) throws X;

    /**
     * Execute the runner method if no entity is present in this wrapped object
     *
     * @param runner                the code to execute if nothing is present
     * @throws NullPointerException in case the runner is null
     * @return           the {@link OrElse} functionality, which enables processing in case of {@link #isPresent() }
     *                   being true.
     */
    default OrElse ifNotPresent(Runnable runner) {
        Objects.requireNonNull(runner, "Runner cannot be null");
        if (!isPresent()) {
            runner.run();
            return Constants.OR_ELSE_NOT_EMPTY;
        }

        return Constants.OR_ELSE_EMPTY;
    }

    /**
     * Throws an exception when no value is present in this value
     *
     * @param exceptionSupplier the supplier to create the exception
     * @param                the type of exception expected
     * @throws X                the exception thrown if no present element
     * @throws NullPointerException in case the exceptionSupplier is null
     * @return           the {@link OrElse} functionality, which enables processing in case of {@link #isPresent() }
     *                   being true.
     */
    default  OrElse ifNotPresent(Supplier exceptionSupplier) throws X {
        Objects.requireNonNull(exceptionSupplier, "Supplier of exceptions cannot be null");
        if (!isPresent()) {
            throw exceptionSupplier.get();
        }

        return Constants.OR_ELSE_EMPTY;
    }

    /**
     * Process the present element wrapped within using the provided {@link java.util.function.Consumer}.
     *
     * @param consumer   the method that will consume the element
     * @return           the {@link OrElse} functionality, which enables processing in case of {@link #isPresent() }
     *                   being false.
     */
    OrElse ifPresent(Consumer consumer);

    /**
     * Throw an exception if an element is present within. Otherwise it will return the {@link OrElse}.
     *
     * @param exceptionSupplier the supplier to create the exception
     * @param                the type of exception expected
     * @return                  the {@link OrElse} in case no element is present
     * @throws X                the exception thrown if a present element
     */
     OrElse ifPresent(Supplier exceptionSupplier) throws X;

    /**
     * Indicates if a value is present within the wrapper
     *
     * @return true if an element is present, otherwise false
     */
    boolean isPresent();

    @Override
    default boolean isSingleValued() {
        return true;
    }

    @Override
     Optional map(Function mapper);

    /**
     * The OrElse interface is an extension to the {@link com.jongsoft.lang.control.Optional} interface. This interface can be used to cascade behaviour
     * when an entity is or is not present in the wrapper.
     * 
     *     For example if the {@link com.jongsoft.lang.control.Optional} has no entity contained within then the OrElse can be used to throw an exception
     *     or run alternative logic.
     * 
     * Example:
     * {@code  API.Option(null)
     *      .ifPresent(System.out::println)
     *      .elseThrow(() -> new NullPointerException("No value present"))
     * }
     *
     * @since 0.0.1
     */
    interface OrElse {
        /**
         * This operation will run when the precondition of this OrElse is not met.
         *
         * @param runner    the code to be run when the else is running
         */
        default void elseRun(Runnable runner) {}

        /**
         * This operation will create an exception using the provided {@link Supplier} and throw it.
         *
         * @param exceptionSupplier the supplier to create the exception
         * @param                the type of exception
         * @throws X                the exception in case of an OrElse run
         */
        default  void elseThrow(Supplier exceptionSupplier) throws X {}

    }

}