Package com.guinetik.rr.interceptor

Interface RequestInterceptor

  • All Known Implementing Classes:
    RetryInterceptor
    public interface RequestInterceptor
    Interceptor for adding cross-cutting behavior to HTTP request execution.

    Interceptors provide lifecycle hooks that can modify requests before execution, transform responses after execution, and handle errors (including retry logic). They form a chain where each interceptor can delegate to the next.

    Interceptor Chain

     Request → [Interceptor 1] → [Interceptor 2] → ... → [HTTP Client] → Response
              ↓ beforeRequest()                           ↓
              ↓ onError() if exception                    ↓
              ← afterResponse() ←←←←←←←←←←←←←←←←←←←←←←←←←←

    Creating an Interceptor

    
 public class LoggingInterceptor implements RequestInterceptor {

     @Override
     public <Req, Res> RequestSpec<Req, Res> beforeRequest(RequestSpec<Req, Res> request) {
         System.out.println("-> " + request.getMethod() + " " + request.getEndpoint());
         return request;
     }

     @Override
     public <Res> Res afterResponse(Res response, RequestSpec<?, Res> request) {
         System.out.println("<- Response received");
         return response;
     }
 }

    Retry Interceptor Example

    
 public class RetryInterceptor implements RequestInterceptor {
     private final int maxRetries = 3;

     @Override
     public <Req, Res> Res onError(RocketRestException e, RequestSpec<Req, Res> request,
                                    InterceptorChain chain) throws RocketRestException {
         if (isRetryable(e) && chain.getRetryCount() < maxRetries) {
             Thread.sleep(1000 * chain.getRetryCount()); // Exponential backoff
             return chain.retry(request);
         }
         throw e;
     }
 }

    Using Interceptors

    
 RocketClient client = RocketClientFactory.builder("https://api.example.com")
     .withInterceptor(new LoggingInterceptor())
     .withInterceptor(new RetryInterceptor(3, 1000))
     .withInterceptor(new MetricsInterceptor())
     .build();
    Since:
    1.1.0
    Author:
    guinetik <guinetik@gmail.com>
    See Also:
    InterceptorChain, RetryInterceptor

    • Method Detail

      • beforeRequest

        default <Req,​Res> RequestSpec<Req,​Res> beforeRequest​(RequestSpec<Req,​Res> request)
        Called before a request is executed.

        This method can modify the request (e.g., add headers, transform body) or return the same request unchanged. To short-circuit the chain and prevent execution, throw an exception.

        Type Parameters:
        Req - The request body type
        Res - The response type
        Parameters:
        request - The request specification
        Returns:
        The (possibly modified) request to execute

      • afterResponse

        default <Res> Res afterResponse​(Res response,
                                RequestSpec<?,​Res> request)
        Called after a successful response is received.

        This method can transform the response or perform side effects like logging or metrics collection.

        Type Parameters:
        Res - The response type
        Parameters:
        response - The response from the server
        request - The original request specification
        Returns:
        The (possibly transformed) response

      • onError

        default <Req,​Res> Res onError​(RocketRestException e,
                                    RequestSpec<Req,​Res> request,
                                    InterceptorChain chain)
                             throws RocketRestException
        Called when an exception occurs during request execution.

        This method can:

        • Retry the request using InterceptorChain.retry(RequestSpec)
        • Transform the exception into a different one
        • Recover and return a fallback response
        • Rethrow the exception (default behavior)
        Type Parameters:
        Req - The request body type
        Res - The response type
        Parameters:
        e - The exception that occurred
        request - The request that failed
        chain - The interceptor chain (use for retry)
        Returns:
        A recovered response, or throws an exception
        Throws:
        RocketRestException - If the error cannot be handled

      • getOrder

        default int getOrder()
        Returns the order of this interceptor in the chain.

        Lower values execute first. Use negative values for interceptors that must run early (e.g., authentication), and positive values for interceptors that should run late (e.g., logging).

        Suggested ordering:

        • -100: Authentication/Authorization
        • 0: Default (most interceptors)
        • 100: Retry logic
        • 200: Logging/Metrics
        Returns:
        The order value (lower = earlier)