001/* 002 * Copyright 2002-2016 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.core.convert; 018 019/** 020 * A service interface for type conversion. This is the entry point into the convert system. 021 * Call {@link #convert(Object, Class)} to perform a thread-safe type conversion using this system. 022 * 023 * @author Keith Donald 024 * @author Phillip Webb 025 * @since 3.0 026 */ 027public interface ConversionService { 028 029 /** 030 * Return {@code true} if objects of {@code sourceType} can be converted to the {@code targetType}. 031 * <p>If this method returns {@code true}, it means {@link #convert(Object, Class)} is capable 032 * of converting an instance of {@code sourceType} to {@code targetType}. 033 * <p>Special note on collections, arrays, and maps types: 034 * For conversion between collection, array, and map types, this method will return {@code true} 035 * even though a convert invocation may still generate a {@link ConversionException} if the 036 * underlying elements are not convertible. Callers are expected to handle this exceptional case 037 * when working with collections and maps. 038 * @param sourceType the source type to convert from (may be {@code null} if source is {@code null}) 039 * @param targetType the target type to convert to (required) 040 * @return {@code true} if a conversion can be performed, {@code false} if not 041 * @throws IllegalArgumentException if {@code targetType} is {@code null} 042 */ 043 boolean canConvert(Class<?> sourceType, Class<?> targetType); 044 045 /** 046 * Return {@code true} if objects of {@code sourceType} can be converted to the {@code targetType}. 047 * The TypeDescriptors provide additional context about the source and target locations 048 * where conversion would occur, often object fields or property locations. 049 * <p>If this method returns {@code true}, it means {@link #convert(Object, TypeDescriptor, TypeDescriptor)} 050 * is capable of converting an instance of {@code sourceType} to {@code targetType}. 051 * <p>Special note on collections, arrays, and maps types: 052 * For conversion between collection, array, and map types, this method will return {@code true} 053 * even though a convert invocation may still generate a {@link ConversionException} if the 054 * underlying elements are not convertible. Callers are expected to handle this exceptional case 055 * when working with collections and maps. 056 * @param sourceType context about the source type to convert from 057 * (may be {@code null} if source is {@code null}) 058 * @param targetType context about the target type to convert to (required) 059 * @return {@code true} if a conversion can be performed between the source and target types, 060 * {@code false} if not 061 * @throws IllegalArgumentException if {@code targetType} is {@code null} 062 */ 063 boolean canConvert(TypeDescriptor sourceType, TypeDescriptor targetType); 064 065 /** 066 * Convert the given {@code source} to the specified {@code targetType}. 067 * @param source the source object to convert (may be {@code null}) 068 * @param targetType the target type to convert to (required) 069 * @return the converted object, an instance of targetType 070 * @throws ConversionException if a conversion exception occurred 071 * @throws IllegalArgumentException if targetType is {@code null} 072 */ 073 <T> T convert(Object source, Class<T> targetType); 074 075 /** 076 * Convert the given {@code source} to the specified {@code targetType}. 077 * The TypeDescriptors provide additional context about the source and target locations 078 * where conversion will occur, often object fields or property locations. 079 * @param source the source object to convert (may be {@code null}) 080 * @param sourceType context about the source type to convert from 081 * (may be {@code null} if source is {@code null}) 082 * @param targetType context about the target type to convert to (required) 083 * @return the converted object, an instance of {@link TypeDescriptor#getObjectType() targetType} 084 * @throws ConversionException if a conversion exception occurred 085 * @throws IllegalArgumentException if targetType is {@code null}, 086 * or {@code sourceType} is {@code null} but source is not {@code null} 087 */ 088 Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType); 089 090}