javadoc

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

org.springframework.core/src/main/java/org/springframework/core/convert/service/AbstractCollectionConverter.java

@@ -20,6 +20,10 @@ import org.springframework.core.convert.ConversionExecutor;
 import org.springframework.core.convert.ConversionService;
 import org.springframework.core.convert.TypeDescriptor;
 
+/**
+ * Base class for converters that convert to and from collection types (arrays and java.util.Collection types)
+ * @author Keith Donald
+ */
 abstract class AbstractCollectionConverter implements ConversionExecutor {
 
 	private ConversionService conversionService;
@@ -43,10 +47,16 @@ abstract class AbstractCollectionConverter implements ConversionExecutor {
 		}
 	}
 
+	/**
+	 * The collection type to convert to.
+	 */
 	protected Class<?> getTargetCollectionType() {
 		return targetCollectionType.getType();
 	}
-	
+
+	/**
+	 * The type of elements in the target collection.
+	 */
 	protected Class<?> getTargetElementType() {
 		return targetCollectionType.getElementType();
 	}
@@ -55,6 +65,10 @@ abstract class AbstractCollectionConverter implements ConversionExecutor {
 		return conversionService;
 	}
 
+	/**
+	 * The converter to use to convert elements to the {@link #getTargetElementType()}.
+	 * Returns {@link NoOpConversionExecutor#INSTANCE} if no converter could be eagerly resolved from type descriptor metadata.
+	 */
 	protected ConversionExecutor getElementConverter() {
 		return elementConverter;
 	}
@@ -67,6 +81,12 @@ abstract class AbstractCollectionConverter implements ConversionExecutor {
 		}
 	}
 
+	/**
+	 * Override to perform collection conversion 
+	 * @param sourceCollection the source collection to convert from, an instance of sourceCollectionType, which must be either an array or java.util.Collection type
+	 * @return the converted target collection, an instance of targetCollectionType
+	 * @throws Exception an exception occurred during the conversion
+	 */
 	protected abstract Object doExecute(Object sourceCollection) throws Exception;
 	
 }

org.springframework.core/src/main/java/org/springframework/core/convert/service/ArrayToCollection.java

@@ -19,19 +19,12 @@ import java.lang.reflect.Array;
 import java.util.Collection;
 
 import org.springframework.core.convert.ConversionExecutor;
-import org.springframework.core.convert.ConversionService;
 import org.springframework.core.convert.TypeDescriptor;
 
 /**
  * Special converter that converts from a source array to a target collection. Supports the selection of an
  * "approximate" collection implementation when a target collection interface such as <code>List.class</code> is
- * specified. Supports type conversion of array elements when a concrete parameterized collection class is provided,
- * such as <code>IntegerList<Integer>.class</code>.
- * 
- * Note that type erasure prevents arbitrary access to generic collection element type information at runtime,
- * preventing the ability to convert elements for collections declared as properties.
- * 
- * Mainly used internally by {@link ConversionService} implementations.
+ * specified. Supports type conversion of array elements when a parameterized target collection type descriptor is provided.
  * 
  * @author Keith Donald
  */

org.springframework.core/src/main/java/org/springframework/core/convert/service/CollectionConversionUtils.java

@@ -23,23 +23,31 @@ import java.util.Set;
 import java.util.SortedSet;
 import java.util.TreeSet;
 
