From 4f4732df451721402d8fb1854ade0efb6b72eda8 Mon Sep 17 00:00:00 2001 From: Keith Donald Date: Fri, 11 Dec 2009 17:56:41 +0000 Subject: [PATCH] javadoc polishing --- .../convert/support/MapToArrayConverter.java | 4 +- .../support/MapToCollectionConverter.java | 7 +- .../convert/support/MapToMapConverter.java | 5 +- .../convert/support/MapToObjectConverter.java | 94 ++++--------------- .../convert/support/MapToStringConverter.java | 3 +- .../support/ObjectToArrayConverter.java | 3 +- .../support/ObjectToCollectionConverter.java | 3 +- .../convert/support/ObjectToMapConverter.java | 4 +- .../support/StringToArrayConverter.java | 2 +- .../support/StringToCharacterConverter.java | 2 +- .../support/StringToCollectionConverter.java | 2 +- .../support/StringToEnumConverterFactory.java | 2 +- .../convert/support/StringToMapConverter.java | 3 +- 13 files changed, 47 insertions(+), 87 deletions(-) diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToArrayConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToArrayConverter.java index fa70f9024d8..00f593983ff 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToArrayConverter.java +++ b/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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToCollectionConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToCollectionConverter.java index 5db1af64ffc..eaf1e728167 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToCollectionConverter.java +++ b/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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToMapConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToMapConverter.java index 9920b1dff8a..b9540395170 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToMapConverter.java +++ b/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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToObjectConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToObjectConverter.java index 6cf2e759efb..376f535d472 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToObjectConverter.java +++ b/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,75 +52,24 @@ 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); - } - } 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); - } + 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); } - } - } - - 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); } } diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToStringConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToStringConverter.java index 6ced5cb5678..cf189214862 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/MapToStringConverter.java +++ b/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 { diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToArrayConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToArrayConverter.java index c1b9456643d..db1108a36cd 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToArrayConverter.java +++ b/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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToCollectionConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToCollectionConverter.java index fafc6d0b20c..645ff906862 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToCollectionConverter.java +++ b/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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToMapConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToMapConverter.java index f34cee41af1..da2f210b0b5 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/ObjectToMapConverter.java +++ b/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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToArrayConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToArrayConverter.java index aec1ca9606c..0c5e9496bbc 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToArrayConverter.java +++ b/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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToCharacterConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToCharacterConverter.java index 3771d83f505..c347c15f2d2 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToCharacterConverter.java +++ b/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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToCollectionConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToCollectionConverter.java index d8e534929a1..117cf8c4877 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToCollectionConverter.java +++ b/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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToEnumConverterFactory.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToEnumConverterFactory.java index b3d47d6a511..1e816dec4ce 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToEnumConverterFactory.java +++ b/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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToMapConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToMapConverter.java index d2e6637aadc..aca3d9ec6dd 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/support/StringToMapConverter.java +++ b/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 {