Module io.github.teceli.resiliencia.core
Package io.github.teceli.resiliencia.core.api

Interface Resilient<T>

All Known Implementing Classes:
Bulkhead, CircuitBreaker, FakeResilient, Policy, RateLimiter, Retry, Timeout
public interface Resilient<T>
Base interface for all resilience patterns. Patterns implement this to provide call execution with resilience guarantees.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Resilient.Operation<T>
     

  • Method Summary

    Modifier and Type
    Method
    Description
    T
    call(Resilient.Operation<T> operation)
    Execute an operation with resilience guarantees.
    default CompletableFuture<T>
    callAsync(Resilient.Operation<T> operation)
    Execute an operation asynchronously on a new virtual thread and return a handle to its result.
    default boolean
    hasOwnDeadline()
    Whether this pattern already enforces its own upper bound on total duration, independent of any outer Timeout.
    Outcome<T>
    outcome(Resilient.Operation<T> operation)
    Execute an operation and capture the result or failure as an Outcome.
    default PatternKind
    patternKind()
    The kind of this pattern, used for internal comparisons (e.g.
    default String
    patternName()
    The name of this pattern, e.g.

  • Method Details

    • call

      T call(Resilient.Operation<T> operation) throws ResilientException
      Execute an operation with resilience guarantees. May throw ResilienciaException or a specific pattern exception.
      Throws:
      ResilientException

    • outcome

      Outcome<T> outcome(Resilient.Operation<T> operation)
      Execute an operation and capture the result or failure as an Outcome. Never throws for a recorded Exception — always returns Success, Failure, or a pattern-specific outcome. An Error thrown by the operation propagates uncaught instead of being captured as a Failure: fatal JVM conditions (e.g. OutOfMemoryError) should not be treated as a recoverable result.

    • callAsync

      default CompletableFuture<T> callAsync(Resilient.Operation<T> operation)
      Execute an operation asynchronously on a new virtual thread and return a handle to its result. The future completes with the value of call(io.github.teceli.resiliencia.core.api.Resilient.Operation<T>), or exceptionally with whatever call(io.github.teceli.resiliencia.core.api.Resilient.Operation<T>) throws. If call(io.github.teceli.resiliencia.core.api.Resilient.Operation<T>) lets an Error propagate, the future is still completed exceptionally with it (so a waiter on the future is not left hanging), but the Error is also rethrown on the worker thread afterward — it is never treated as a recoverable business outcome (see "Error handling" in docs/architecture/ARCHITECTURE.md). Cancelling the returned future interrupts the virtual thread, so cancellation propagates through whichever pattern is currently blocking — a Timeout wait, a Retry backoff, a Bulkhead or RateLimiter permit wait — including across a full Policy chain.

    • patternName

      default String patternName()
      The name of this pattern, e.g. "retry", "timeout", "circuit-breaker". Used for identification (e.g. by Policy) without coupling to concrete pattern types. Defaults to "custom" for user-defined Resilient implementations.

    • patternKind

      default PatternKind patternKind()
      The kind of this pattern, used for internal comparisons (e.g. Policy order validation). Unlike patternName(), which is a free-form observability label, this is a closed enum the library can reason about exhaustively. Defaults to PatternKind.CUSTOM for user-defined Resilient implementations.

    • hasOwnDeadline

      default boolean hasOwnDeadline()
      Whether this pattern already enforces its own upper bound on total duration, independent of any outer Timeout. Used by Policy to decide whether a Timeout-wraps-Retry ordering warning still applies. Defaults to false for user-defined Resilient implementations.