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