001/*
002 * Copyright 2002-2018 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.converter;
018
019import java.io.IOException;
020import java.lang.reflect.Type;
021
022import org.springframework.http.HttpInputMessage;
023import org.springframework.http.HttpOutputMessage;
024import org.springframework.http.MediaType;
025import org.springframework.lang.Nullable;
026
027/**
028 * A specialization of {@link HttpMessageConverter} that can convert an HTTP request
029 * into a target object of a specified generic type and a source object of a specified
030 * generic type into an HTTP response.
031 *
032 * @author Arjen Poutsma
033 * @author Rossen Stoyanchev
034 * @author Sebastien Deleuze
035 * @since 3.2
036 * @param <T> the converted object type
037 * @see org.springframework.core.ParameterizedTypeReference
038 */
039public interface GenericHttpMessageConverter<T> extends HttpMessageConverter<T> {
040
041        /**
042         * Indicates whether the given type can be read by this converter.
043         * This method should perform the same checks than
044         * {@link HttpMessageConverter#canRead(Class, MediaType)} with additional ones
045         * related to the generic type.
046         * @param type the (potentially generic) type to test for readability
047         * @param contextClass a context class for the target type, for example a class
048         * in which the target type appears in a method signature (can be {@code null})
049         * @param mediaType the media type to read, can be {@code null} if not specified.
050         * Typically the value of a {@code Content-Type} header.
051         * @return {@code true} if readable; {@code false} otherwise
052         */
053        boolean canRead(Type type, @Nullable Class<?> contextClass, @Nullable MediaType mediaType);
054
055        /**
056         * Read an object of the given type form the given input message, and returns it.
057         * @param type the (potentially generic) type of object to return. This type must have
058         * previously been passed to the {@link #canRead canRead} method of this interface,
059         * which must have returned {@code true}.
060         * @param contextClass a context class for the target type, for example a class
061         * in which the target type appears in a method signature (can be {@code null})
062         * @param inputMessage the HTTP input message to read from
063         * @return the converted object
064         * @throws IOException in case of I/O errors
065         * @throws HttpMessageNotReadableException in case of conversion errors
066         */
067        T read(Type type, @Nullable Class<?> contextClass, HttpInputMessage inputMessage)
068                        throws IOException, HttpMessageNotReadableException;
069
070        /**
071         * Indicates whether the given class can be written by this converter.
072         * <p>This method should perform the same checks than
073         * {@link HttpMessageConverter#canWrite(Class, MediaType)} with additional ones
074         * related to the generic type.
075         * @param type the (potentially generic) type to test for writability
076         * (can be {@code null} if not specified)
077         * @param clazz the source object class to test for writability
078         * @param mediaType the media type to write (can be {@code null} if not specified);
079         * typically the value of an {@code Accept} header.
080         * @return {@code true} if writable; {@code false} otherwise
081         * @since 4.2
082         */
083        boolean canWrite(@Nullable Type type, Class<?> clazz, @Nullable MediaType mediaType);
084
085        /**
086         * Write an given object to the given output message.
087         * @param t the object to write to the output message. The type of this object must
088         * have previously been passed to the {@link #canWrite canWrite} method of this
089         * interface, which must have returned {@code true}.
090         * @param type the (potentially generic) type of object to write. This type must have
091         * previously been passed to the {@link #canWrite canWrite} method of this interface,
092         * which must have returned {@code true}. Can be {@code null} if not specified.
093         * @param contentType the content type to use when writing. May be {@code null} to
094         * indicate that the default content type of the converter must be used. If not
095         * {@code null}, this media type must have previously been passed to the
096         * {@link #canWrite canWrite} method of this interface, which must have returned
097         * {@code true}.
098         * @param outputMessage the message to write to
099         * @throws IOException in case of I/O errors
100         * @throws HttpMessageNotWritableException in case of conversion errors
101         * @since 4.2
102         */
103        void write(T t, @Nullable Type type, @Nullable MediaType contentType, HttpOutputMessage outputMessage)
104                        throws IOException, HttpMessageNotWritableException;
105
106}