Package net.groboclown.retval

Class ValueAccumulator<T>

  • All Implemented Interfaces:
    ProblemContainer

    public class ValueAccumulator<T>
extends java.lang.Object
implements ProblemContainer
    Allows for accumulating a list of values, some of which may have errors associated with them.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(RetNullable<T> res)
      Add a value into this accumulator if the return value is ok, otherwise add the problems.
      void add​(RetVal<T> res)
      Add a value into this accumulator if the return value is ok, otherwise add the problems.
      void add​(ValuedProblemContainer<T> res)
      Add a value into this accumulator if the return value is ok, otherwise add the problems.
      void addAll​(java.lang.Iterable<ValuedProblemContainer<T>> values)
      Add a list of values into this accumulator.
      void addAllValues​(java.lang.Iterable<T> values)
      Add vararg list of values into this accumulator.
      void addValue​(T value)
      Add vararg list of values into this accumulator.
      java.util.Collection<Problem> anyProblems​()
      Return all the problems in this object, even if the container is "ok".
      RetVal<java.util.Collection<T>> asRetVal​()
      Returns the accumulated values as a RetVal if there are no problems, otherwise the enclosed problems.
      RetVal<java.util.List<T>> asRetValList​()
      Return the value as an unmodifiable List, rather than as a generic Collection.
      WarningVal<java.util.Collection<T>> asWarning​()
      Return this accumulator as a warning value, containing both all collected values (up to this point) and discovered problems.
      java.lang.String debugProblems​(java.lang.String joinedWith)
      Return the problems as a single string, which combines the Object.toString() output of each problem with the given joining string parameter.
      static <T> ValueAccumulator<T> from​()
      Create a new, empty value accumulator instance.
      static <T> ValueAccumulator<T> from​(Problem problem, Problem... problems)
      Create a new value accumulator that starts with the given problem(s).
      static <T> ValueAccumulator<T> from​(RetNullable<T> value)
      Create a new value accumulator that starts with the given value or problems.
      static <T> ValueAccumulator<T> from​(RetVal<T> value)
      Create a new value accumulator that starts with the given value or problems.
      ProblemCollector getCollector​()
      Get the underlying collector object, for adding arbitrary problems to the accumulator.
      java.util.Collection<T> getValues​()
      Get all valid values collected so far, even if there are also problems.
      boolean hasProblems​()
      Returns whether this object contains 1 or more problems.
      boolean isOk​()
      Returns whether this object contains zero problems.
      boolean isProblem​()
      Returns whether this object contains 1 or more problems.
      void joinProblemsWith​(java.util.Collection<Problem> problemList)
      Add all problems in this container into the argument.
      RetVal<java.util.Collection<T>> then​()
      Return a collection of the accumulated values, or the problems collected.
      java.util.Collection<Problem> validProblems​()
      Returns all contained problems in this object, but only if this object contains 1 or more problems.
      ValueAccumulator<T> with​(java.util.Collection<Problem> problemSet, java.util.Collection<Problem>... problemSets)
      Add the given possible problems to the accumulator.
      ValueAccumulator<T> with​(Problem problem, Problem... problems)
      Add the given possible problems to the accumulator.
      ValueAccumulator<T> with​(RetNullable<T> value)
      Add the given value or problems to this accumulator.
      ValueAccumulator<T> with​(RetVal<T> value)
      Add the given value or problems to this accumulator.
      ValueAccumulator<T> withAll​(RetNullable<? extends java.lang.Iterable<T>> value)
      If the argument is okay, then all the entries in the value are added into this accumulator (but only if the value is non-null).
      ValueAccumulator<T> withAll​(RetVal<? extends java.lang.Iterable<T>> value)
      If the argument is okay, then all the entries in the value are added into this accumulator.
      ValueAccumulator<T> withAllValues​(java.lang.Iterable<T>... values)
      Add vararg list of values into this accumulator.
      ValueAccumulator<T> withAllValues​(T... values)
      Add vararg list of values into this accumulator.
      <V> ValueAccumulator<T> withEach​(java.util.Collection<V> input, NonnullReturnFunction<V,RetVal<T>> func)
      For each element in the input list, process it through the function argument to transform into the accumulator type.
      <V> ValueAccumulator<T> withEach​(RetVal<? extends java.util.Collection<V>> inputRes, NonnullReturnFunction<V,RetVal<T>> func)
      For each element in the input list, process it through the function argument to transform into the accumulator type.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • from

        @Nonnull
public static <T> ValueAccumulator<T> from​()
        Create a new, empty value accumulator instance.
        Type Parameters:
        T - value type
        Returns:
        new instance.

      • from

        @Nonnull
public static <T> ValueAccumulator<T> from​(@Nonnull
                                           RetVal<T> value)
        Create a new value accumulator that starts with the given value or problems.
        Type Parameters:
        T - type of the value
        Parameters:
        value - value or problem.
        Returns:
        new instance.

      • from

        @Nonnull
