1 /*
2 * Copyright 2002-2013 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.beans;
18
19 import java.lang.reflect.Field;
20
21 import org.springframework.core.MethodParameter;
22
23 /**
24 * Interface that defines type conversion methods. Typically (but not necessarily)
25 * implemented in conjunction with the {@link PropertyEditorRegistry} interface.
26 *
27 * <p><b>Note:</b> Since TypeConverter implementations are typically based on
28 * {@link java.beans.PropertyEditor PropertyEditors} which aren't thread-safe,
29 * TypeConverters themselves are <em>not</em> to be considered as thread-safe either.
30 *
31 * @author Juergen Hoeller
32 * @since 2.0
33 * @see SimpleTypeConverter
34 * @see BeanWrapperImpl
35 */
36 public interface TypeConverter {
37
38 /**
39 * Convert the value to the required type (if necessary from a String).
40 * <p>Conversions from String to any type will typically use the {@code setAsText}
41 * method of the PropertyEditor class, or a Spring Converter in a ConversionService.
42 * @param value the value to convert
43 * @param requiredType the type we must convert to
44 * (or {@code null} if not known, for example in case of a collection element)
45 * @return the new value, possibly the result of type conversion
46 * @throws TypeMismatchException if type conversion failed
47 * @see java.beans.PropertyEditor#setAsText(String)
48 * @see java.beans.PropertyEditor#getValue()
49 * @see org.springframework.core.convert.ConversionService
50 * @see org.springframework.core.convert.converter.Converter
51 */
52 <T> T convertIfNecessary(Object value, Class<T> requiredType) throws TypeMismatchException;
53
54 /**
55 * Convert the value to the required type (if necessary from a String).
56 * <p>Conversions from String to any type will typically use the {@code setAsText}
57 * method of the PropertyEditor class, or a Spring Converter in a ConversionService.
58 * @param value the value to convert
59 * @param requiredType the type we must convert to
60 * (or {@code null} if not known, for example in case of a collection element)
61 * @param methodParam the method parameter that is the target of the conversion
62 * (for analysis of generic types; may be {@code null})
63 * @return the new value, possibly the result of type conversion
64 * @throws TypeMismatchException if type conversion failed
65 * @see java.beans.PropertyEditor#setAsText(String)
66 * @see java.beans.PropertyEditor#getValue()
67 * @see org.springframework.core.convert.ConversionService
68 * @see org.springframework.core.convert.converter.Converter
69 */
70 <T> T convertIfNecessary(Object value, Class<T> requiredType, MethodParameter methodParam)
71 throws TypeMismatchException;
72
73 /**
74 * Convert the value to the required type (if necessary from a String).
75 * <p>Conversions from String to any type will typically use the {@code setAsText}
76 * method of the PropertyEditor class, or a Spring Converter in a ConversionService.
77 * @param value the value to convert
78 * @param requiredType the type we must convert to
79 * (or {@code null} if not known, for example in case of a collection element)
80 * @param field the reflective field that is the target of the conversion
81 * (for analysis of generic types; may be {@code null})
82 * @return the new value, possibly the result of type conversion
83 * @throws TypeMismatchException if type conversion failed
84 * @see java.beans.PropertyEditor#setAsText(String)
85 * @see java.beans.PropertyEditor#getValue()
86 * @see org.springframework.core.convert.ConversionService
87 * @see org.springframework.core.convert.converter.Converter
88 */
89 <T> T convertIfNecessary(Object value, Class<T> requiredType, Field field)
90 throws TypeMismatchException;
91
92 }