[SPR-8388] Improved documentation on default registered PropertyEditors; fixed typos and grammar in JavaDoc; suppressed warnings due to generics; etc.

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

org.springframework.beans/src/main/java/org/springframework/beans/PropertyEditorRegistrySupport.java

@@ -91,17 +91,17 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 
 	private boolean configValueEditorsActive = false;
 
-	private Map<Class, PropertyEditor> defaultEditors;
+	private Map<Class<?>, PropertyEditor> defaultEditors;
 
-	private Map<Class, PropertyEditor> overriddenDefaultEditors;
+	private Map<Class<?>, PropertyEditor> overriddenDefaultEditors;
 
-	private Map<Class, PropertyEditor> customEditors;
+	private Map<Class<?>, PropertyEditor> customEditors;
 
 	private Map<String, CustomEditorHolder> customEditorsForPath;
 
 	private Set<PropertyEditor> sharedEditors;
 
-	private Map<Class, PropertyEditor> customEditorCache;
+	private Map<Class<?>, PropertyEditor> customEditorCache;
 
 
 	/**
@@ -152,9 +152,9 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 	 * @param propertyEditor the editor to register
 	 * @see #registerCustomEditor(Class, PropertyEditor)
 	 */
-	public void overrideDefaultEditor(Class requiredType, PropertyEditor propertyEditor) {
+	public void overrideDefaultEditor(Class<?> requiredType, PropertyEditor propertyEditor) {
 		if (this.overriddenDefaultEditors == null) {
-			this.overriddenDefaultEditors = new HashMap<Class, PropertyEditor>();
+			this.overriddenDefaultEditors = new HashMap<Class<?>, PropertyEditor>();
 		}
 		this.overriddenDefaultEditors.put(requiredType, propertyEditor);
 	}
@@ -166,7 +166,7 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 	 * @return the default editor, or <code>null</code> if none found
 	 * @see #registerDefaultEditors
 	 */
-	public PropertyEditor getDefaultEditor(Class requiredType) {
+	public PropertyEditor getDefaultEditor(Class<?> requiredType) {
 		if (!this.defaultEditorsActive) {
 			return null;
 		}
@@ -186,7 +186,7 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 	 * Actually register the default editors for this registry instance.
 	 */
 	private void createDefaultEditors() {
-		this.defaultEditors = new HashMap<Class, PropertyEditor>(64);
+		this.defaultEditors = new HashMap<Class<?>, PropertyEditor>(64);
 
 		// Simple editors, without parameterization capabilities.
 		// The JDK does not contain a default editor for any of these target types.
@@ -269,11 +269,11 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 	// Management of custom editors
 	//---------------------------------------------------------------------
 
-	public void registerCustomEditor(Class requiredType, PropertyEditor propertyEditor) {
+	public void registerCustomEditor(Class<?> requiredType, PropertyEditor propertyEditor) {
 		registerCustomEditor(requiredType, null, propertyEditor);
 	}
 
-	public void registerCustomEditor(Class requiredType, String propertyPath, PropertyEditor propertyEditor) {
+	public void registerCustomEditor(Class<?> requiredType, String propertyPath, PropertyEditor propertyEditor) {
 		if (requiredType == null && propertyPath == null) {
 			throw new IllegalArgumentException("Either requiredType or propertyPath is required");
 		}
@@ -285,7 +285,7 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 		}
 		else {
 			if (this.customEditors == null) {
-				this.customEditors = new LinkedHashMap<Class, PropertyEditor>(16);
+				this.customEditors = new LinkedHashMap<Class<?>, PropertyEditor>(16);
 			}
 			this.customEditors.put(requiredType, propertyEditor);
 			this.customEditorCache = null;
@@ -301,7 +301,7 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 	 * @deprecated as of Spring 3.0, in favor of PropertyEditorRegistrars or ConversionService usage
 	 */
 	@Deprecated
-	public void registerSharedEditor(Class requiredType, PropertyEditor propertyEditor) {
+	public void registerSharedEditor(Class<?> requiredType, PropertyEditor propertyEditor) {
 		registerCustomEditor(requiredType, null, propertyEditor);
 		if (this.sharedEditors == null) {
 			this.sharedEditors = new HashSet<PropertyEditor>();
@@ -319,8 +319,8 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 		return (this.sharedEditors != null && this.sharedEditors.contains(propertyEditor));
 	}
 
-	public PropertyEditor findCustomEditor(Class requiredType, String propertyPath) {
-		Class requiredTypeToUse = requiredType;
+	public PropertyEditor findCustomEditor(Class<?> requiredType, String propertyPath) {
+		Class<?> requiredTypeToUse = requiredType;
 		if (propertyPath != null) {
 			if (this.customEditorsForPath != null) {
 				// Check property-specific editor first.
@@ -354,7 +354,7 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 	 * can be <code>null</code> if not known)
 	 * @return whether a matching custom editor has been found
 	 */
-	public boolean hasCustomEditorForElement(Class elementType, String propertyPath) {
+	public boolean hasCustomEditorForElement(Class<?> elementType, String propertyPath) {
 		if (propertyPath != null && this.customEditorsForPath != null) {
 			for (Map.Entry<String, CustomEditorHolder> entry : this.customEditorsForPath.entrySet()) {
 				if (PropertyAccessorUtils.matchesProperty(entry.getKey(), propertyPath)) {
@@ -379,7 +379,7 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 	 * @return the type of the property, or <code>null</code> if not determinable
 	 * @see BeanWrapper#getPropertyType(String)
 	 */
-	protected Class getPropertyType(String propertyPath) {
+	protected Class<?> getPropertyType(String propertyPath) {
 		return null;
 	}
 
@@ -389,7 +389,7 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 	 * @param requiredType the type to look for
 	 * @return the custom editor, or <code>null</code> if none specific for this property
 	 */
-	private PropertyEditor getCustomEditor(String propertyName, Class requiredType) {
+	private PropertyEditor getCustomEditor(String propertyName, Class<?> requiredType) {
 		CustomEditorHolder holder = this.customEditorsForPath.get(propertyName);
 		return (holder != null ? holder.getPropertyEditor(requiredType) : null);
 	}
@@ -402,7 +402,7 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 	 * @return the custom editor, or <code>null</code> if none found for this type
 	 * @see java.beans.PropertyEditor#getAsText()
 	 */
-	private PropertyEditor getCustomEditor(Class requiredType) {
+	private PropertyEditor getCustomEditor(Class<?> requiredType) {
 		if (requiredType == null || this.customEditors == null) {
 			return null;
 		}
@@ -415,14 +415,14 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 			}
 			if (editor == null) {
 				// Find editor for superclass or interface.
-				for (Iterator<Class> it = this.customEditors.keySet().iterator(); it.hasNext() && editor == null;) {
-					Class key = it.next();
+				for (Iterator<Class<?>> it = this.customEditors.keySet().iterator(); it.hasNext() && editor == null;) {
+					Class<?> key = it.next();
 					if (key.isAssignableFrom(requiredType)) {
 						editor = this.customEditors.get(key);
 						// Cache editor for search type, to avoid the overhead
 						// of repeated assignable-from checks.
 						if (this.customEditorCache == null) {
-							this.customEditorCache = new HashMap<Class, PropertyEditor>();
+							this.customEditorCache = new HashMap<Class<?>, PropertyEditor>();
 						}
 						this.customEditorCache.put(requiredType, editor);
 					}
@@ -438,7 +438,7 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 	 * @param propertyName the name of the property
 	 * @return the property type, or <code>null</code> if not determinable
 	 */
-	protected Class guessPropertyTypeFromEditors(String propertyName) {
+	protected Class<?> guessPropertyTypeFromEditors(String propertyName) {
 		if (this.customEditorsForPath != null) {
 			CustomEditorHolder editorHolder = this.customEditorsForPath.get(propertyName);
 			if (editorHolder == null) {
@@ -467,7 +467,7 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 		String actualPropertyName =
 				(nestedProperty != null ? PropertyAccessorUtils.getPropertyName(nestedProperty) : null);
 		if (this.customEditors != null) {
-			for (Map.Entry<Class, PropertyEditor> entry : this.customEditors.entrySet()) {
+			for (Map.Entry<Class<?>, PropertyEditor> entry : this.customEditors.entrySet()) {
 				target.registerCustomEditor(entry.getKey(), entry.getValue());
 			}
 		}
@@ -529,9 +529,9 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 
 		private final PropertyEditor propertyEditor;
 
-		private final Class registeredType;
+		private final Class<?> registeredType;
 
-		private CustomEditorHolder(PropertyEditor propertyEditor, Class registeredType) {
+		private CustomEditorHolder(PropertyEditor propertyEditor, Class<?> registeredType) {
 			this.propertyEditor = propertyEditor;
 			this.registeredType = registeredType;
 		}
@@ -540,11 +540,11 @@ public class PropertyEditorRegistrySupport implements PropertyEditorRegistry {
 			return this.propertyEditor;
 		}
 
-		private Class getRegisteredType() {
+		private Class<?> getRegisteredType() {
 			return this.registeredType;
 		}
 
-		private PropertyEditor getPropertyEditor(Class requiredType) {
+		private PropertyEditor getPropertyEditor(Class<?> requiredType) {
 			// Special case: If no required type specified, which usually only happens for
 			// Collection elements, or required type is not assignable to registered type,
 			// which usually only happens for generic properties of type Object -

org.springframework.beans/src/main/java/org/springframework/beans/support/ResourceEditorRegistrar.java

@@ -70,7 +70,7 @@ public class ResourceEditorRegistrar implements PropertyEditorRegistrar {
 	 * @see org.springframework.core.io.support.ResourcePatternResolver
 	 * @see org.springframework.context.ApplicationContext
 	 * @deprecated as of Spring 3.1 in favor of
-	 * {@link ResourceEditorRegistrar#ResourceEditorRegistrar(ResourceLoader, Environment)}
+	 * {@link #ResourceEditorRegistrar(ResourceLoader, Environment)}
 	 */
 	@Deprecated
 	public ResourceEditorRegistrar(ResourceLoader resourceLoader) {
@@ -91,16 +91,19 @@ public class ResourceEditorRegistrar implements PropertyEditorRegistrar {
 
 
 	/**
-	 * Populate the given bean factory with the following resource editors:
-	 * ResourceEditor, InputStreamEditor, FileEditor, URLEditor, ClassEditor, URIEditor.
-	 * <p>In case of a {@link org.springframework.core.io.support.ResourcePatternResolver},
+	 * Populate the given <code>registry</code> with the following resource editors:
+	 * ResourceEditor, InputStreamEditor, InputSourceEditor, FileEditor, URLEditor,
+	 * URIEditor, ClassEditor, ClassArrayEditor.
+	 * <p>If this registrar has been configured with a {@link ResourcePatternResolver},
 	 * a ResourceArrayPropertyEditor will be registered as well.
 	 * @see org.springframework.core.io.ResourceEditor
 	 * @see org.springframework.beans.propertyeditors.InputStreamEditor
+	 * @see org.springframework.beans.propertyeditors.InputSourceEditor
 	 * @see org.springframework.beans.propertyeditors.FileEditor
 	 * @see org.springframework.beans.propertyeditors.URLEditor
-	 * @see org.springframework.beans.propertyeditors.ClassEditor
 	 * @see org.springframework.beans.propertyeditors.URIEditor
+	 * @see org.springframework.beans.propertyeditors.ClassEditor
+	 * @see org.springframework.beans.propertyeditors.ClassArrayEditor
 	 * @see org.springframework.core.io.support.ResourceArrayPropertyEditor
 	 */
 	public void registerCustomEditors(PropertyEditorRegistry registry) {
@@ -126,7 +129,7 @@ public class ResourceEditorRegistrar implements PropertyEditorRegistrar {
 	 * Override default editor, if possible (since that's what we really mean to do here);
 	 * otherwise register as a custom editor.
 	 */
-	private void doRegisterEditor(PropertyEditorRegistry registry, Class requiredType, PropertyEditor editor) {
+	private void doRegisterEditor(PropertyEditorRegistry registry, Class<?> requiredType, PropertyEditor editor) {
 		if (registry instanceof PropertyEditorRegistrySupport) {
 			((PropertyEditorRegistrySupport) registry).overrideDefaultEditor(requiredType, editor);
 		}

org.springframework.core/src/main/java/org/springframework/core/io/support/PathMatchingResourcePatternResolver.java

@@ -84,8 +84,8 @@ import org.springframework.util.StringUtils;
  * "<code>zip:</code>" in WebLogic, "<code>wsjar</code>" in WebSphere", etc.),
  * then a <code>java.io.File</code> is obtained from it, and used to resolve the
  * wildcard by walking the filesystem. In the case of a jar URL, the resolver
- * either gets a <code>java.net.JarURLConnection</code> from it, or manually parse
- * the jar URL, and then traverse the contents of the jar file, to resolve the
+ * either gets a <code>java.net.JarURLConnection</code> from it, or manually parses
+ * the jar URL, and then traverses the contents of the jar file, to resolve the
  * wildcards.
  *
  * <p><b>Implications on portability:</b>
@@ -173,7 +173,7 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
 	static {
 		// Detect Equinox OSGi (e.g. on WebSphere 6.1)
 		try {
-			Class fileLocatorClass = PathMatchingResourcePatternResolver.class.getClassLoader().loadClass(
+			Class<?> fileLocatorClass = PathMatchingResourcePatternResolver.class.getClassLoader().loadClass(
 					"org.eclipse.core.runtime.FileLocator");
 			equinoxResolveMethod = fileLocatorClass.getMethod("resolve", URL.class);
 			logger.debug("Found Equinox FileLocator for OSGi bundle URL resolution");
@@ -220,7 +220,6 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
 		this.resourceLoader = resourceLoader;
 	}
 
-
 	/**
 	 * Return the ResourceLoader that this pattern resolver works with.
 	 */
@@ -286,7 +285,6 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
 		}
 	}
 
-
 	/**
 	 * Find all class location resources with the given location via the ClassLoader.
 	 * @param location the absolute path within the classpath
@@ -300,10 +298,10 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
 		if (path.startsWith("/")) {
 			path = path.substring(1);
 		}
-		Enumeration resourceUrls = getClassLoader().getResources(path);
+		Enumeration<URL> resourceUrls = getClassLoader().getResources(path);
 		Set<Resource> result = new LinkedHashSet<Resource>(16);
 		while (resourceUrls.hasMoreElements()) {
-			URL url = (URL) resourceUrls.nextElement();
+			URL url = resourceUrls.nextElement();
 			result.add(convertClassLoaderURL(url));
 		}
 		return result.toArray(new Resource[result.size()]);
@@ -384,7 +382,7 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
 	 * <p>The default implementation detects an Equinox OSGi "bundleresource:"
 	 * / "bundleentry:" URL and resolves it into a standard jar file URL that
 	 * can be traversed using Spring's standard jar file traversal algorithm.
-	 * @param original the resource to resolfe
+	 * @param original the resource to resolve
 	 * @return the resolved resource (may be identical to the passed-in resource)
 	 * @throws IOException in case of resolution failure
 	 */
@@ -471,8 +469,8 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
 				rootEntryPath = rootEntryPath + "/";
 			}
 			Set<Resource> result = new LinkedHashSet<Resource>(8);
-			for (Enumeration entries = jarFile.entries(); entries.hasMoreElements();) {
-				JarEntry entry = (JarEntry) entries.nextElement();
+			for (Enumeration<JarEntry> entries = jarFile.entries(); entries.hasMoreElements();) {
+				JarEntry entry = entries.nextElement();
 				String entryPath = entry.getName();
 				if (entryPath.startsWith(rootEntryPath)) {
 					String relativePath = entryPath.substring(rootEntryPath.length());
@@ -604,7 +602,7 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
 	 * Recursively retrieve files that match the given pattern,
 	 * adding them to the given result list.
 	 * @param fullPattern the pattern to match against,
-	 * with preprended root directory path
+	 * with prepended root directory path
 	 * @param dir the current directory
 	 * @param result the Set of matching File instances to add to
 	 * @throws IOException if directory contents could not be retrieved
@@ -712,11 +710,11 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
 			return VfsPatternUtils.getVisitorAttribute();
 		}
 
-
 		public Set<Resource> getResources() {
 			return this.resources;
 		}
 
+		@SuppressWarnings("unused")
 		public int size() {
 			return this.resources.size();
 		}

org.springframework.core/src/main/java/org/springframework/core/io/support/ResourceArrayPropertyEditor.java

@@ -37,9 +37,9 @@ import org.springframework.core.io.Resource;
  * to <code>Resource</code> array properties. Can also translate a collection
  * or array of location patterns into a merged Resource array.
  *
- * <p>The path may contain <code>${...}</code> placeholders,
- * to be resolved as system properties: e.g. <code>${user.dir}</code>.
- * Unresolvable placeholder are ignored by default.
+ * <p>A path may contain <code>${...}</code> placeholders, to be
+ * resolved as {@link org.springframework.core.env.Environment} properties:
+ * e.g. <code>${user.dir}</code>. Unresolvable placeholders are ignored by default.
  *
  * <p>Delegates to a {@link ResourcePatternResolver},
  * by default using a {@link PathMatchingResourcePatternResolver}.
@@ -123,7 +123,7 @@ public class ResourceArrayPropertyEditor extends PropertyEditorSupport {
 
 
 	/**
-	 * Treat the given text as location pattern and convert it to a Resource array.
+	 * Treat the given text as a location pattern and convert it to a Resource array.
 	 */
 	@Override
 	public void setAsText(String text) {
@@ -138,13 +138,13 @@ public class ResourceArrayPropertyEditor extends PropertyEditorSupport {
 	}
 
 	/**
-	 * Treat the given value as collection or array and convert it to a Resource array.
-	 * Considers String elements as location patterns, and takes Resource elements as-is.
+	 * Treat the given value as a collection or array and convert it to a Resource array.
+	 * Considers String elements as location patterns and takes Resource elements as-is.
 	 */
 	@Override
 	public void setValue(Object value) throws IllegalArgumentException {
 		if (value instanceof Collection || (value instanceof Object[] && !(value instanceof Resource[]))) {
-			Collection input = (value instanceof Collection ? (Collection) value : Arrays.asList((Object[]) value));
+			Collection<?> input = (value instanceof Collection ? (Collection<?>) value : Arrays.asList((Object[]) value));
 			List<Resource> merged = new ArrayList<Resource>();
 			for (Object element : input) {
 				if (element instanceof String) {