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