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.beans;
018
019import java.lang.reflect.Field;
020
021import org.springframework.core.MethodParameter;
022import org.springframework.core.convert.TypeDescriptor;
023import org.springframework.lang.Nullable;
024
025/**
026 * Interface that defines type conversion methods. Typically (but not necessarily)
027 * implemented in conjunction with the {@link PropertyEditorRegistry} interface.
028 *
029 * <p><b>Note:</b> Since TypeConverter implementations are typically based on
030 * {@link java.beans.PropertyEditor PropertyEditors} which aren't thread-safe,
031 * TypeConverters themselves are <em>not</em> to be considered as thread-safe either.
032 *
033 * @author Juergen Hoeller
034 * @since 2.0
035 * @see SimpleTypeConverter
036 * @see BeanWrapperImpl
037 */
038public interface TypeConverter {
039
040        /**
041         * Convert the value to the required type (if necessary from a String).
042         * <p>Conversions from String to any type will typically use the {@code setAsText}
043         * method of the PropertyEditor class, or a Spring Converter in a ConversionService.
044         * @param value the value to convert
045         * @param requiredType the type we must convert to
046         * (or {@code null} if not known, for example in case of a collection element)
047         * @return the new value, possibly the result of type conversion
048         * @throws TypeMismatchException if type conversion failed
049         * @see java.beans.PropertyEditor#setAsText(String)
050         * @see java.beans.PropertyEditor#getValue()
051         * @see org.springframework.core.convert.ConversionService
052         * @see org.springframework.core.convert.converter.Converter
053         */
054        @Nullable
055        <T> T convertIfNecessary(@Nullable Object value, @Nullable Class<T> requiredType) throws TypeMismatchException;
056
057        /**
058         * Convert the value to the required type (if necessary from a String).
059         * <p>Conversions from String to any type will typically use the {@code setAsText}
060         * method of the PropertyEditor class, or a Spring Converter in a ConversionService.
061         * @param value the value to convert
062         * @param requiredType the type we must convert to
063         * (or {@code null} if not known, for example in case of a collection element)
064         * @param methodParam the method parameter that is the target of the conversion
065         * (for analysis of generic types; may be {@code null})
066         * @return the new value, possibly the result of type conversion
067         * @throws TypeMismatchException if type conversion failed
068         * @see java.beans.PropertyEditor#setAsText(String)
069         * @see java.beans.PropertyEditor#getValue()
070         * @see org.springframework.core.convert.ConversionService
071         * @see org.springframework.core.convert.converter.Converter
072         */
073        @Nullable
074        <T> T convertIfNecessary(@Nullable Object value, @Nullable Class<T> requiredType,
075                        @Nullable MethodParameter methodParam) throws TypeMismatchException;
076
077        /**
078         * Convert the value to the required type (if necessary from a String).
079         * <p>Conversions from String to any type will typically use the {@code setAsText}
080         * method of the PropertyEditor class, or a Spring Converter in a ConversionService.
081         * @param value the value to convert
082         * @param requiredType the type we must convert to
083         * (or {@code null} if not known, for example in case of a collection element)
084         * @param field the reflective field that is the target of the conversion
085         * (for analysis of generic types; may be {@code null})
086         * @return the new value, possibly the result of type conversion
087         * @throws TypeMismatchException if type conversion failed
088         * @see java.beans.PropertyEditor#setAsText(String)
089         * @see java.beans.PropertyEditor#getValue()
090         * @see org.springframework.core.convert.ConversionService
091         * @see org.springframework.core.convert.converter.Converter
092         */
093        @Nullable
094        <T> T convertIfNecessary(@Nullable Object value, @Nullable Class<T> requiredType, @Nullable Field field)
095                        throws TypeMismatchException;
096
097        /**
098         * Convert the value to the required type (if necessary from a String).
099         * <p>Conversions from String to any type will typically use the {@code setAsText}
100         * method of the PropertyEditor class, or a Spring Converter in a ConversionService.
101         * @param value the value to convert
102         * @param requiredType the type we must convert to
103         * (or {@code null} if not known, for example in case of a collection element)
104         * @param typeDescriptor the type descriptor to use (may be {@code null}))
105         * @return the new value, possibly the result of type conversion
106         * @throws TypeMismatchException if type conversion failed
107         * @since 5.1.4
108         * @see java.beans.PropertyEditor#setAsText(String)
109         * @see java.beans.PropertyEditor#getValue()
110         * @see org.springframework.core.convert.ConversionService
111         * @see org.springframework.core.convert.converter.Converter
112         */
113        @Nullable
114        default <T> T convertIfNecessary(@Nullable Object value, @Nullable Class<T> requiredType,
115                        @Nullable TypeDescriptor typeDescriptor) throws TypeMismatchException {
116
117                throw new UnsupportedOperationException("TypeDescriptor resolution not supported");
118        }
119
120}