diff --git a/spring-core/src/main/java/org/springframework/core/convert/converter/ConditionalGenericConverter.java b/spring-core/src/main/java/org/springframework/core/convert/converter/ConditionalGenericConverter.java index 56dadbfc45..dca0720f4e 100644 --- a/spring-core/src/main/java/org/springframework/core/convert/converter/ConditionalGenericConverter.java +++ b/spring-core/src/main/java/org/springframework/core/convert/converter/ConditionalGenericConverter.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2014 the original author or authors. + * Copyright 2002-2015 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. @@ -21,7 +21,8 @@ import org.springframework.core.convert.TypeDescriptor; /** * A {@link GenericConverter} that may conditionally execute based on attributes * of the {@code source} and {@code target} {@link TypeDescriptor}. - * See {@link ConditionalConverter} for details. + * + *

See {@link ConditionalConverter} for details. * * @author Keith Donald * @author Phillip Webb diff --git a/spring-core/src/main/java/org/springframework/core/convert/converter/Converter.java b/spring-core/src/main/java/org/springframework/core/convert/converter/Converter.java index cfb578c11a..0223b5d400 100644 --- a/spring-core/src/main/java/org/springframework/core/convert/converter/Converter.java +++ b/spring-core/src/main/java/org/springframework/core/convert/converter/Converter.java @@ -17,23 +17,24 @@ package org.springframework.core.convert.converter; /** - * A converter converts a source object of type S to a target of type T. - * Implementations of this interface are thread-safe and can be shared. + * A converter converts a source object of type {@code S} to a target of type {@code T}. + * + *

Implementations of this interface are thread-safe and can be shared. * *

Implementations may additionally implement {@link ConditionalConverter}. * * @author Keith Donald * @since 3.0 - * @param The source type - * @param The target type + * @param the source type + * @param the target type */ public interface Converter { /** - * Convert the source of type S to target type T. - * @param source the source object to convert, which must be an instance of S (never {@code null}) - * @return the converted object, which must be an instance of T (potentially {@code null}) - * @throws IllegalArgumentException if the source could not be converted to the desired target type + * Convert the source object of type {@code S} to target type {@code T}. + * @param source the source object to convert, which must be an instance of {@code S} (never {@code null}) + * @return the converted object, which must be an instance of {@code T} (potentially {@code null}) + * @throws IllegalArgumentException if the source cannot be converted to the desired target type */ T convert(S source); diff --git a/spring-core/src/main/java/org/springframework/core/convert/converter/GenericConverter.java b/spring-core/src/main/java/org/springframework/core/convert/converter/GenericConverter.java index 65d1def81f..11bc2945a7 100644 --- a/spring-core/src/main/java/org/springframework/core/convert/converter/GenericConverter.java +++ b/spring-core/src/main/java/org/springframework/core/convert/converter/GenericConverter.java @@ -29,10 +29,10 @@ import org.springframework.util.Assert; * type pairs (see {@link #getConvertibleTypes()}. In addition, GenericConverter implementations * have access to source/target {@link TypeDescriptor field context} during the type conversion * process. This allows for resolving source and target field metadata such as annotations and - * generics information, which can be used influence the conversion logic. + * generics information, which can be used to influence the conversion logic. * *

This interface should generally not be used when the simpler {@link Converter} or - * {@link ConverterFactory} interfaces are sufficient. + * {@link ConverterFactory} interface is sufficient. * *

Implementations may additionally implement {@link ConditionalConverter}. * @@ -47,16 +47,16 @@ import org.springframework.util.Assert; public interface GenericConverter { /** - * Return the source and target types which this converter can convert between. Each - * entry is a convertible source-to-target type pair. - *

For {@link ConditionalConverter conditional} converters this method may return + * Return the source and target types that this converter can convert between. + *

Each entry is a convertible source-to-target type pair. + *

For {@link ConditionalConverter conditional converters} this method may return * {@code null} to indicate all source-to-target pairs should be considered. */ Set getConvertibleTypes(); /** - * Convert the source to the targetType described by the TypeDescriptor. - * @param source the source object to convert (may be null) + * Convert the source object to the targetType described by the {@code TypeDescriptor}. + * @param source the source object to convert (may be {@code null}) * @param sourceType the type descriptor of the field we are converting from * @param targetType the type descriptor of the field we are converting to * @return the converted object diff --git a/spring-core/src/main/java/org/springframework/core/convert/support/FallbackObjectToStringConverter.java b/spring-core/src/main/java/org/springframework/core/convert/support/FallbackObjectToStringConverter.java index 90f1575485..7de6d62578 100644 --- a/spring-core/src/main/java/org/springframework/core/convert/support/FallbackObjectToStringConverter.java +++ b/spring-core/src/main/java/org/springframework/core/convert/support/FallbackObjectToStringConverter.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 the original author or authors. + * Copyright 2002-2015 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. @@ -25,12 +25,15 @@ import org.springframework.core.convert.converter.ConditionalGenericConverter; import org.springframework.util.ClassUtils; /** - * Simply calls {@link Object#toString()} to convert any supported Object to a String. - * Supports CharSequence, StringWriter, and any class with a String constructor or - * {@code valueOf(String)} method. + * Simply calls {@link Object#toString()} to convert any supported object + * to a {@link String}. * - *

Used by the default ConversionService as a fallback if there are no other explicit - * to-String converters registered. + *

Supports {@link CharSequence}, {@link StringWriter}, and any class + * with a String constructor or one of the following static factory methods: + * {@code valueOf(String)}, {@code of(String)}, {@code from(String)}. + * + *

Used by the {@link DefaultConversionService} as a fallback if there + * are no other explicit to-String converters registered. * * @author Keith Donald * @author Juergen Hoeller diff --git a/spring-core/src/main/java/org/springframework/core/convert/support/ObjectToObjectConverter.java b/spring-core/src/main/java/org/springframework/core/convert/support/ObjectToObjectConverter.java index a7df486600..7b83374fa0 100644 --- a/spring-core/src/main/java/org/springframework/core/convert/support/ObjectToObjectConverter.java +++ b/spring-core/src/main/java/org/springframework/core/convert/support/ObjectToObjectConverter.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 the original author or authors. + * Copyright 2002-2015 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. @@ -29,14 +29,23 @@ import org.springframework.util.ClassUtils; import org.springframework.util.ReflectionUtils; /** - * Generic converter that attempts to convert a source Object to a target type - * by delegating to methods on the target type. + * Generic converter that uses conventions to convert a source object to a + * {@code targetType} by delegating to a method on the source object or to + * a static factory method or constructor on the {@code targetType}. * - *

Calls a static {@code valueOf(sourceType)} or Java 8 style {@code of|from(sourceType)} - * method on the target type to perform the conversion, if such a method exists. Otherwise, - * it checks for a {@code to[targetType.simpleName]} method on the source type calls - * the target type's constructor that accepts a single {@code sourceType} argument, if such - * a constructor exists. If neither strategy works, it throws a ConversionFailedException. + *

Conversion Algorithm

+ *
    + *
  1. Invoke a {@code to[targetType.simpleName]()} method on the source object + * that has a return type equal to {@code targetType}, if such a method exists. + * For example, {@code org.example.Bar Foo#toBar()} is a method that follows this + * convention. + *
  2. Otherwise invoke a static {@code valueOf(sourceType)} or Java + * 8 style static {@code of(sourceType)} or {@code from(sourceType)} + * method on the {@code targetType}, if such a method exists. + *
  3. Otherwise invoke a constructor on the {@code targetType} that accepts + * a single {@code sourceType} argument, if such a constructor exists. + *
  4. Otherwise throw a {@link ConversionFailedException}. + *
* * @author Keith Donald * @author Juergen Hoeller