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}