com.bluecatcode.common.base.Either Maven / Gradle / Ivy

package com.bluecatcode.common.base;

import com.google.common.base.Function;

import javax.annotation.CheckReturnValue;
import javax.annotation.Nullable;
import java.io.Serializable;

import static com.bluecatcode.common.contract.Preconditions.require;

/**
 * Represents a value of one of two possible types (a disjoint union).
 * Instances of {@code Either} are either an instance of {@code Left} or {@code Right}.
 * 
 * Either is an algebraic data type similar to the {@link com.google.common.base.Optional}.
 * 

 * A common use of {@code Either} is as an alternative to {@code Optional} for dealing with possible missing values.
 * In this usage, {@code Absent} is replaced with a {@code Left} which can contain useful information.
 * {@code Right} takes the place of {@code Present}.
 * Convention dictates that {@code Left} is used for failure and {@code Right} is used for success.
 * 

 * A non-null {@code Either} reference can be used as an alternative to the classic error handling (exceptions).
 * 

 * 
 *  public static Either divide(int x, int y) {
 *    try {
 *      return Either.valueOf(x / y);
 *    } catch (Exception e) {
 *      return Either.errorOf(e);
 *    }
 *  }
 * 
 *
 * @param  the type of left instance that can be contained.
 * @param  the type of right instance that can be contained.
 * @since 1.0.5
 */
@CheckReturnValue
public abstract class Either implements Serializable {

    private static final long serialVersionUID = 0;

    Either() {
        /* Empty */
    }

    /**
     * Same as {@link #rightOf}, a convenience method for Value/Error use case.
     */
    public static  Either valueOf(R reference) {
        return rightOf(reference);
    }

    /**
     * Same as {@link #leftOf}, a convenience method for Value/Error use case.
     */
    public static  Either errorOf(L reference) {
        return leftOf(reference);
    }

    /**
     * Returns an {@code Either} instance containing the given non-null reference.
     *
     * @throws NullPointerException if {@code reference} is null
     */
    public static  Either leftOf(L reference) {
        require(reference != null, "Expected non-null reference");
        return new Left<>(reference);
    }

    /**
     * Returns an {@code Either} instance containing the given non-null reference.
     *
     * @throws NullPointerException if {@code reference} is null
     */
    public static  Either rightOf(R reference) {
        require(reference != null, "Expected non-null reference");
        return new Right<>(reference);
    }

    /**
     * Same as {@link #isRight()}, a convenience method for Value/Error use case.
     */
    public boolean isValue() {
        return isRight();
    }

    /**
     * Same as {@link #isLeft}, a convenience method for Value/Error use case.
     */
    public boolean isError() {
        return isLeft();
    }

    /**
     * @return true if this is a Left, false otherwise.
     */
    public abstract boolean isLeft();

    /**
     * @return true if this is a Right, false otherwise.
     */
    public abstract boolean isRight();

    /**
     * Same as {@link #right()}, a convenience method for Value/Error use case.
     */
    public R value() {
        return right();
    }

    /**
     * Same as {@link #left()}, a convenience method for Value/Error use case.
     */
    public L error() {
        return left();
    }

    /**
     * Returns the contained instance, which must be present.
     *
     * @throws IllegalStateException if the instance is absent ({@link #isLeft()} returns
     *                               {@code false}); depending on this specific exception type (over the more general
     *                               {@link RuntimeException}) is discouraged
     */
    public abstract L left();

    /**
     * Returns the contained instance, which must be present.
     *
     * @throws IllegalStateException if the instance is absent ({@link #isRight()} returns
     *                               {@code false}); depending on this specific exception type (over the more general
     *                               {@link RuntimeException}) is discouraged
     */
    public abstract R right();

    /**
     * Returns this {@code Either} if it has the right value present; {@code secondChoice} otherwise.
     */
    public abstract Either or(Either secondChoice);

    /**
     * Returns the left instance if it is present; {@code throw leftFunction.apply(left())} otherwise.
     *
     * @throws NullPointerException if right value is absent and the function returns {@code null}
     */
    public abstract  R orThrow(Function leftFunction) throws E;

    /**
     * Applies {@code leftFunction} if this is a Left or {@code rightFunction if this is a Right.
     *
     * @return the result of the {@code function}.
     * @throws NullPointerException if the function returns {@code null}
     */
    public abstract  V either(Function leftFunction, Function rightFunction);

    /**
     * Applies {@code leftFunction} if this is a Left or {@code rightFunction if this is a Right.
     *
     * @return the result of the {@code function}.
     * @throws NullPointerException if the function returns {@code null}
     */
    public abstract  Either transform(Function leftFunction, Function rightFunction);

    /**
     * If this is a Left, then return the left value in Right or vice versa.
     *
     * @return a new {@code Either}
     */
    public abstract Either swap();

    /**
     * Returns {@code true} if {@code object} is an {@code Either} instance, and either
     * the contained references are {@linkplain Object#equals equal} to each other.
     * Note that {@code Either} instances of differing parameterized types can
     * be equal.
     */
    @Override
    public abstract boolean equals(@Nullable Object object);

    /**
     * Returns a hash code for this instance.
     */
    @Override
    public abstract int hashCode();

    /**
     * Returns a string representation for this instance.
     */
    @Override
    public abstract String toString();
}