Package name.martingeisse.grumpyjson

Class FieldErrorNode

java.lang.Object
name.martingeisse.grumpyjson.FieldErrorNode
Direct Known Subclasses:
FieldErrorNode.Field, FieldErrorNode.InternalException, FieldErrorNode.Message, FieldErrorNode.Siblings
public abstract class FieldErrorNode extends Object
This class typically gets constructed by grumpyjson and consumed by grumpyrest, without any need for the application code to deal with it. Application code can, however,
  • get instances after an error has occurred, to access the field path and message programmatically
  • create instances inside custom converters to expose the field path for nestable custom types

This class and its subclasses allow to quickly construct error information, then propagate it upwards while collecting the field path, and finally generate one or more error messages as strings or JSON from it.

An error is generated from a specific JSON value, e.g. from a JSON string whose format does not match a validation pattern. Such an error is created with a message, but does not know the context (field path) in which it occurs, nor does it know about other errors that may occur in other fields. The error is then wrapped in an exception (either JsonDeserializationException or JsonSerializationException) and thrown to propagate it upwards. Container values further up then process these exceptions and re-throw them, collecting multiple errors and augmenting their field paths. The result is a tree structure of FieldErrorNode that contains all errors that have occurred in the whole JSON structure. This tree structure is then usually flattened to a list of errors and returned to the REST client.

Instances of this class and its subclasses are immutable. All grouping and nesting is done by creating new nodes around the existing nodes.

Instances of this class should be created using factory methods. The subclass constructors are private to enforce this.

  • Method Details

    • create

      public static FieldErrorNode create(String message)
      Creates a node for a single error message without a field path.
      Parameters:
      message - the error message
      Returns:
      the newly created node

    • create

      public static FieldErrorNode create(Exception exception)
      Creates a node for a single error message without a field path.
      Parameters:
      exception - an exception that caused the error
      Returns:
      the newly created node

    • and

      public final FieldErrorNode and(FieldErrorNode other)
      Groups two error sets together in a single new node. This and the other node may both contain multiple errors and possibly use field path suffixes. If this node is later used below another field path prefix, then that prefix applies to all errors from this and the other node.
      Parameters:
      other - the other node to group together with this one. May be null, in which case this method just returns this node -- this simplifies combining optional errors from multiple sources.
      Returns:
      the node that groups both nodes

    • in

      public final FieldErrorNode in(String fieldName)
      Adds the nesting within a single field as a prefix to the field path of this node, returning the result as a new node. The nesting affects all errors stored under this node.

      Note that if a prefix consisting of multiple nesting levels is to be added, then this method must be called multiple times in reverse order (i.e. from innermost field to outermost field).

      Parameters:
      fieldName - the name of the field to add as a prefix
      Returns:
      the node that has the prefix applied

    • flatten

      public final List<FieldErrorNode.FlattenedError> flatten()
      Flattens the errors contained in this node and its subnodes as a list of FieldErrorNode.FlattenedError objects.
      Returns:
      the flattened errors

    • flatten

      protected abstract void flatten(List<FieldErrorNode.FlattenedError> errors, List<String> segments)
      NOT PUBLIC API
      Parameters:
      errors - ...
      segments - ...

    • toString

      public String toString()
      This method turns the node to a string for simple output / debugging purposes. It does not guarantee a specific format of the string. To process errors programmatically, use flatten() to get the contained errors in a more reliable format, or process the nodes directly.
      Overrides:
      toString in class Object
      Returns:
      this node as a string