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.http.codec;
018
019import java.util.List;
020import java.util.Map;
021
022import org.reactivestreams.Publisher;
023import reactor.core.publisher.Mono;
024
025import org.springframework.core.MethodParameter;
026import org.springframework.core.ResolvableType;
027import org.springframework.http.MediaType;
028import org.springframework.http.ReactiveHttpOutputMessage;
029import org.springframework.http.server.reactive.ServerHttpRequest;
030import org.springframework.http.server.reactive.ServerHttpResponse;
031import org.springframework.lang.Nullable;
032
033/**
034 * Strategy for encoding a stream of objects of type {@code <T>} and writing
035 * the encoded stream of bytes to an {@link ReactiveHttpOutputMessage}.
036 *
037 * @author Rossen Stoyanchev
038 * @author Arjen Poutsma
039 * @author Sebastien Deleuze
040 * @since 5.0
041 * @param <T> the type of objects in the input stream
042 */
043public interface HttpMessageWriter<T> {
044
045        /**
046         * Return the {@link MediaType}'s that this writer supports.
047         */
048        List<MediaType> getWritableMediaTypes();
049
050        /**
051         * Whether the given object type is supported by this writer.
052         * @param elementType the type of object to check
053         * @param mediaType the media type for the write (possibly {@code null})
054         * @return {@code true} if writable, {@code false} otherwise
055         */
056        boolean canWrite(ResolvableType elementType, @Nullable MediaType mediaType);
057
058        /**
059         * Write an given stream of object to the output message.
060         * @param inputStream the objects to write
061         * @param elementType the type of objects in the stream which must have been
062         * previously checked via {@link #canWrite(ResolvableType, MediaType)}
063         * @param mediaType the content type for the write (possibly {@code null} to
064         * indicate that the default content type of the writer must be used)
065         * @param message the message to write to
066         * @param hints additional information about how to encode and write
067         * @return indicates completion or error
068         */
069        Mono<Void> write(Publisher<? extends T> inputStream, ResolvableType elementType,
070                        @Nullable MediaType mediaType, ReactiveHttpOutputMessage message, Map<String, Object> hints);
071
072        /**
073         * Server-side only alternative to
074         * {@link #write(Publisher, ResolvableType, MediaType, ReactiveHttpOutputMessage, Map)}
075         * with additional context available.
076         * @param actualType the actual return type of the method that returned the
077         * value; for annotated controllers, the {@link MethodParameter} can be
078         * accessed via {@link ResolvableType#getSource()}.
079         * @param elementType the type of Objects in the input stream
080         * @param mediaType the content type to use (possibly {@code null} indicating
081         * the default content type of the writer should be used)
082         * @param request the current request
083         * @param response the current response
084         * @return a {@link Mono} that indicates completion of writing or error
085         */
086        default Mono<Void> write(Publisher<? extends T> inputStream, ResolvableType actualType,
087                        ResolvableType elementType, @Nullable MediaType mediaType, ServerHttpRequest request,
088                        ServerHttpResponse response, Map<String, Object> hints) {
089
090                return write(inputStream, elementType, mediaType, response, hints);
091        }
092
093}