001/*
002 * Copyright 2002-2019 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.messaging.handler.invocation;
018
019import org.springframework.core.MethodParameter;
020import org.springframework.util.concurrent.ListenableFuture;
021
022/**
023 * An extension of {@link HandlerMethodReturnValueHandler} for handling async,
024 * Future-like return value types that support success and error callbacks.
025 * Essentially anything that can be adapted to a {@link ListenableFuture}.
026 *
027 * <p>Implementations should consider extending the convenient base class
028 * {@link AbstractAsyncReturnValueHandler}.
029 *
030 * @author Rossen Stoyanchev
031 * @since 4.2
032 * @see AbstractAsyncReturnValueHandler
033 */
034public interface AsyncHandlerMethodReturnValueHandler extends HandlerMethodReturnValueHandler {
035
036        /**
037         * Whether the return value represents an asynchronous, Future-like type
038         * with success and error callbacks. If this method returns {@code true},
039         * then {@link #toListenableFuture} is invoked next. If it returns
040         * {@code false}, then {@link #handleReturnValue} is called.
041         * <p><strong>Note:</strong> this method will only be invoked after
042         * {@link #supportsReturnType(org.springframework.core.MethodParameter)}
043         * is called and it returns {@code true}.
044         * @param returnValue the value returned from the handler method
045         * @param returnType the type of the return value
046         * @return {@code true} if the return value type represents an async value
047         */
048        boolean isAsyncReturnValue(Object returnValue, MethodParameter returnType);
049
050        /**
051         * Adapt the asynchronous return value to a {@link ListenableFuture}.
052         * Implementations should consider returning an instance of
053         * {@link org.springframework.util.concurrent.SettableListenableFuture
054         * SettableListenableFuture}. Return value handling will then continue when
055         * the ListenableFuture is completed with either success or error.
056         * <p><strong>Note:</strong> this method will only be invoked after
057         * {@link #supportsReturnType(org.springframework.core.MethodParameter)}
058         * is called and it returns {@code true}.
059         * @param returnValue the value returned from the handler method
060         * @param returnType the type of the return value
061         * @return the resulting ListenableFuture, or {@code null} in which case
062         * no further handling will be performed
063         */
064        ListenableFuture<?> toListenableFuture(Object returnValue, MethodParameter returnType);
065
066}