io.vlingo.common.Outcome Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of vlingo-common Show documentation
These are just a few common tools shared across various vlingo projects.
There is a newer version: 1.7.5
// Copyright © 2012-2020 VLINGO LABS. All rights reserved.
//
// This Source Code Form is subject to the terms of the
// Mozilla Public License, v. 2.0. If a copy of the MPL
// was not distributed with this file, You can obtain
// one at https://mozilla.org/MPL/2.0/.

package io.vlingo.common;

import java.util.NoSuchElementException;
import java.util.Optional;
import java.util.function.Consumer;
import java.util.function.Function;

/**
 * Represents a outcome of a process that can fail with an unexpected exception. Outcomes can be
 * mapped and composed safely, converted to Java standard Optional, to null and to a vlingo Completes.
 *
 * @param  Type of an unexpected exception.
 * @param  Type of expected value.
 */
public interface Outcome {
    /**
     * Maps a success value to the next success value.
     *
     * For example:
     *
     * 
     *     Success.of(42).andThen(v -> v + 8).get() // 50
     * 
     *
     * In case that the outcome is failure, nothing will happen.
     *
     * @param action Function to apply to the current value
     * @param  Result of the current value
     * @return A successful Outcome with the new value, or a Failure outcome.
     */
    
    Outcome andThen(final Function action);

    /**
     * Maps a success Outcome value to a function that returns a new Outcome, that can be
     * either successful or failure.
     *
     * @param action Function to apply to the current value
     * @param  the type of the outcome on failure
     * @param  the type of the outcome on success
     * @return The mapped Outcome
     */
    
    Outcome andThenTo(final Function> action);

    /**
     * Consumes eventually the successful outcome.
     * @param consumer A consumer function that processes the outcome.
     */
    void atLeastConsume(final Consumer consumer);

    /**
     * Maps a failure outcome to a successful outcome, for recovery.
     *
     * @param action function to apply to the current value
     * @return A successful outcome.
     */
    Outcome otherwise(final Function action);

    /**
     * Maps a failure outcome to a new outcome.
     *
     * @param action function to apply to current value
     * @param  the type of the outcome on failure
     * @param  the type of the outcome on success
     * @return The mapped outcome.
     */
    
    Outcome otherwiseTo(final Function> action);

    /**
     * @return The success outcome value
     * @throws FailureT in case that the outcome is a failure
     */
    SuccessT get() throws FailureT;

    /**
     *
     * @return The success outcome value or null in case of a failure
     */
    SuccessT getOrNull();

    /**
     * Resolves the outcome and returns the mapped value.
     *
     * For example:
     *
     * 
     *     Failure.of(exception).resolve(f -> 42, s -@gtl  1) // == 42
     *     Success.of(value).resolve(f -@gt; 42, s -@gt;  1) // == 1
     * 
     *
     * @param onFailedOutcome A mapping function from a failure to a success outcome
     * @param onSuccessfulOutcome A mapping function from a success outcome to another success outcome
     * @param  the type of the next success
     * @return The mapped value
     */
    
    NextSuccessT resolve(
            final Function onFailedOutcome,
            final Function onSuccessfulOutcome
    );

    /**
     *
     * @return A Java optional with the success value, or Optional.empty() in case of failure
     */
    Optional asOptional();

    /**
     *
     * @return A vlingo Completes with the success value, or a failed Completes n case of failure
     */
    Completes asCompletes();

    /**
     * Applies a filter predicate to the success value, or returns a failed Outcome in case
     * of not fulfilling the predicate.
     *
     * @param filterFunction the filter function
     * @return The filtered outcome
     */
    Outcome filter(final Function filterFunction);

    /**
     * Returns a Outcome of a tuple of successes, or the first Failure in case of any of the failed outcomes.
     *
     * @param outcome the outcome
     * @param  the type of the second success
     * @return a Outcome of a tuple of successes, or the first Failure in case of any of the failed outcomes
     */
    
    Outcome> alongWith(final Outcome outcome);

    /**
     * Maps a failed outcome to another failed outcome.
     *
     * @param action the function to map a failed outcome to another failed outcome
     * @param  the type of the next falure
     * @return The new failed outcome
     */
    
    Outcome otherwiseFail(Function action);
}