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}