javadoc polishing

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@2626 50f2f4bb-b051-0410-bef5-90022cba6387

org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToArrayConverter.java

@@ -25,7 +25,9 @@ import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.core.convert.converter.ConditionalGenericConverter;
 
 /**
- * Converts from a Map to an array.
+ * Converts a Map to an Array.
+ * First converts the source Map to a Collection, then converts that Collection to an Array.
+ * Delegates to {@link MapToCollectionConverter} and {@link CollectionToArrayConverter} helpers to do this.
  *
  * @author Keith Donald
  * @since 3.0

org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToCollectionConverter.java

@@ -28,7 +28,12 @@ import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.core.convert.converter.ConditionalGenericConverter;
 
 /**
- * Converts from a Map to a Collection.
+ * Converts a Map to a Collection.
+ * First, creates a new Collection of the requested targetType with a size equal to the size of the source Map.
+ * Then copies each element in the source map to the target collection.
+ * During the copy process, if the target collection's parameterized type is a String, each Map entry is first encoded as a "key=value" property String, then added to the Collection.
+ * If the collection type is another Object type, the value of each Map entry is added to the Collection.
+ * Will perform a conversion from the source maps's parameterized K,V types to the target collection's parameterized type if necessary.
  *
  * @author Keith Donald
  * @since 3.0

org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToMapConverter.java

@@ -27,7 +27,10 @@ import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.core.convert.converter.ConditionalGenericConverter;
 
 /**
- * Converts from a source Map to a target Map type.
+ * Converts a Map to another Map.
+ * First, creates a new Map of the requested targetType with a size equal to the size of the source Map.
+ * Then copies each element in the source map to the target map.
+ * Will perform a conversion from the source maps's parameterized K,V types to the target map's parameterized types K,V if necessary.
  *
  * @author Keith Donald
  * @since 3.0

org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToObjectConverter.java

@@ -16,20 +16,15 @@
 
 package org.springframework.core.convert.support;
 
-import static org.springframework.core.convert.support.ConversionUtils.getMapEntryTypes;
-
-import java.io.ByteArrayOutputStream;
-import java.io.IOException;
 import java.util.Collections;
 import java.util.Map;
-import java.util.Properties;
 import java.util.Set;
 
 import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.core.convert.converter.ConditionalGenericConverter;
 
 /**
- * Converts from a Map to a single Object.
+ * Converts a Map to an Object by returning the first Map entry value after converting it to the desired targetType.
  *
  * @author Keith Donald
  * @since 3.0
@@ -47,8 +42,8 @@ final class MapToObjectConverter implements ConditionalGenericConverter {
 	}
 
 	public boolean matches(TypeDescriptor sourceType, TypeDescriptor targetType) {
-		return this.conversionService.canConvert(sourceType.getMapKeyTypeDescriptor(), targetType) &&
-			this.conversionService.canConvert(sourceType.getMapValueTypeDescriptor(), targetType);
+		return this.conversionService.canConvert(sourceType.getMapKeyTypeDescriptor(), targetType)
+				&& this.conversionService.canConvert(sourceType.getMapValueTypeDescriptor(), targetType);
 	}
 
 	public Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType) {
@@ -57,76 +52,25 @@ final class MapToObjectConverter implements ConditionalGenericConverter {
 		}
 		Map<?, ?> sourceMap = (Map<?, ?>) source;
 		if (sourceMap.size() == 0) {
-			if (targetType.typeEquals(String.class)) {
-				return "";
-			} else {
-				return null;
-			}
+			return null;
 		} else {
-			if (targetType.typeEquals(String.class)) {
-				TypeDescriptor sourceKeyType = sourceType.getMapKeyTypeDescriptor();
-				TypeDescriptor sourceValueType = sourceType.getMapValueTypeDescriptor();
-				if (sourceKeyType == TypeDescriptor.NULL || sourceValueType == TypeDescriptor.NULL) {
-					TypeDescriptor[] sourceEntryTypes = getMapEntryTypes(sourceMap);
-					sourceKeyType = sourceEntryTypes[0];
-					sourceValueType = sourceEntryTypes[1];
-				}
-				boolean keysCompatible = false;
-				if (sourceKeyType != TypeDescriptor.NULL && sourceKeyType.isAssignableTo(targetType)) {
-					keysCompatible = true;
-				}
-				boolean valuesCompatible = false;
-				if (sourceValueType != TypeDescriptor.NULL && sourceValueType.isAssignableTo(targetType)) {
-					valuesCompatible = true;
-				}
-				Properties props = new Properties();
-				if (keysCompatible && valuesCompatible) {
-					for (Object entry : sourceMap.entrySet()) {
-						Map.Entry<?, ?> mapEntry = (Map.Entry<?, ?>) entry;
-						props.setProperty((String) mapEntry.getKey(), (String) mapEntry.getValue());
-					}
-					return store(props);
-				} else {
-					MapEntryConverter converter = new MapEntryConverter(sourceKeyType, sourceValueType, targetType,
-							targetType, keysCompatible, valuesCompatible, this.conversionService);
-					for (Object entry : sourceMap.entrySet()) {
-						Map.Entry<?, ?> mapEntry = (Map.Entry<?, ?>) entry;
-						Object key = converter.convertKey(mapEntry.getKey());
-						Object value = converter.convertValue(mapEntry.getValue());
-						props.setProperty((String) key, (String) value);
-					}
-					return store(props);
-				}
+			Object firstValue = sourceMap.values().iterator().next();
+			TypeDescriptor sourceValueType = sourceType.getMapValueTypeDescriptor();
+			if (sourceValueType == TypeDescriptor.NULL) {
+				sourceValueType = TypeDescriptor.forObject(firstValue);
+			}
+			boolean valuesCompatible = false;
+			if (sourceValueType != TypeDescriptor.NULL && sourceValueType.isAssignableTo(targetType)) {
+				valuesCompatible = true;
+			}
+			if (valuesCompatible) {
+				return firstValue;
 			} else {
-				Object firstValue = sourceMap.values().iterator().next();
-				TypeDescriptor sourceValueType = sourceType.getMapValueTypeDescriptor();
-				if (sourceValueType == TypeDescriptor.NULL) {
-					sourceValueType = TypeDescriptor.forObject(firstValue);
-				}
-				boolean valuesCompatible = false;
-				if (sourceValueType != TypeDescriptor.NULL && sourceValueType.isAssignableTo(targetType)) {
-					valuesCompatible = true;
-				}
-				if (valuesCompatible) {
-					return firstValue;
-				} else {
-					MapEntryConverter converter = new MapEntryConverter(sourceValueType, sourceValueType, targetType,
-							targetType, true, valuesCompatible, this.conversionService);
-					return converter.convertValue(firstValue);
-				}
+				MapEntryConverter converter = new MapEntryConverter(sourceValueType, sourceValueType, targetType,
+						targetType, true, valuesCompatible, this.conversionService);
+				return converter.convertValue(firstValue);
 			}
 		}
 	}
 
-	private String store(Properties props) {
-		try {
-			ByteArrayOutputStream os = new ByteArrayOutputStream();
-			props.store(os, null);
-			return os.toString("ISO-8859-1");
-		} catch (IOException e) {
-			// Should never happen.
-			throw new IllegalArgumentException("Failed to store [" + props + "] into String", e);
-		}
-	}
-
 }

org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToStringConverter.java

@@ -29,10 +29,11 @@ import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.core.convert.converter.ConditionalGenericConverter;
 
 /**
- * Converts from a Map to a String.
+ * Converts from a Map to a String by storing each source Map entry into the String as a property (name=value pair). 
  *
  * @author Keith Donald
  * @since 3.0
+ * @see Properties#store(java.io.OutputStream, String)
  */
 final class MapToStringConverter implements ConditionalGenericConverter {
 

org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToArrayConverter.java

@@ -28,7 +28,8 @@ import org.springframework.core.convert.converter.ConditionalGenericConverter;
 import org.springframework.core.convert.converter.GenericConverter;
 
 /**
- * Converts from a single Object to an array.
+ * Converts an Object to a single-element Array containing the Object.
+ * Will convert the Object to the target Array's component type if necessary.
  *
  * @author Keith Donald
  * @since 3.0

org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToCollectionConverter.java

@@ -29,7 +29,8 @@ import org.springframework.core.convert.converter.ConditionalGenericConverter;
 import org.springframework.core.convert.converter.GenericConverter;
 
 /**
- * Converts from a single Object to a Collection.
+ * Converts an Object to a single-element Collection containing the Object.
+ * Will convert the Object to the target Collection's parameterized type if necessary.
  *
  * @author Keith Donald
  * @since 3.0

org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToMapConverter.java

@@ -25,7 +25,9 @@ import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.core.convert.converter.ConditionalGenericConverter;
 
 /**
- * Converts from a single Object to a Map.
+ * Converts an Object to a single-entry Map containing the Object.
+ * The Object is put as both the entry key and value.
+ * Will convert the Object to the target Map's parameterized types K,V if necessary.
  *
  * @author Keith Donald
  * @since 3.0

org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToArrayConverter.java

@@ -29,7 +29,7 @@ import org.springframework.core.convert.converter.GenericConverter;
 import org.springframework.util.StringUtils;
 
 /**
- * Converts from a delimited String to an array.
+ * Converts a comma-delimited String to an Array.
  *
  * @author Keith Donald
  * @since 3.0

org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToCharacterConverter.java

@@ -19,7 +19,7 @@ package org.springframework.core.convert.support;
 import org.springframework.core.convert.converter.Converter;
 
 /**
- * Converts a String to a Character and back.
+ * Converts a String to a Character.
  *
  * @author Keith Donald
  * @since 3.0

org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToCollectionConverter.java

@@ -30,7 +30,7 @@ import org.springframework.core.convert.converter.GenericConverter;
 import org.springframework.util.StringUtils;
 
 /**
- * Converts from a String to a Collection.
+ * Converts a comma-delimited String to a Collection.
  *
  * @author Keith Donald
  * @since 3.0

org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToEnumConverterFactory.java

@@ -20,7 +20,7 @@ import org.springframework.core.convert.converter.Converter;
 import org.springframework.core.convert.converter.ConverterFactory;
 
 /**
- * A factory for String to enum converters.
+ * Converts from a String to a java.lang.Enum by calling {@link Enum#valueOf(Class, String)}.
  *
  * @author Keith Donald
  * @since 3.0

org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToMapConverter.java

@@ -26,10 +26,11 @@ import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.core.convert.converter.ConditionalGenericConverter;
 
 /**
- * Converts from a String to a Map.
+ * Converts a String to a Map by loading the list of properties (name=value pairs) encoded in the String.
  *
  * @author Keith Donald
  * @since 3.0
+ * @see Properties#load(java.io.InputStream)
  */
 final class StringToMapConverter implements ConditionalGenericConverter {