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