Interface Result<V,E>

Type Parameters:
V - the type of the success value
E - the type of the error value
All Known Implementing Classes:
Result.Err, Result.Ok
public sealed interface Result<V,E> permits Result.Ok<V,E>, Result.Err<V,E>

The result of an operation that can fail: a success value (Result.Ok) or an error value (Result.Err).

jsonlens reports errors with this type, not with exceptions. The parser, the evaluator, and the registration of function extensions all return a Result.

Examine a result

Result is sealed, so a switch with record patterns must handle both cases. The compiler tells you if a case is missing:

Result<Integer, Problem> port = parsePort("8080");

// Examine a result with a switch. The compiler checks that all cases are present.
String text = switch (port) {
    case Result.Ok(Integer value) -> "port " + value;
    case Result.Err(Problem problem) -> "no port: " + problem.reason();
};

// Or change it with map, flatMap, and fold.
Result<String, Problem> url = port.map(value -> "http://localhost:" + value);
int value = port.orElse(80);

Make a result

Use ok(Object) and err(Object). The error type is usually a sealed interface of records:

static Result<Integer, Problem> parsePort(String text) {
    if (!text.matches("[0-9]{1,5}")) {
        return Result.err(new Problem("not a number: " + text));
    }
    int port = Integer.parseInt(text);
    return port <= 65_535 ? Result.ok(port) : Result.err(new Problem("too large: " + port));
}

Operations

Method On Result.Ok On Result.Err
map(Function) applies the function to the value no change
mapErr(Function) no change applies the function to the error
flatMap(Function) applies an operation that can fail no change
fold(Function, Function) applies the first function applies the second function
orElse(Object) gives the value gives the fallback value

flatMap(Function) chains operations that can fail, for example a parse and an evaluation:

// Result.flatMap chains the parse and the evaluation. The error type is a String here.
Result<List<Node<JsonNode>>, String> authors = JsonPathParser.standard()
        .parse("$..author")
        .mapErr(ParseError::message)
        .flatMap(query -> JsonPathEvaluator.standard()
                .evaluate(query, root, JacksonJsonModel.INSTANCE)
                .mapErr(EvaluationError::message));

int count = authors.fold(List::size, error -> 0); // 4

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    Result.Err<V,E>
    An error value.
    static final record 
    Result.Ok<V,E>
    A success value.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <V,E> Result<V,E>
    err(E error)
    Makes an error result.
    default <U> Result<U,E>
    flatMap(Function<? super V, Result<U,E>> mapper)
    Applies an operation that can fail to the success value.
    default <R> R
    fold(Function<? super V, ? extends R> onOk, Function<? super E, ? extends R> onErr)
    Changes the success value or the error value into one value.
    default boolean
    isErr()
    Returns true for an error result.
    default boolean
    isOk()
    Returns true for a success result.
    default <U> Result<U,E>
    map(Function<? super V, ? extends U> mapper)
    Changes the success value.
    default <F> Result<V,F>
    mapErr(Function<? super E, ? extends F> mapper)
    Changes the error value.
    static <V,E> Result<V,E>
    ok(V value)
    Makes a success result.
    default V
    orElse(V fallback)
    Returns the success value, or a fallback value for an error result.

  • Method Details

    • ok

      static <V,E> Result<V,E> ok(V value)
      Makes a success result.
      Type Parameters:
      V - the type of the success value
      E - the type of the error value
      Parameters:
      value - the value
      Returns:
      a success result

    • err

      static <V,E> Result<V,E> err(E error)
      Makes an error result.
      Type Parameters:
      V - the type of the success value
      E - the type of the error value
      Parameters:
      error - the error
      Returns:
      an error result

    • isOk

      default boolean isOk()
      Returns true for a success result.
      Returns:
      true if this is an Result.Ok

    • isErr

      default boolean isErr()
      Returns true for an error result.
      Returns:
      true if this is an Result.Err

    • map

      default <U> Result<U,E> map(Function<? super V, ? extends U> mapper)
      Changes the success value. An error result does not change.
      Type Parameters:
      U - the new type of the success value
      Parameters:
      mapper - the function for the success value
      Returns:
      the changed result

    • mapErr

      default <F> Result<V,F> mapErr(Function<? super E, ? extends F> mapper)
      Changes the error value. A success result does not change.
      Type Parameters:
      F - the new type of the error value
      Parameters:
      mapper - the function for the error value
      Returns:
      the changed result

    • flatMap

      default <U> Result<U,E> flatMap(Function<? super V, Result<U,E>> mapper)
      Applies an operation that can fail to the success value. An error result does not change.
      Type Parameters:
      U - the type of the success value of the operation
      Parameters:
      mapper - the operation for the success value
      Returns:
      the result of the operation, or this error

    • fold

      default <R> R fold(Function<? super V, ? extends R> onOk, Function<? super E, ? extends R> onErr)
      Changes the success value or the error value into one value.
      Type Parameters:
      R - the type of the value
      Parameters:
      onOk - the function for a success value
      onErr - the function for an error value
      Returns:
      the value from the applicable function

    • orElse

      default V orElse(V fallback)
      Returns the success value, or a fallback value for an error result.
      Parameters:
      fallback - the value for an error result
      Returns:
      the success value or the fallback value