Package com.opengamma.strata.collect.result

Class ValueWithFailures<T>

  • Type Parameters:
    T - the type of the underlying success value, typically a collection type
    All Implemented Interfaces:
    Serializable, org.joda.beans.Bean, org.joda.beans.ImmutableBean
    public final class ValueWithFailures<T>
extends Object
implements org.joda.beans.ImmutableBean, Serializable
    A value with associated failures.

    This captures a common use case where an operation can tolerate some failure. This is often referred to as partial success or partial failure. The class stores the value, of any object type, and a list of failures that may be empty.

    The success value must be able to handle the case where everything fails. In most cases, the success value will be a collection type, such as List or Map, which can be empty if the operation failed completely.

    The classic example is loading rows from a file, when some rows are valid and some are invalid. The partial result would contain the successful rows, with the list of failures containing an entry for each row that failed to parse.

    See Also:
    Serialized Form

    • Method Detail

      • of

        public static <T> ValueWithFailures<T> of​(T successValue,
                                          FailureItem... failures)
        Creates an instance wrapping the success value and failures.
        Type Parameters:
        T - the type of the success value
        Parameters:
        successValue - the success value
        failures - the failures
        Returns:
        an instance wrapping the value and failures

      • of

        public static <T> ValueWithFailures<T> of​(T successValue,
                                          List<FailureItem> failures)
        Creates an instance wrapping the success value and failures.
        Type Parameters:
        T - the type of the success value
        Parameters:
        successValue - the success value
        failures - the failures
        Returns:
        an instance wrapping the value and failures

      • of

        public static <T> ValueWithFailures<T> of​(T successValue,
                                          Collection<FailureItem> failures)
        Creates an instance wrapping the success value and failures.
        Type Parameters:
        T - the type of the success value
        Parameters:
        successValue - the success value
        failures - the failures
        Returns:
        an instance wrapping the value and failures

      • of

        public static <T> ValueWithFailures<T> of​(T emptyValue,
                                          Supplier<T> supplier)
        Creates an instance using a supplier.

        If the supplier succeeds normally, the supplied value will be returned. If the supplier fails, the empty value will be returned along with a failure.

        This recognizes and handles FailureItemProvider exceptions. If the exception type is not recognized, the failure item will have a reason of ERROR.

        Type Parameters:
        T - the type of the value
        Parameters:
        emptyValue - the empty value
        supplier - supplier of the result value
        Returns:
        an instance containing the supplied value, or a failure if an exception is thrown

      • combiningValues

        public static <T> BinaryOperator<ValueWithFailures<T>> combiningValues​(BinaryOperator<T> combiner)
        Returns a BinaryOperator that combines ValueWithFailures objects using the provided combiner function.

        This would be used as follows (with a static import): 

           stream.reduce(combiningValues(Guavate::concatToList));

   stream.reduce(baseValueWithFailures, combiningValues(Guavate::concatToList));

        This replaces code of the form: 

           stream.reduce((vwf1, vwf2) -> vwf1.combinedWith(vwf2, Guavate::concatToList));

   stream.reduce(baseValueWithFailures, (vwf1, vwf2) -> vwf1.combinedWith(vwf2, Guavate::concatToList));
        Type Parameters:
        T - the type of the values
        Parameters:
        combiner - the combiner of the values
        Returns:
        the combining binary operator

      • toValueWithFailures

        public static <T> Collector<ValueWithFailures<T>,​?,​ValueWithFailures<T>> toValueWithFailures​(T identityValue,
                                                                                                         BinaryOperator<T> operator)
        Returns a collector that can be used to create a combined ValueWithFailure from a stream of separate instances.

        The Collector returned performs a reduction of its ValueWithFailures input elements under a specified BinaryOperator using the provided identity.

        This collects a Stream<ValueWithFailures<T>> to a ValueWithFailures<T>.

        Type Parameters:
        T - the type of the success value in the ValueWithFailures
        Parameters:
        identityValue - the identity value
        operator - the operator used for the reduction.
        Returns:
        a Collector

      • toCombinedValuesAsList

        public static <T> Collector<ValueWithFailures<? extends T>,​?,​ValueWithFailures<List<T>>> toCombinedValuesAsList()
        Returns a collector that creates a combined ValueWithFailure from a stream of separate instances, combining into an immutable list.

        This collects a Stream<ValueWithFailures<T>> to a ValueWithFailures<List<T>>.

        Type Parameters:
        T - the type of the success value in the ValueWithFailures
        Returns:
        a Collector

      • toCombinedValuesAsSet

        public static <T> Collector<ValueWithFailures<? extends T>,​?,​ValueWithFailures<Set<T>>> toCombinedValuesAsSet()
        Returns a collector that creates a combined ValueWithFailure from a stream of separate instances, combining into an immutable set.

        This collects a Stream<ValueWithFailures<T>> to a ValueWithFailures<Set<T>>.

        Type Parameters:
        T - the type of the success value in the ValueWithFailures
        Returns:
        a Collector

      • toCombinedResultsAsList

        public static <T> Collector<Result<? extends T>,​?,​ValueWithFailures<List<T>>> toCombinedResultsAsList()
        Returns a collector that can be used to create a combined ValueWithFailure from a stream of Result instances.

        This collects a Stream<Result<T>> to a ValueWithFailures<List<T>>.

        Type Parameters:
        T - the type of the success value in the ValueWithFailures
        Returns:
        a Collector

      • combineValuesAsList

        public static <T> ValueWithFailures<List<T>> combineValuesAsList​(Iterable<? extends ValueWithFailures<? extends T>> items)
        Combines separate instances of ValueWithFailure into a single instance, using a list to collect the values.

        This converts Iterable<ValueWithFailures<T>> to ValueWithFailures<List<T>>.

        Type Parameters:
        T - the type of the success value in the ValueWithFailures
        Parameters:
        items - the items to combine
        Returns:
        a new instance with a list of success values

      • combineValuesAsSet

        public static <T> ValueWithFailures<Set<T>> combineValuesAsSet​(Iterable<? extends ValueWithFailures<? extends T>> items)
        Combines separate instances of ValueWithFailure into a single instance, using a set to collect the values.

        This converts Iterable<ValueWithFailures<T>> to ValueWithFailures<Set<T>>.

        Type Parameters:
        T - the type of the success value in the ValueWithFailures
        Parameters:
        items - the items to combine
        Returns:
        a new instance with a set of success values

      • hasFailures

        public boolean hasFailures()
        Checks if there are any failures.
        Returns:
        true if there are any failures

      • map

        public <R> ValueWithFailures<R> map​(Function<? super T,​? extends R> function)
        Processes the value by applying a function that alters the value.

        This operation allows post-processing of a result value. The specified function represents a conversion to be performed on the value.

        It is strongly advised to ensure that the function cannot throw an exception. Exceptions from the function are not caught.

        Type Parameters:
        R - the type of the value in the returned result
        Parameters:
        function - the function to transform the value with
        Returns:
        the transformed instance of value and failures

      • mapFailures

        public ValueWithFailures<T> mapFailures​(Function<FailureItem,​FailureItem> function)
        Processes the value by applying a function that alters the failures.

        This operation allows post-processing of a result failures. The specified function represents a conversion to be performed on the failures.

        It is strongly advised to ensure that the function cannot throw an exception. Exceptions from the function are not caught.

        Parameters:
        function - the function to transform the failures with
        Returns:
        the transformed instance of value and failures

      • flatMap

        public <R> ValueWithFailures<R> flatMap​(Function<? super T,​ValueWithFailures<R>> function)
        Processes the value by applying a function that returns another result.

        This operation allows post-processing of a result value. This is similar to map(Function) but the function returns a ValueWithFailures. The result of this method consists of the transformed value, and the combined list of failures.

        It is strongly advised to ensure that the function cannot throw an exception. Exceptions from the function are not caught.

        Type Parameters:
        R - the type of the value in the returned result
        Parameters:
        function - the function to transform the value with
        Returns:
        the transformed instance of value and failures

      • combinedWith

        public <U,​R> ValueWithFailures<R> combinedWith​(ValueWithFailures<U> other,
                                                     BiFunction<T,​U,​R> combiner)
        Combines this instance with another.

        If both instances contain lists of the same type, the combining function will often be Guavate::concatToList.

        It is strongly advised to ensure that the function cannot throw an exception. Exceptions from the function are not caught.

        Type Parameters:
        U - the type of the value in the other instance
        R - the type of the value in the returned result
        Parameters:
        other - the other instance
        combiner - the function that combines the two values
        Returns:
        the combined instance of value and failures

      • withValue

        public <R> ValueWithFailures<R> withValue​(R value)
        Returns a new instance with the specified value, retaining the current failures.

        This can be useful as an inline alternative to map(Function).

        Type Parameters:
        R - the type of the value in the returned result
        Parameters:
        value - the new value
        Returns:
        the combined instance of value and failures

      • withValue

        public <R> ValueWithFailures<R> withValue​(R value,
                                          List<FailureItem> additionalFailures)
        Returns a new instance with the specified value, combining the failures.

        This can be useful as an inline alternative to flatMap(Function).

        Type Parameters:
        R - the type of the value in the returned result
        Parameters:
        value - the new value
        additionalFailures - the additional failures
        Returns:
        the combined instance of value and failures

      • withValue

        public <R> ValueWithFailures<R> withValue​(ValueWithFailures<R> valueWithFailures)
        Returns a new instance with the specified value, combining the failures.

        This can be useful as an inline alternative to flatMap(Function).

        Type Parameters:
        R - the type of the value in the returned result
        Parameters:
        valueWithFailures - the new value with failures
        Returns:
        the combined instance of value and failures

      • withAdditionalFailures

        public ValueWithFailures<T> withAdditionalFailures​(List<FailureItem> additionalFailures)
        Returns a new instance with the specified failures, retaining the current value.
        Parameters:
        additionalFailures - the additional failures
        Returns:
        the combined instance of value and failures

      • meta

        public static ValueWithFailures.Meta meta()
        The meta-bean for ValueWithFailures.
        Returns:
        the meta-bean, not null

      • metaValueWithFailures

        public static <R> ValueWithFailures.Meta<R> metaValueWithFailures​(Class<R> cls)
        The meta-bean for ValueWithFailures.
        Type Parameters:
        R - the bean's generic type
        Parameters:
        cls - the bean's generic type
        Returns:
        the meta-bean, not null

      • getValue

        public T getValue()
        Gets the success value.
        Returns:
        the value of the property, not null

      • getFailures

        public ImmutableList<FailureItem> getFailures()
        Gets the failure items.
        Returns:
        the value of the property, not null

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object