From 5ed30b559a652c0855599baa6617062935e71be6 Mon Sep 17 00:00:00 2001 From: Keith Donald Date: Fri, 10 Apr 2009 15:21:16 +0000 Subject: [PATCH] javadoc git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@971 50f2f4bb-b051-0410-bef5-90022cba6387 --- .../service/AbstractCollectionConverter.java | 22 ++++++++++++++++- .../convert/service/ArrayToCollection.java | 9 +------ .../service/CollectionConversionUtils.java | 24 ++++++++++++------- .../convert/service/CollectionToArray.java | 11 +-------- .../service/NoOpConversionExecutor.java | 3 +++ .../core/convert/service/NoOpConverter.java | 4 ++++ .../convert/service/ReverseConverter.java | 4 ++++ .../service/ReverseSuperConverter.java | 4 ++++ .../service/StaticConversionExecutor.java | 4 ++++ .../StaticSuperConversionExecutor.java | 4 ++++ 10 files changed, 62 insertions(+), 27 deletions(-) diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/service/AbstractCollectionConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/service/AbstractCollectionConverter.java index f22a6d07b34..a43fa91155a 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/service/AbstractCollectionConverter.java +++ b/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; } \ No newline at end of file diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/service/ArrayToCollection.java b/org.springframework.core/src/main/java/org/springframework/core/convert/service/ArrayToCollection.java index 03e75b31ca9..d971a645ce2 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/service/ArrayToCollection.java +++ b/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 List.class is - * specified. Supports type conversion of array elements when a concrete parameterized collection class is provided, - * such as IntegerList.class. - * - * 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 */ diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/service/CollectionConversionUtils.java b/org.springframework.core/src/main/java/org/springframework/core/convert/service/CollectionConversionUtils.java index ab4aff912d5..f899af5f2b4 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/service/CollectionConversionUtils.java +++ b/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; } } diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/service/CollectionToArray.java b/org.springframework.core/src/main/java/org/springframework/core/convert/service/CollectionToArray.java index 796982468d4..b7e2ed98dba 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/service/CollectionToArray.java +++ b/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 List.class is - * specified. Supports type conversion of array elements when a concrete parameterized collection class is provided, - * such as IntegerList.class. - * - * 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 */ diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/service/NoOpConversionExecutor.java b/org.springframework.core/src/main/java/org/springframework/core/convert/service/NoOpConversionExecutor.java index b63b0121777..81773172493 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/service/NoOpConversionExecutor.java +++ b/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(); diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/service/NoOpConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/service/NoOpConverter.java index dab3ee15ef4..4f468924ea1 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/service/NoOpConverter.java +++ b/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 { diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/service/ReverseConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/service/ReverseConverter.java index dbd4de98bfa..eb85ac1aed7 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/service/ReverseConverter.java +++ b/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 { diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/service/ReverseSuperConverter.java b/org.springframework.core/src/main/java/org/springframework/core/convert/service/ReverseSuperConverter.java index 8400ae3c57a..1ec9686cf62 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/service/ReverseSuperConverter.java +++ b/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 { diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/service/StaticConversionExecutor.java b/org.springframework.core/src/main/java/org/springframework/core/convert/service/StaticConversionExecutor.java index d4301de53ff..857d7d3dc27 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/service/StaticConversionExecutor.java +++ b/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 { diff --git a/org.springframework.core/src/main/java/org/springframework/core/convert/service/StaticSuperConversionExecutor.java b/org.springframework.core/src/main/java/org/springframework/core/convert/service/StaticSuperConversionExecutor.java index 4573b2f8e94..58241e9f615 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/convert/service/StaticSuperConversionExecutor.java +++ b/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 {