jakarta.ws.rs.container.TimeoutHandler Maven / Gradle / Ivy
/*
* Copyright (c) 2012, 2019 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.ws.rs.container;
/**
* Asynchronous response suspend time-out handler.
*
* JAX-RS users may utilize this callback interface to provide custom resolution of time-out events.
*
* By default, JAX-RS runtime generates a {@link jakarta.ws.rs.WebApplicationException} with a
* {@link jakarta.ws.rs.core.Response.Status#SERVICE_UNAVAILABLE HTTP 503 (Service unavailable)} error response status
* code. A custom time-out handler may be {@link AsyncResponse#setTimeoutHandler(TimeoutHandler) set} on an asynchronous
* response instance to provide custom time-out event resolution.
*
*
* In case of a suspend time-out event, a custom time-out handler takes typically one of the following actions:
*
*
* - Resumes the suspended asynchronous response using a {@link AsyncResponse#resume(Object) custom response} or a
* {@link AsyncResponse#resume(Throwable) custom exception}
* - Cancels the response by calling one of the {@link AsyncResponse} {@code cancel(...)} methods.
* - Extends the suspend period of the response by
* {@link AsyncResponse#setTimeout(long, java.util.concurrent.TimeUnit) setting a new suspend time-out}
*
*
* If the registered time-out handler does not take any of the actions above, the default time-out event processing
* continues and the response is resumed with a generated {@code WebApplicationException} containing the HTTP 503 status
* code.
*
*
* Following example illustrates the use of a custom {@code TimeoutHandler}:
*
*
*
* public class MyTimeoutHandler implements TimeoutHandler {
* …
* public void handleTimeout(AsyncResponse ar) {
* if (keepSuspended) {
* ar.setTimeout(10, SECONDS);
* } else if (cancel) {
* ar.cancel(retryPeriod);
* } else {
* ar.resume(defaultResponse);
* }
* }
* …
* }
*
* @Path("/messages/next")
* public class MessagingResource {
* …
* @GET
* public void readMessage(@Suspended AsyncResponse ar) {
* ar.setTimeoutHandler(new MyTimeoutHandler());
* suspended.put(ar);
* }
* …
* }
*
*
* @author Marek Potociar
* @since 2.0
*/
public interface TimeoutHandler {
/**
* Invoked when the suspended asynchronous response is about to time out.
*
* Implementing time-out handlers may use the callback method to change the default time-out strategy defined by JAX-RS
* specification (see {@link jakarta.ws.rs.container.AsyncResponse} API documentation).
*
* A custom time-out handler may decide to either
*
*
* - resume the suspended response using one of it's {@code resume(...)} methods,
* - cancel the suspended response using one of it's {@code cancel(...)} methods, or
* - extend the suspend period by {@link AsyncResponse#setTimeout(long, java.util.concurrent.TimeUnit) setting a new
* suspend time-out}
*
* In case the time-out handler does not take any of the actions mentioned above, a default time-out strategy is
* executed by the JAX-RS runtime.
*
* @param asyncResponse suspended asynchronous response that is timing out.
*/
public void handleTimeout(AsyncResponse asyncResponse);
}