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}