https://github.com/spring-projects/spring-framework: Spring Core (Spring IO)
  • Juergen Hoeller 
/*
 * Copyright 2002-2017 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.core.convert;

import org.springframework.lang.Nullable;


A service interface for type conversion. This is the entry point into the convert system. Call convert(Object, Class<Object>) to perform a thread-safe type conversion using this system. 
Author:Keith Donald, Phillip Webb
Since:3.0
/**
 * A service interface for type conversion. This is the entry point into the convert system.
 * Call {@link #convert(Object, Class)} to perform a thread-safe type conversion using this system.
 *
 * @author Keith Donald
 * @author Phillip Webb
 * @since 3.0
 */
public interface ConversionService {

	
Return true if objects of sourceType can be converted to the targetType. 
If this method returns true, it means convert(Object, Class<Object>) is capable of converting an instance of sourceType to targetType. 
Special note on collections, arrays, and maps types: For conversion between collection, array, and map types, this method will return true even though a convert invocation may still generate a ConversionException if the underlying elements are not convertible. Callers are expected to handle this exceptional case when working with collections and maps. 
Params:
  • sourceType – the source type to convert from (may be null if source is null)
  • targetType – the target type to convert to (required)
Throws:
Returns:true if a conversion can be performed, false if not
/**
	 * Return {@code true} if objects of {@code sourceType} can be converted to the {@code targetType}.
	 * <p>If this method returns {@code true}, it means {@link #convert(Object, Class)} is capable
	 * of converting an instance of {@code sourceType} to {@code targetType}.
	 * <p>Special note on collections, arrays, and maps types:
	 * For conversion between collection, array, and map types, this method will return {@code true}
	 * even though a convert invocation may still generate a {@link ConversionException} if the
	 * underlying elements are not convertible. Callers are expected to handle this exceptional case
	 * when working with collections and maps.
	 * @param sourceType the source type to convert from (may be {@code null} if source is {@code null})
	 * @param targetType the target type to convert to (required)
	 * @return {@code true} if a conversion can be performed, {@code false} if not
	 * @throws IllegalArgumentException if {@code targetType} is {@code null}
	 */
	boolean canConvert(@Nullable Class<?> sourceType, Class<?> targetType);

	
Return true if objects of sourceType can be converted to the targetType. The TypeDescriptors provide additional context about the source and target locations where conversion would occur, often object fields or property locations. 
If this method returns true, it means convert(Object, TypeDescriptor, TypeDescriptor) is capable of converting an instance of sourceType to targetType. 
Special note on collections, arrays, and maps types: For conversion between collection, array, and map types, this method will return true even though a convert invocation may still generate a ConversionException if the underlying elements are not convertible. Callers are expected to handle this exceptional case when working with collections and maps. 
Params:
  • sourceType – context about the source type to convert from (may be null if source is null)
  • targetType – context about the target type to convert to (required)
Throws:
Returns:true if a conversion can be performed between the source and target types, false if not
/**
	 * Return {@code true} if objects of {@code sourceType} can be converted to the {@code targetType}.
	 * The TypeDescriptors provide additional context about the source and target locations
	 * where conversion would occur, often object fields or property locations.
	 * <p>If this method returns {@code true}, it means {@link #convert(Object, TypeDescriptor, TypeDescriptor)}
	 * is capable of converting an instance of {@code sourceType} to {@code targetType}.
	 * <p>Special note on collections, arrays, and maps types:
	 * For conversion between collection, array, and map types, this method will return {@code true}
	 * even though a convert invocation may still generate a {@link ConversionException} if the
	 * underlying elements are not convertible. Callers are expected to handle this exceptional case
	 * when working with collections and maps.
	 * @param sourceType context about the source type to convert from
	 * (may be {@code null} if source is {@code null})
	 * @param targetType context about the target type to convert to (required)
	 * @return {@code true} if a conversion can be performed between the source and target types,
	 * {@code false} if not
	 * @throws IllegalArgumentException if {@code targetType} is {@code null}
	 */
	boolean canConvert(@Nullable TypeDescriptor sourceType, TypeDescriptor targetType);

	
Convert the given source to the specified targetType. 
Params:
  • source – the source object to convert (may be null)
  • targetType – the target type to convert to (required)
Throws:
Returns:the converted object, an instance of targetType
/**
	 * Convert the given {@code source} to the specified {@code targetType}.
	 * @param source the source object to convert (may be {@code null})
	 * @param targetType the target type to convert to (required)
	 * @return the converted object, an instance of targetType
	 * @throws ConversionException if a conversion exception occurred
	 * @throws IllegalArgumentException if targetType is {@code null}
	 */
	@Nullable
	<T> T convert(@Nullable Object source, Class<T> targetType);

	
Convert the given source to the specified targetType. The TypeDescriptors provide additional context about the source and target locations where conversion will occur, often object fields or property locations. 
Params:
  • source – the source object to convert (may be null)
  • sourceType – context about the source type to convert from (may be null if source is null)
  • targetType – context about the target type to convert to (required)
Throws:
Returns:the converted object, an instance of targetType
/**
	 * Convert the given {@code source} to the specified {@code targetType}.
	 * The TypeDescriptors provide additional context about the source and target locations
	 * where conversion will occur, often object fields or property locations.
	 * @param source the source object to convert (may be {@code null})
	 * @param sourceType context about the source type to convert from
	 * (may be {@code null} if source is {@code null})
	 * @param targetType context about the target type to convert to (required)
	 * @return the converted object, an instance of {@link TypeDescriptor#getObjectType() targetType}
	 * @throws ConversionException if a conversion exception occurred
	 * @throws IllegalArgumentException if targetType is {@code null},
	 * or {@code sourceType} is {@code null} but source is not {@code null}
	 */
	@Nullable
	Object convert(@Nullable Object source, @Nullable TypeDescriptor sourceType, TypeDescriptor targetType);

}