Interface DataResult<T>

Type Parameters:
T - The type of the wrapped value.
All Known Implementing Classes:
DataResult.Error, DataResult.Success
public interface DataResult<T>
A monadic container representing the result of a serialization or deserialization operation. Contains either a successful value, potentially with partial warnings, or an error message detailing the failure context.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    DataResult.Error<T>
    The structural implementation of a failed serialization state.
    static final record 
    DataResult.Success<T>
    The structural implementation of a successful serialization state, handling optional partials.

  • Method Summary

    Modifier and Type
    Method
    Description
    DataResult<T>
    addWarning(DataError warning)
    Injects a recorded warning into the execution timeline without forcing a structural failure.
    Optional<DataError>
    dataError()
     
    Optional<String>
    error()
     
    static <T> DataResult<T>
    error(DataError error)
    Creates an error result driven by an explicit DataError type.
    static <T> DataResult<T>
    error(String message)
    Creates an error result with the provided string message.
    <R> DataResult<R>
    flatMap(Function<? super T, ? extends DataResult<? extends R>> mapper)
    Transforms the wrapped value into a new DataResult using the provided flat-mapping function.
    T
    getOrThrow()
    Retrieves the value or throws a RuntimeException if this is an error.
    boolean
    isError()
     
    boolean
    isPartial()
     
    boolean
    isSuccess()
     
    <R> DataResult<R>
    map(Function<? super T, ? extends R> mapper)
    Transforms the wrapped value using the provided mapping function.
    DataResult<T>
    mapError(Function<String,String> errorMapper)
    Transforms the error message if this result represents an error.
    T
    orElse(T defaultValue)
    Retrieves the value, or returns the provided default value if this is an error.
    static <T> DataResult<T>
    partial(T value, List<DataError> warnings)
    Creates a partial result containing the provided value, logging structural warnings.
    DataResult<T>
    prependPath(String path)
    Prepends a path segment to the error context or recorded warnings to build a complete diagnostic trajectory.
    Optional<T>
    result()
     
    static <T> DataResult<T>
    success(T value)
    Creates a successful result containing the provided value with no structural warnings.
    List<DataError>
    warnings()
     

  • Method Details

    • success

      static <T> DataResult<T> success(T value)
      Creates a successful result containing the provided value with no structural warnings.
      Type Parameters:
      T - The type of the value.
      Parameters:
      value - The value to wrap.
      Returns:
      A successful DataResult.

    • partial

      static <T> DataResult<T> partial(T value, List<DataError> warnings)
      Creates a partial result containing the provided value, logging structural warnings.
      Type Parameters:
      T - The type of the value.
      Parameters:
      value - The value mapped despite violations.
      warnings - The collected issues encountered alongside data generation.
      Returns:
      A successful DataResult with attached warnings.

    • error

      static <T> DataResult<T> error(String message)
      Creates an error result with the provided string message.
      Type Parameters:
      T - The expected type of the value.
      Parameters:
      message - The error message.
      Returns:
      An error DataResult wrapping a custom DataError.

    • error

      static <T> DataResult<T> error(DataError error)
      Creates an error result driven by an explicit DataError type.
      Type Parameters:
      T - The expected type of the value.
      Parameters:
      error - The structural error implementation.
      Returns:
      An error DataResult.

    • isSuccess

      boolean isSuccess()
      Returns:
      True if this result represents a success (including partial successes), false otherwise.

    • isError

      boolean isError()
      Returns:
      True if this result represents an error, false otherwise.

    • isPartial

      boolean isPartial()
      Returns:
      True if this result is successful but carries recorded warnings.

    • result

      Optional<T> result()
      Returns:
      An Optional containing the value if successful, or empty if an error.

    • error

      Optional<String> error()
      Returns:
      An Optional containing the formatted error message if an error, or empty if successful.

    • dataError

      Optional<DataError> dataError()
      Returns:
      An Optional containing the exact DataError type evaluated during deserialization.

    • warnings

      List<DataError> warnings()
      Returns:
      The collection of recorded warnings if this is a partial result.

    • getOrThrow

      T getOrThrow()
      Retrieves the value or throws a RuntimeException if this is an error.
      Returns:
      The wrapped value.
      Throws:
      RuntimeException - If this result represents an error.

    • orElse

      T orElse(T defaultValue)
      Retrieves the value, or returns the provided default value if this is an error.
      Parameters:
      defaultValue - The fallback value.
      Returns:
      The wrapped value or the default.

    • map

      <R> DataResult<R> map(Function<? super T, ? extends R> mapper)
      Transforms the wrapped value using the provided mapping function.
      Type Parameters:
      R - The new value type.
      Parameters:
      mapper - The transformation logic.
      Returns:
      A new DataResult containing the transformed value.

    • flatMap

      <R> DataResult<R> flatMap(Function<? super T, ? extends DataResult<? extends R>> mapper)
      Transforms the wrapped value into a new DataResult using the provided flat-mapping function. Supports covariant return types to prevent generic capture mismatches.
      Type Parameters:
      R - The new value type.
      Parameters:
      mapper - The transformation logic that yields a DataResult.
      Returns:
      A new DataResult.

    • mapError

      DataResult<T> mapError(Function<String,String> errorMapper)
      Transforms the error message if this result represents an error.
      Parameters:
      errorMapper - The logic to apply to the existing error message.
      Returns:
      A new DataResult with the transformed error.

    • prependPath

      DataResult<T> prependPath(String path)
      Prepends a path segment to the error context or recorded warnings to build a complete diagnostic trajectory.
      Parameters:
      path - The path segment to prepend.
      Returns:
      A new DataResult reflecting the updated path logic.

    • addWarning

      DataResult<T> addWarning(DataError warning)
      Injects a recorded warning into the execution timeline without forcing a structural failure.
      Parameters:
      warning - The localized diagnostic logging message mapped as an error.
      Returns:
      A modified instance retaining the internal value but flagging warning status.