package org.jboss.resteasy.core.interception.jaxrs;

import jakarta.ws.rs.container.ContainerRequestContext;

/**
 * Suspendable request context, which allows the users to suspend execution of the filter
 * chain until it is resumed normally, or abnormally with a {@link Throwable}.
 *
 * @author <a href="mailto:stef@epardaud.fr">Stéphane Épardaud</a>
 */
public interface SuspendableContainerRequestContext extends ContainerRequestContext {
    /**
     * Suspends the current request. This makes the current request asynchronous. No
     * further request filter is executed until this request is resumed.
     *
     * No reply is going to be sent to the client until this request is resumed either
     * with {@link #resume()} or aborted with {@link #resume(Throwable)} or
     * {@link #abortWith(jakarta.ws.rs.core.Response)}.
     */
    void suspend();

    /**
     * Resumes the current request, and proceeds to the next request filter, if any,
     * or to the resource method.
     */
    void resume();

    /**
     * Aborts the current request with the given exception. This behaves as if the request
     * filter threw this exception synchronously, which means exceptions may be mapped via
     * exception mappers, response filters will run and async response callbacks will be
     * called with this exception.
     *
     * @param t the exception to send back to the client, as mapped by the application.
     */
    void resume(Throwable t);
}
