All Downloads are FREE. Search and download functionalities are using the official Maven repository.

jakarta.ws.rs.container.AsyncResponse 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;

import java.util.Collection;
import java.util.Date;
import java.util.Map;
import java.util.concurrent.TimeUnit;

/**
 * An injectable JAX-RS asynchronous response that provides means for asynchronous server side response processing.
 * 

* A new instance of {@code AsyncResponse} may be injected into a {@link jakarta.ws.rs.HttpMethod resource or sub-resource * method} parameter using the {@link Suspended @Suspended} annotation. *

* Each asynchronous response instance is bound to the running request and can be used to asynchronously provide the * request processing result or otherwise manipulate the suspended client connection. The available operations include: *
    *
  • updating suspended state data (time-out value, response ...)
  • *
  • resuming the suspended request processing
  • *
  • canceling the suspended request processing
  • *
*

* Following example demonstrates the use of the {@code AsyncResponse} for asynchronous HTTP request processing: *

* *
 * @Path("/messages/next")
 * public class MessagingResource {
 *     private static final BlockingQueue<AsyncResponse> suspended = new ArrayBlockingQueue<AsyncResponse>(5);
 *
 *     @GET
 *     public void readMessage(@Suspended AsyncResponse ar) throws InterruptedException {
 *         suspended.put(ar);
 *     }
 *
 *     @POST
 *     public String postMessage(final String message) throws InterruptedException {
 *         final AsyncResponse ar = suspended.take();
 *         ar.resume(message); // resumes the processing of one GET request
 *         return "Message sent";
 *     }
 * }
 * 
*

* If the asynchronous response was suspended with a positive timeout value, and has not been explicitly resumed before * the timeout has expired, the processing will be resumed once the specified timeout threshold is reached, provided a * positive timeout value was set on the response. *

*

* By default a timed-out asynchronous response is resumed with a {@link jakarta.ws.rs.WebApplicationException} that has * {@link jakarta.ws.rs.core.Response.Status#SERVICE_UNAVAILABLE HTTP 503 (Service unavailable)} error response status * code set. This default behavior may be overridden by {@link AsyncResponse#setTimeoutHandler(TimeoutHandler) setting} * a custom {@link TimeoutHandler time-out handler}. *

* * @author Marek Potociar * @since 2.0 */ public interface AsyncResponse { /** * Constant specifying no suspend timeout value. */ public static final long NO_TIMEOUT = 0; /** * Resume the suspended request processing using the provided response data. * * The provided response data can be of any Java type that can be returned from a {@link jakarta.ws.rs.HttpMethod JAX-RS * resource method}. *

* The asynchronous response must be still in a {@link #isSuspended() suspended} state for this method to succeed. *

*

* By executing this method, the request is guaranteed to complete either successfully or with an error. The data * processing by the JAX-RS runtime follows the same path as it would for the response data returned synchronously by a * JAX-RS resource, except that unmapped exceptions are not re-thrown by JAX-RS runtime to be handled by a hosting I/O * container. Instead, any unmapped exceptions are propagated to the hosting I/O container via a container-specific * callback mechanism. Depending on the container implementation, propagated unmapped exceptions typically result in an * error status being sent to the client and/or the connection being closed. *

* * @param response data to be sent back in response to the suspended request. * @return {@code true} if the request processing has been resumed, returns {@code false} in case the request processing * is not {@link #isSuspended() suspended} and could not be resumed. * @see #resume(Throwable) */ public boolean resume(Object response); /** * Resume the suspended request processing using the provided throwable. * * For the provided throwable same rules apply as for an exception thrown by a {@link jakarta.ws.rs.HttpMethod JAX-RS * resource method}. *

* By executing this method, the request is guaranteed to complete either successfully or with an error. The throwable * processing by the JAX-RS runtime follows the same path as it would for the response data returned synchronously by a * JAX-RS resource, except that unmapped exceptions are not re-thrown by JAX-RS runtime to be handled by a hosting I/O * container. Instead, any unmapped exceptions are propagated to the hosting I/O container via a container-specific * callback mechanism. Depending on the container implementation, propagated unmapped exceptions typically result in an * error status being sent to the client and/or the connection being closed. *

* * @param response an exception to be raised in response to the suspended request. * @return {@code true} if the response has been resumed, returns {@code false} in case the response is not * {@link #isSuspended() suspended} and could not be resumed. * @see #resume(Object) */ public boolean resume(Throwable response); /** * Cancel the suspended request processing. *

* When a request processing is cancelled using this method, the JAX-RS implementation MUST indicate to the client that * the request processing has been cancelled by sending back a * {@link jakarta.ws.rs.core.Response.Status#SERVICE_UNAVAILABLE HTTP 503 (Service unavailable)} error response. *

*

* Invoking a {@code cancel(...)} method multiple times to cancel request processing has the same effect as canceling * the request processing only once. Invoking a {@code cancel(...)} method on an asynchronous response instance that has * already been cancelled or resumed has no effect and the method call is ignored while returning {@code true}, in case * the request has been cancelled previously. Otherwise, in case the request has been resumed regularly (using a * {@code resume(...) method}) or resumed due to a time-out, method returns {@code false}. *

* * @return {@code true} if the request processing has been cancelled, returns {@code false} in case the request * processing is not {@link #isSuspended() suspended} and could not be cancelled and is not {@link #isCancelled() * cancelled} already. * @see #cancel(int) * @see #cancel(java.util.Date) */ public boolean cancel(); /** * Cancel the suspended request processing. *

* When a request processing is cancelled using this method, the JAX-RS implementation MUST indicate to the client that * the request processing has been cancelled by sending back a * {@link jakarta.ws.rs.core.Response.Status#SERVICE_UNAVAILABLE HTTP 503 (Service unavailable)} error response with a * {@code Retry-After} header set to the value provided by the method parameter. *

*

* Invoking a {@code cancel(...)} method multiple times to cancel request processing has the same effect as canceling * the request processing only once. Invoking a {@code cancel(...)} method on an asynchronous response instance that has * already been cancelled or resumed has no effect and the method call is ignored while returning {@code true}, in case * the request has been cancelled previously. Otherwise, in case the request has been resumed regularly (using a * {@code resume(...) method}) or resumed due to a time-out, method returns {@code false}. *

* * @param retryAfter a decimal integer number of seconds after the response is sent to the client that indicates how * long the service is expected to be unavailable to the requesting client. * @return {@code true} if the request processing has been cancelled, returns {@code false} in case the request * processing is not {@link #isSuspended() suspended} and could not be cancelled and is not {@link #isCancelled() * cancelled} already. * @see #cancel * @see #cancel(java.util.Date) */ public boolean cancel(int retryAfter); /** * Cancel the suspended request processing. *

* When a request processing is cancelled using this method, the JAX-RS implementation MUST indicate to the client that * the request processing has been cancelled by sending back a * {@link jakarta.ws.rs.core.Response.Status#SERVICE_UNAVAILABLE HTTP 503 (Service unavailable)} error response with a * {@code Retry-After} header set to the value provided by the method parameter. *

*

* Invoking a {@code cancel(...)} method multiple times to cancel request processing has the same effect as canceling * the request processing only once. Invoking a {@code cancel(...)} method on an asynchronous response instance that has * already been cancelled or resumed has no effect and the method call is ignored while returning {@code true}, in case * the request has been cancelled previously. Otherwise, in case the request has been resumed regularly (using a * {@code resume(...) method}) or resumed due to a time-out, method returns {@code false}. *

* * @param retryAfter a date that indicates how long the service is expected to be unavailable to the requesting client. * @return {@code true} if the request processing has been cancelled, returns {@code false} in case the request * processing is not {@link #isSuspended() suspended} and could not be cancelled and is not {@link #isCancelled() * cancelled} already. * @see #cancel * @see #cancel(int) */ public boolean cancel(Date retryAfter); /** * Check if the asynchronous response instance is in a suspended state. * * Method returns {@code true} if this asynchronous response is still suspended and has not finished processing yet * (either by resuming or canceling the response). * * @return {@code true} if this asynchronous response is in a suspend state, {@code false} otherwise. * @see #isCancelled() * @see #isDone() */ public boolean isSuspended(); /** * Check if the asynchronous response instance has been cancelled. * * Method returns {@code true} if this asynchronous response has been canceled before completion. * * @return {@code true} if this task was canceled before completion. * @see #isSuspended() * @see #isDone() */ public boolean isCancelled(); /** * Check if the processing of a request this asynchronous response instance belongs to has finished. * * Method returns {@code true} if the processing of a request this asynchronous response is bound to is finished. *

* The request processing may be finished due to a normal termination, a suspend timeout, or cancellation -- in all of * these cases, this method will return {@code true}. *

* * @return {@code true} if this execution context has finished processing. * @see #isSuspended() * @see #isCancelled() */ public boolean isDone(); /** * Set/update the suspend timeout. *

* The new suspend timeout values override any timeout value previously specified. The asynchronous response must be * still in a {@link #isSuspended() suspended} state for this method to succeed. *

* * @param time suspend timeout value in the give time {@code unit}. Value lower or equal to 0 causes the context to * suspend indefinitely. * @param unit suspend timeout value time unit. * @return {@code true} if the suspend time out has been set, returns {@code false} in case the request processing is * not in the {@link #isSuspended() suspended} state. */ public boolean setTimeout(long time, TimeUnit unit); /** * Set/replace a time-out handler for the suspended asynchronous response. *

* The time-out handler will be invoked when the suspend period of this asynchronous response times out. The job of the * time-out handler is to resolve the time-out situation by either *

*
    *
  • resuming the suspended response
  • *
  • cancelling the suspended response
  • *
  • extending the suspend period by setting a new suspend time-out
  • *
*

* Note that in case the response is suspended {@link #NO_TIMEOUT indefinitely}, the time-out handler may never be * invoked. *

* * @param handler response time-out handler. */ public void setTimeoutHandler(TimeoutHandler handler); /** * Register an asynchronous processing lifecycle callback class to receive lifecycle events for the asynchronous * response based on the implemented callback interfaces. * * @param callback callback class. * @return collection of registered callback interfaces. If the callback class does not implement any recognized * callback interfaces, the returned collection will be empty. * @throws NullPointerException in case the callback class is {@code null}. */ public Collection> register(Class callback); /** * Register asynchronous processing lifecycle callback classes to receive lifecycle events for the asynchronous response * based on the implemented callback interfaces. * * @param callback callback class. * @param callbacks additional callback classes. * @return map of registered classes and the callback interfaces registered for each class. If a callback class does not * implement any recognized callback interfaces, the associated collection of registered interfaces for the class will * be empty. * @throws NullPointerException in case any of the callback classes is {@code null}. */ public Map, Collection>> register(Class callback, Class... callbacks); /** * Register an asynchronous processing lifecycle callback instance to receive lifecycle events for the asynchronous * response based on the implemented callback interfaces. * * @param callback callback instance implementing one or more of the recognized callback interfaces. * @return collection of registered callback interfaces. If the callback class does not implement any recognized * callback interfaces, the returned collection will be empty. * @throws NullPointerException in case the callback instance is {@code null}. */ public Collection> register(Object callback); /** * Register an asynchronous processing lifecycle callback instances to receive lifecycle events for the asynchronous * response based on the implemented callback interfaces. * * @param callback callback instance. * @param callbacks additional callback instances. * @return map of registered classes and the callback interfaces registered for each class. If a callback class does not * implement any recognized callback interfaces, the associated collection of registered interfaces for the class will * be empty. * @throws NullPointerException in case any of the callback instances is {@code null}. */ public Map, Collection>> register(Object callback, Object... callbacks); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy