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