public static <T> ValueAccumulator<T> from​(@Nonnull
                                           RetNullable<T> value)
        Create a new value accumulator that starts with the given value or problems.
        Type Parameters:
        T - type of the value
        Parameters:
        value - value or problem.
        Returns:
        new instance.

      • from

        @Nonnull
public static <T> ValueAccumulator<T> from​(@Nonnull
                                           Problem problem,
                                           @Nonnull
                                           Problem... problems)
        Create a new value accumulator that starts with the given problem(s).
        Type Parameters:
        T - type of the value
        Parameters:
        problem - a problem.
        problems - optional additional problems.
        Returns:
        new instance.

      • getCollector

        @Nonnull
public ProblemCollector getCollector​()
        Get the underlying collector object, for adding arbitrary problems to the accumulator.
        Returns:
        the underlying problem collector object.
        Since:
        2.1

      • with

        @Nonnull
public ValueAccumulator<T> with​(@Nonnull
                                RetVal<T> value)
        Add the given value or problems to this accumulator.
        Parameters:
        value - value or problems
        Returns:
        this instance

      • with

        @Nonnull
public ValueAccumulator<T> with​(@Nonnull
                                RetNullable<T> value)
        Add the given value or problems to this accumulator.
        Parameters:
        value - value or problems
        Returns:
        this instance

      • with

        @Nonnull
public ValueAccumulator<T> with​(@Nonnull
                                Problem problem,
                                @Nonnull
                                Problem... problems)
        Add the given possible problems to the accumulator.
        Parameters:
        problem - a problem.
        problems - optional additional problems.
        Returns:
        this instance

      • with

        @SafeVarargs
@Nonnull
public final ValueAccumulator<T> with​(@Nonnull
                                      java.util.Collection<Problem> problemSet,
                                      @Nonnull
                                      java.util.Collection<Problem>... problemSets)
        Add the given possible problems to the accumulator.
        Parameters:
        problemSet - a collection of problems.
        problemSets - vararg optional additional problems.
        Returns:
        this instance

      • withAllValues

        @SafeVarargs
@Nonnull
public final ValueAccumulator<T> withAllValues​(T... values)
        Add vararg list of values into this accumulator.
        Parameters:
        values - list of values to add into the internal accumulated list.
        Returns:
        this accumulator
        Throws:
        java.lang.NullPointerException - if the value array is null.
        Since:
        2.1

      • withAllValues

        @SafeVarargs
@Nonnull
public final ValueAccumulator<T> withAllValues​(@Nonnull
                                               java.lang.Iterable<T>... values)
        Add vararg list of values into this accumulator.
        Parameters:
        values - list of values to add into the internal accumulated list.
        Returns:
        this accumulator
        Since:
        2.1

      • add

        public void add​(@Nonnull
                RetVal<T> res)
        Add a value into this accumulator if the return value is ok, otherwise add the problems.
        Parameters:
        res - value to add into the internal accumulated list.
        Since:
        2.1

      • add

        public void add​(@Nonnull
                RetNullable<T> res)
        Add a value into this accumulator if the return value is ok, otherwise add the problems.
        Parameters:
        res - value to add into the internal accumulated list.
        Since:
        2.1

      • add

        public void add​(@Nonnull
                ValuedProblemContainer<T> res)
        Add a value into this accumulator if the return value is ok, otherwise add the problems.
        Parameters:
        res - value to add into the internal accumulated list.
        Since:
        2.1

      • addAll

        public void addAll​(@Nonnull
                   java.lang.Iterable<ValuedProblemContainer<T>> values)
        Add a list of values into this accumulator. If a value has problems, then the problems are added; if the value has no problems, then the value is added.

        This will work unexpectedly with WarningVal objects; the value will only be added if no problems are in the warning value.

        Parameters:
        values - list of values to add into the internal accumulated list.
        Since:
        2.1

      • addValue

        public void addValue​(T value)
        Add vararg list of values into this accumulator.
        Parameters:
        value - value to add into the internal accumulated list.
        Since:
        2.1

      • addAllValues

        public void addAllValues​(@Nonnull
                         java.lang.Iterable<T> values)
        Add vararg list of values into this accumulator.
        Parameters:
        values - list of values to add into the internal accumulated list.
        Since:
        2.1

      • withAll

        @Nonnull
public ValueAccumulator<T> withAll​(@Nonnull
                                   RetVal<? extends java.lang.Iterable<T>> value)
        If the argument is okay, then all the entries in the value are added into this accumulator. Otherwise, its problems are added into this accumulator.
        Parameters:
        value - RetVal instance with a collection of values to accumulate.
        Returns:
        this instance
        Since:
        2.1

      • withAll

        @Nonnull
