Polishing

Issue: SPR-11215

Author: jhoeller

spring-core/src/main/java/org/springframework/core/convert/ConversionService.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2013 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.
@@ -27,36 +27,43 @@
 public interface ConversionService {
 
 	/**
-	 * Returns true if objects of sourceType can be converted to targetType.
-	 * If this method returns true, it means {@link #convert(Object, Class)} 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 {@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 null if source is null)
+	 * 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 true if a conversion can be performed, false if not
-	 * @throws IllegalArgumentException if targetType is null
+	 * @return {@code true} if a conversion can be performed, {@code false} if not
+	 * @throws IllegalArgumentException if {@code targetType} is {@code null}
 	 */
 	boolean canConvert(Class<?> sourceType, Class<?> targetType);
 
 	/**
-	 * Returns 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 {@link #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 {@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 null if source is null)
+	 * 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 true if a conversion can be performed between the source and target types, false if not
-	 * @throws IllegalArgumentException if targetType is null
+	 * @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(TypeDescriptor sourceType, TypeDescriptor targetType);
 
 	/**
-	 * Convert the source to targetType.
+	 * Convert the given {@code source} to the specified {@code targetType}.
 	 * @param source the source object to convert (may be null)
 	 * @param targetType the target type to convert to (required)
 	 * @return the converted object, an instance of targetType
@@ -66,15 +73,17 @@ public interface ConversionService {
 	<T> T convert(Object source, Class<T> targetType);
 
 	/**
-	 * Convert the source to targetType.
-	 * The TypeDescriptors provide additional context about the source and target locations where conversion will occur, often object fields or property locations.
+	 * 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 null)
-	 * @param sourceType context about the source type converting from (may be null if source is 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}</code>
+	 * @return the converted object, an instance of {@link TypeDescriptor#getObjectType() targetType}
 	 * @throws ConversionException if a conversion exception occurred
-	 * @throws IllegalArgumentException if targetType is null
-	 * @throws IllegalArgumentException if sourceType is null but source is not null
+	 * @throws IllegalArgumentException if targetType is {@code null},
+	 * or {@code sourceType} is {@code null} but source is not {@code null}
 	 */
 	Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType);
 

spring-expression/src/main/java/org/springframework/expression/TypeConverter.java

@@ -21,8 +21,8 @@
 /**
  * A type converter can convert values between different types encountered during
  * expression evaluation. This is an SPI for the expression parser; see
- * {@link org.springframework.core.convert.ConversionService} for the primary user API to
- * Spring's conversion facilities.
+ * {@link org.springframework.core.convert.ConversionService} for the primary
+ * user API to Spring's conversion facilities.
  *
  * @author Andy Clement
  * @author Juergen Hoeller
@@ -31,8 +31,8 @@
 public interface TypeConverter {
 
 	/**
-	 * Return true if the type converter can convert the specified type to the desired
-	 * target type.
+	 * Return {@code true} if the type converter can convert the specified type
+	 * to the desired target type.
 	 * @param sourceType a type descriptor that describes the source type
 	 * @param targetType a type descriptor that describes the requested result type
 	 * @return true if that conversion can be performed
@@ -46,9 +46,9 @@ public interface TypeConverter {
 	 * than simply a List.
 	 * @param value the value to be converted
 	 * @param sourceType a type descriptor that supplies extra information about the
-	 *        source object
+	 * source object
 	 * @param targetType a type descriptor that supplies extra information about the
-	 *        requested result type
+	 * requested result type
 	 * @return the converted value
 	 * @throws EvaluationException if conversion is not possible
 	 */

spring-expression/src/main/java/org/springframework/expression/spel/support/StandardTypeConverter.java

@@ -67,11 +67,13 @@ public Object convertValue(Object value, TypeDescriptor sourceType, TypeDescript
 		try {
 			return this.conversionService.convert(value, sourceType, targetType);
 		}
-		catch (ConverterNotFoundException cenfe) {
-			throw new SpelEvaluationException(cenfe, SpelMessage.TYPE_CONVERSION_ERROR, sourceType.toString(), targetType.toString());
+		catch (ConverterNotFoundException ex) {
+			throw new SpelEvaluationException(
+					ex, SpelMessage.TYPE_CONVERSION_ERROR, sourceType.toString(), targetType.toString());
 		}
-		catch (ConversionException ce) {
-			throw new SpelEvaluationException(ce, SpelMessage.TYPE_CONVERSION_ERROR, sourceType.toString(), targetType.toString());
+		catch (ConversionException ex) {
+			throw new SpelEvaluationException(
+					ex, SpelMessage.TYPE_CONVERSION_ERROR, sourceType.toString(), targetType.toString());
 		}
 	}