+/**
+ * Util code shared by collection converters extending from {@link AbstractCollectionConverter}.
+ */
 class CollectionConversionUtils {
 
-	public static Class<?> getImpl(Class<?> targetClass) {
-		if (targetClass.isInterface()) {
-			if (List.class.equals(targetClass)) {
+	/**
+	 * Get the java.util.Collection implementation class that should be used for the given target collection type.
+	 * @param targetCollectionType the target collection type, may be an interface
+	 * @return the collection impl to use
+	 */
+	public static Class<?> getImpl(Class<?> targetCollectionType) {
+		if (targetCollectionType.isInterface()) {
+			if (List.class.equals(targetCollectionType)) {
 				return ArrayList.class;
-			} else if (Set.class.equals(targetClass)) {
+			} else if (Set.class.equals(targetCollectionType)) {
 				return LinkedHashSet.class;
-			} else if (SortedSet.class.equals(targetClass)) {
+			} else if (SortedSet.class.equals(targetCollectionType)) {
 				return TreeSet.class;
-			} else if (Collection.class.equals(targetClass)) {
+			} else if (Collection.class.equals(targetCollectionType)) {
 				return ArrayList.class;
 			} else {
-				throw new IllegalArgumentException("Unsupported collection interface [" + targetClass.getName() + "]");
+				throw new IllegalArgumentException("Unsupported collection interface [" + targetCollectionType.getName() + "]");
 			}
 		} else {
-			return targetClass;
+			return targetCollectionType;
 		}
 	}
 

org.springframework.core/src/main/java/org/springframework/core/convert/service/CollectionToArray.java

@@ -20,19 +20,10 @@ import java.util.Collection;
 import java.util.Iterator;
 
 import org.springframework.core.convert.ConversionExecutor;
-import org.springframework.core.convert.ConversionService;
 import org.springframework.core.convert.TypeDescriptor;
 
 /**
- * Special converter that converts from a source array to a target collection. Supports the selection of an
- * "approximate" collection implementation when a target collection interface such as <code>List.class</code> is
- * specified. Supports type conversion of array elements when a concrete parameterized collection class is provided,
- * such as <code>IntegerList<Integer>.class</code>.
- * 
- * Note that type erasure prevents arbitrary access to generic collection element type information at runtime,
- * preventing the ability to convert elements for collections declared as properties.
- * 
- * Mainly used internally by {@link ConversionService} implementations.
+ * Special converter that converts from target collection to a source array.
  * 
  * @author Keith Donald
  */

org.springframework.core/src/main/java/org/springframework/core/convert/service/NoOpConversionExecutor.java

@@ -18,6 +18,9 @@ package org.springframework.core.convert.service;
 import org.springframework.core.convert.ConversionExecutionException;
 import org.springframework.core.convert.ConversionExecutor;
 
+/**
+ * Conversion executor that does nothing.  Access singleton at {@link #INSTANCE}.s
+ */
 class NoOpConversionExecutor implements ConversionExecutor {
 
 	public static final ConversionExecutor INSTANCE = new NoOpConversionExecutor();

org.springframework.core/src/main/java/org/springframework/core/convert/service/NoOpConverter.java

@@ -17,6 +17,10 @@ package org.springframework.core.convert.service;
 
 import org.springframework.core.convert.converter.Converter;
 
+/**
+ * A converter that does nothing.  Access singleton at {@link #INSTANCE}.
+ * @author Keith Donald
+ */
 @SuppressWarnings("unchecked")
 class NoOpConverter implements Converter {
 

org.springframework.core/src/main/java/org/springframework/core/convert/service/ReverseConverter.java

@@ -17,6 +17,10 @@ package org.springframework.core.convert.service;
 
 import org.springframework.core.convert.converter.Converter;
 
+/**
+ * A converter that reverses another converter.
+ * @author Keith Donald
+ */
 @SuppressWarnings("unchecked")
 class ReverseConverter implements Converter {
 

org.springframework.core/src/main/java/org/springframework/core/convert/service/ReverseSuperConverter.java

@@ -18,6 +18,10 @@ package org.springframework.core.convert.service;
 import org.springframework.core.convert.converter.SuperConverter;
 import org.springframework.core.convert.converter.SuperTwoWayConverter;
 
+/**
+ * A super converter that reverses another super converter.
+ * @author Keith Donald
+ */
 @SuppressWarnings("unchecked")
 class ReverseSuperConverter implements SuperConverter {
 

org.springframework.core/src/main/java/org/springframework/core/convert/service/StaticConversionExecutor.java

@@ -21,6 +21,10 @@ import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.core.convert.converter.Converter;
 import org.springframework.core.style.ToStringCreator;
 
+/**
+ * Default conversion executor implementation for converters.
+ * @author Keith Donald
+ */
 @SuppressWarnings("unchecked")
 class StaticConversionExecutor implements ConversionExecutor {
 

org.springframework.core/src/main/java/org/springframework/core/convert/service/StaticSuperConversionExecutor.java

@@ -21,6 +21,10 @@ import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.core.convert.converter.SuperConverter;
 import org.springframework.core.style.ToStringCreator;
 
+/**
+ * Default conversion executor implementation for super converters.
+ * @author Keith Donald
+ */
 @SuppressWarnings("unchecked")
 class StaticSuperConversionExecutor implements ConversionExecutor {