public ValueAccumulator<T> withAll​(@Nonnull
                                   RetNullable<? extends java.lang.Iterable<T>> value)
        If the argument is okay, then all the entries in the value are added into this accumulator (but only if the value is non-null). Otherwise, its problems are added into this accumulator. An underlying null result is ignored.
        Parameters:
        value - RetNullable instance with a collection of values to accumulate.
        Returns:
        this instance
        Since:
        2.1

      • withEach

        public <V> ValueAccumulator<T> withEach​(@Nonnull
                                        java.util.Collection<V> input,
                                        @Nonnull
                                        NonnullReturnFunction<V,RetVal<T>> func)
        For each element in the input list, process it through the function argument to transform into the accumulator type.
        Type Parameters:
        V - input value type
        Parameters:
        input - list of input values
        func - mapping function or validator
        Returns:
        this instance

      • withEach

        public <V> ValueAccumulator<T> withEach​(@Nonnull
                                        RetVal<? extends java.util.Collection<V>> inputRes,
                                        @Nonnull
                                        NonnullReturnFunction<V,RetVal<T>> func)
        For each element in the input list, process it through the function argument to transform into the accumulator type. If the input value has problems, then it is not processed.
        Type Parameters:
        V - input value type
        Parameters:
        inputRes - list of input values or problems
        func - mapping function or validator
        Returns:
        this instance

      • getValues

        @Nonnull
public java.util.Collection<T> getValues​()
        Get all valid values collected so far, even if there are also problems. Null values may be included in the result if null values were added from a RetNullable or transformed function.
        Returns:
        read-only collection of problems.

      • then

        @Nonnull
public RetVal<java.util.Collection<T>> then​()
        Return a collection of the accumulated values, or the problems collected.

        This is functionally identical to asRetVal(), but logically means a continuation of processing within the same call chain.

        Returns:
        the problems or values collected.

      • asRetVal

        @Nonnull
public RetVal<java.util.Collection<T>> asRetVal​()
        Returns the accumulated values as a RetVal if there are no problems, otherwise the enclosed problems.

        This is functionally identical to then(), but logically means a conversion to a standard object and completing the call chain.

        Returns:
        a RetVal representation of this instance.

      • asRetValList

        @Nonnull
public RetVal<java.util.List<T>> asRetValList​()
        Return the value as an unmodifiable List, rather than as a generic Collection.
        Returns:
        a RetVal version of the instance with an underlying List implementation.
        Since:
        2.1

      • asWarning

        @Nonnull
public WarningVal<java.util.Collection<T>> asWarning​()
        Return this accumulator as a warning value, containing both all collected values (up to this point) and discovered problems.
        Returns:
        warning version of the accumulator.

      • isProblem

        public boolean isProblem​()
        Description copied from interface: ProblemContainer
        Returns whether this object contains 1 or more problems.
        Specified by:
        isProblem in interface ProblemContainer
        Returns:
        true if there is a problem, false if there is no problem.

      • isOk

        public boolean isOk​()
        Description copied from interface: ProblemContainer
        Returns whether this object contains zero problems.
        Specified by:
        isOk in interface ProblemContainer
        Returns:
        true if there are no problems, false if there is a problem.

      • anyProblems

        @Nonnull
public java.util.Collection<Problem> anyProblems​()
        Description copied from interface: ProblemContainer
        Return all the problems in this object, even if the container is "ok".

        Generally, this combines the problems in this instance with a larger collection, which can itself be used to check if any of the values had problems.

        The returned collection is read-only, and contains no null values.

        Specified by:
        anyProblems in interface ProblemContainer
        Returns:
        the problems contained in this container, even if there are none.

      • validProblems

        @Nonnull
public java.util.Collection<Problem> validProblems​()
        Description copied from interface: ProblemContainer
        Returns all contained problems in this object, but only if this object contains 1 or more problems. If it contains 0, then this throws an IllegalStateException.

        The returned collection is read-only, and contains no null values.

        Specified by:
        validProblems in interface ProblemContainer
        Returns:
        the problems in this container, and the collection will contain at least 1 item.

      • debugProblems

        @Nonnull
public java.lang.String debugProblems​(@Nonnull
                                      java.lang.String joinedWith)
        Description copied from interface: ProblemContainer
        Return the problems as a single string, which combines the Object.toString() output of each problem with the given joining string parameter. If this object contains no problems, then an empty string is returned instead.
        Specified by:
        debugProblems in interface ProblemContainer
        Parameters:
        joinedWith - the text to join multiple problem strings together.
        Returns:
        the combined text of the problems, or an empty string if there are no problems.

      • joinProblemsWith

        public void joinProblemsWith​(@Nonnull
                             java.util.Collection<Problem> problemList)
        Description copied from interface: ProblemContainer
        Add all problems in this container into the argument. This has a very specific usage to indicate that this container, even if it has no problems, is part of a bigger issue. Therefore, this is fine to call even if there are no problems in this container.
        Specified by:
        joinProblemsWith in interface ProblemContainer
        Parameters:
        problemList - a modifiable collection of zero or more problems.