Package nz.org.riskscape.problem

Interface Problems

All Superinterfaces:
Iterable<Problem>
All Known Implementing Classes:
Problem, Unchecked
public interface Problems extends Iterable<Problem>

The Problems interface exists to abstract over a single Problem or a collection of them (ProblemList), because most of the time when dealing with errors it doesn't matter whether you have one or many, you just want to pass one or more around.

Helpers for generating Problem objects.

General tips: - Try to reuse existing ProblemFactory APIs where possible. - To help make messages reusable, try to think in generic terms - use '[thing]' as a placeholder in your message. E.g. use "[thing] was invalid" over the more specific "pipeline step '[name]' was invalid". - Use objects as building blocks in your message, i.e. just pass in the whole NamedStep as an arg rather than using NamedStep.getName(). This means we can display things in a consistent, user-friendly, translatable way. Displaying these objects args is handled in ObjectRenderer. - If you don't have an instance of a particular object, you may be able to use ProblemPlaceholder as a placeholder. - If it's an exception, always use caught(Throwable). Never use Throwable.getMessage() directly. - If you just want to group or nest problems together, use foundWith(Object, List).

  • Field Details

    • NONE

      static final Problems NONE

      An empty ProblemList

  • Method Details

    • errorWith

      static Problem errorWith(ProblemCode code, Object thing, Object... otherArgs)

      Creates a Problem for an error found with a given object. I.e. there is clearly a thing (Parameter, Step, Bookmark, etc) that is associated with or affected by this Problem. This results in the same end message as Problem.error(ProblemCode, Object...), but stores some extra contextual info with the Problem. Note that the 'thing' should always be the first MessageFormat argument, i.e. {0} in the .properties file. The affected thing's contextual info (i.e. class, name) is preserved and can be interrogated later (i.e. by Problem.getAffectedClass()).

    • foundWith

      static Problem foundWith(Object thing, Problems children)

    • foundWith

      static Problem foundWith(Object thing, List<Problem> children)

      Collates the children into a top-level problem: "Problems found with {thing}"

    • foundWith

      static Problem foundWith(Object thing, Problem... child)

      Creates a simple "Problems found with {thing}" problem with optional child problems. This can be a useful placeholder when you want to nest problems but you don't have all the child problems yet. Or you only have a single child problem rather than a list.

    • foundWith

      static Problem foundWith(Class<?> thing, String name, List<Problem> children)

    • foundWith

      static Problem foundWith(Class<?> thing, String name, Problem... child)

    • toSingleProblem

      static Problem toSingleProblem(List<Problem> children)

      Helper for wrapping a list of problems with a single problem - useful where you go from a multiple problem API to a single problem API (sigh).

      Returns the 0th element if children is of size 1

    • caught

      static Problem caught(Throwable ex)

    • parseError

      static Problem parseError(Object expected)

      Produces an error: "Failed to parse [expectedThing]' E.g. Failed to parse pipeline 'foo' Similar to ExpressionProblems.cannotParse(Object, String) but useful when parsing something other than an expressions, or when we don't have easy access to the problematic expression itself.

    • get

      static <T extends ProblemFactory> T get(Class<T> factory)

      Gets a (proxied) ProblemFactory that can be used to generate Problems. The standard usage would be: Problem problem = Problem.create(MyFactory.class).myErrorApi(args);

    • from

      static Problems from(List<Problem> children)
      Returns:
      the correct thing from a list of children, either NONE, the individual problem, or a ProblemList

    • from

      static Problems from(Problem... children)

    • toProblem

      Optional<Problem> toProblem()

      Convert this Problems in to a single problem, or empty if this is Problems.NONE

    • toList

      List<Problem> toList()

      Convert this Problems in to a (possibly empty) list of Problems

      Returns:

    • stream

      Stream<Problem> stream()
      Returns:
      a stream over any individual Problems

    • isPresent

      default boolean isPresent()
      Returns:
      true if this Problems will yield one or more Problems

    • isEmpty

      boolean isEmpty()
      Returns:
      true if this Problems is NONE

    • getSeverity

      Problem.Severity getSeverity()
      Returns:
      the maximum severity of any Problems, or INFO if empty.