Class ValueWithFailures<T>

  • Type Parameters:
    T - the type of the underlying success value, typically a collection type
    All Implemented Interfaces:
    java.io.Serializable, Bean, ImmutableBean

    public final class ValueWithFailures<T>
    extends java.lang.Object
    implements ImmutableBean, java.io.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,
                                                  java.util.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 emptyValue,
                                                  java.util.function.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.

        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
      • toValueWithFailures

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

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

        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
      • hasFailures

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

        public <R> ValueWithFailures<R> map​(java.util.function.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.

        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
      • flatMap

        public <R> ValueWithFailures<R> flatMap​(java.util.function.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.

        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,
                                                             java.util.function.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.

        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
      • 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​(java.lang.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 com.google.common.collect.ImmutableList<FailureItem> getFailures()
        Gets the failure items.
        Returns:
        the value of the property, not null
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object