001/*
002 * Copyright 2002-2017 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.web.context.request.async;
018
019import org.springframework.web.context.request.NativeWebRequest;
020
021/**
022 * Intercepts concurrent request handling, where the concurrent result is
023 * obtained by waiting for a {@link DeferredResult} to be set from a thread
024 * chosen by the application (e.g. in response to some external event).
025 *
026 * <p>A {@code DeferredResultProcessingInterceptor} is invoked before the start
027 * of async processing, after the {@code DeferredResult} is set as well as on
028 * timeout/error, or after completing for any reason including a timeout or network
029 * error.
030 *
031 * <p>As a general rule exceptions raised by interceptor methods will cause
032 * async processing to resume by dispatching back to the container and using
033 * the Exception instance as the concurrent result. Such exceptions will then
034 * be processed through the {@code HandlerExceptionResolver} mechanism.
035 *
036 * <p>The {@link #handleTimeout(NativeWebRequest, DeferredResult) handleTimeout}
037 * method can set the {@code DeferredResult} in order to resume processing.
038 *
039 * @author Rossen Stoyanchev
040 * @author Rob Winch
041 * @since 3.2
042 */
043public interface DeferredResultProcessingInterceptor {
044
045        /**
046         * Invoked immediately before the start of concurrent handling, in the same
047         * thread that started it. This method may be used to capture state just prior
048         * to the start of concurrent processing with the given {@code DeferredResult}.
049         * @param request the current request
050         * @param deferredResult the DeferredResult for the current request
051         * @throws Exception in case of errors
052         */
053        default <T> void beforeConcurrentHandling(NativeWebRequest request, DeferredResult<T> deferredResult)
054                        throws Exception {
055        }
056
057        /**
058         * Invoked immediately after the start of concurrent handling, in the same
059         * thread that started it. This method may be used to detect the start of
060         * concurrent processing with the given {@code DeferredResult}.
061         * <p>The {@code DeferredResult} may have already been set, for example at
062         * the time of its creation or by another thread.
063         * @param request the current request
064         * @param deferredResult the DeferredResult for the current request
065         * @throws Exception in case of errors
066         */
067        default <T> void preProcess(NativeWebRequest request, DeferredResult<T> deferredResult)
068                        throws Exception {
069        }
070
071        /**
072         * Invoked after a {@code DeferredResult} has been set, via
073         * {@link DeferredResult#setResult(Object)} or
074         * {@link DeferredResult#setErrorResult(Object)}, and is also ready to
075         * handle the concurrent result.
076         * <p>This method may also be invoked after a timeout when the
077         * {@code DeferredResult} was created with a constructor accepting a default
078         * timeout result.
079         * @param request the current request
080         * @param deferredResult the DeferredResult for the current request
081         * @param concurrentResult the result to which the {@code DeferredResult}
082         * @throws Exception in case of errors
083         */
084        default <T> void postProcess(NativeWebRequest request, DeferredResult<T> deferredResult,
085                        Object concurrentResult) throws Exception {
086        }
087
088        /**
089         * Invoked from a container thread when an async request times out before
090         * the {@code DeferredResult} has been set. Implementations may invoke
091         * {@link DeferredResult#setResult(Object) setResult} or
092         * {@link DeferredResult#setErrorResult(Object) setErrorResult} to resume processing.
093         * @param request the current request
094         * @param deferredResult the DeferredResult for the current request; if the
095         * {@code DeferredResult} is set, then concurrent processing is resumed and
096         * subsequent interceptors are not invoked
097         * @return {@code true} if processing should continue, or {@code false} if
098         * other interceptors should not be invoked
099         * @throws Exception in case of errors
100         */
101        default <T> boolean handleTimeout(NativeWebRequest request, DeferredResult<T> deferredResult)
102                        throws Exception {
103
104                return true;
105        }
106
107        /**
108         * Invoked from a container thread when an error occurred while processing an async request
109         * before the {@code DeferredResult} has been set. Implementations may invoke
110         * {@link DeferredResult#setResult(Object) setResult} or
111         * {@link DeferredResult#setErrorResult(Object) setErrorResult} to resume processing.
112         * @param request the current request
113         * @param deferredResult the DeferredResult for the current request; if the
114         * {@code DeferredResult} is set, then concurrent processing is resumed and
115         * subsequent interceptors are not invoked
116         * @param t the error that occurred while request processing
117         * @return {@code true} if error handling should continue, or {@code false} if
118         * other interceptors should by bypassed and not be invoked
119         * @throws Exception in case of errors
120         */
121        default <T> boolean handleError(NativeWebRequest request, DeferredResult<T> deferredResult,
122                        Throwable t) throws Exception {
123
124                return true;
125        }
126
127        /**
128         * Invoked from a container thread when an async request completed for any
129         * reason including timeout and network error. This method is useful for
130         * detecting that a {@code DeferredResult} instance is no longer usable.
131         * @param request the current request
132         * @param deferredResult the DeferredResult for the current request
133         * @throws Exception in case of errors
134         */
135        default <T> void afterCompletion(NativeWebRequest request, DeferredResult<T> deferredResult)
136                        throws Exception {
137        }
138
139}