Polishing

Author: jhoeller

spring-beans/src/main/java/org/springframework/beans/factory/BeanFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -181,8 +181,7 @@ public interface BeanFactory {
 	 * but may also be translated into a conventional by-name lookup based on the name
 	 * of the given type. For more extensive retrieval operations across sets of beans,
 	 * use {@link ListableBeanFactory} and/or {@link BeanFactoryUtils}.
-	 * @param requiredType type the bean must match; can be an interface or superclass.
-	 * {@code null} is disallowed.
+	 * @param requiredType type the bean must match; can be an interface or superclass
 	 * @return an instance of the single bean matching the required type
 	 * @throws NoSuchBeanDefinitionException if no bean of the given type was found
 	 * @throws NoUniqueBeanDefinitionException if more than one bean of the given type was found
@@ -200,8 +199,7 @@ public interface BeanFactory {
 	 * but may also be translated into a conventional by-name lookup based on the name
 	 * of the given type. For more extensive retrieval operations across sets of beans,
 	 * use {@link ListableBeanFactory} and/or {@link BeanFactoryUtils}.
-	 * @param requiredType type the bean must match; can be an interface or superclass.
-	 * {@code null} is disallowed.
+	 * @param requiredType type the bean must match; can be an interface or superclass
 	 * @param args arguments to use when creating a bean instance using explicit arguments
 	 * (only applied when creating a new instance as opposed to retrieving an existing one)
 	 * @return an instance of the bean

spring-beans/src/main/java/org/springframework/beans/factory/annotation/BeanFactoryAnnotationUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,11 +22,11 @@
 import org.springframework.beans.BeansException;
 import org.springframework.beans.factory.BeanFactory;
 import org.springframework.beans.factory.BeanFactoryUtils;
+import org.springframework.beans.factory.ListableBeanFactory;
 import org.springframework.beans.factory.NoSuchBeanDefinitionException;
 import org.springframework.beans.factory.NoUniqueBeanDefinitionException;
 import org.springframework.beans.factory.config.BeanDefinition;
 import org.springframework.beans.factory.config.ConfigurableBeanFactory;
-import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
 import org.springframework.beans.factory.support.AbstractBeanDefinition;
 import org.springframework.beans.factory.support.AutowireCandidateQualifier;
 import org.springframework.beans.factory.support.RootBeanDefinition;
@@ -35,8 +35,8 @@
 import org.springframework.util.Assert;
 
 /**
- * Convenience methods performing bean lookups related to annotations, for example
- * Spring's {@link Qualifier @Qualifier} annotation.
+ * Convenience methods performing bean lookups related to Spring-specific annotations,
+ * for example Spring's {@link Qualifier @Qualifier} annotation.
  *
  * @author Juergen Hoeller
  * @author Chris Beams
@@ -49,23 +49,23 @@ public abstract class BeanFactoryAnnotationUtils {
 	 * Obtain a bean of type {@code T} from the given {@code BeanFactory} declaring a
 	 * qualifier (e.g. via {@code <qualifier>} or {@code @Qualifier}) matching the given
 	 * qualifier, or having a bean name matching the given qualifier.
-	 * @param beanFactory the BeanFactory to get the target bean from
+	 * @param beanFactory the factory to get the target bean from (also searching ancestors)
 	 * @param beanType the type of bean to retrieve
 	 * @param qualifier the qualifier for selecting between multiple bean matches
 	 * @return the matching bean of type {@code T} (never {@code null})
 	 * @throws NoUniqueBeanDefinitionException if multiple matching beans of type {@code T} found
 	 * @throws NoSuchBeanDefinitionException if no matching bean of type {@code T} found
 	 * @throws BeansException if the bean could not be created
-	 * @see BeanFactory#getBean(Class)
+	 * @see BeanFactoryUtils#beanOfTypeIncludingAncestors(ListableBeanFactory, Class)
 	 */
 	public static <T> T qualifiedBeanOfType(BeanFactory beanFactory, Class<T> beanType, String qualifier)
 			throws BeansException {
 
 		Assert.notNull(beanFactory, "BeanFactory must not be null");
 
-		if (beanFactory instanceof ConfigurableListableBeanFactory) {
+		if (beanFactory instanceof ListableBeanFactory) {
 			// Full qualifier matching supported.
-			return qualifiedBeanOfType((ConfigurableListableBeanFactory) beanFactory, beanType, qualifier);
+			return qualifiedBeanOfType((ListableBeanFactory) beanFactory, beanType, qualifier);
 		}
 		else if (beanFactory.containsBean(qualifier)) {
 			// Fallback: target bean at least found by bean name.
@@ -82,12 +82,12 @@ else if (beanFactory.containsBean(qualifier)) {
 	/**
 	 * Obtain a bean of type {@code T} from the given {@code BeanFactory} declaring a qualifier
 	 * (e.g. {@code <qualifier>} or {@code @Qualifier}) matching the given qualifier).
-	 * @param bf the BeanFactory to get the target bean from
+	 * @param bf the factory to get the target bean from
 	 * @param beanType the type of bean to retrieve
 	 * @param qualifier the qualifier for selecting between multiple bean matches
 	 * @return the matching bean of type {@code T} (never {@code null})
 	 */
-	private static <T> T qualifiedBeanOfType(ConfigurableListableBeanFactory bf, Class<T> beanType, String qualifier) {
+	private static <T> T qualifiedBeanOfType(ListableBeanFactory bf, Class<T> beanType, String qualifier) {
 		String[] candidateBeans = BeanFactoryUtils.beanNamesForTypeIncludingAncestors(bf, beanType);
 		String matchingBean = null;
 		for (String beanName : candidateBeans) {
@@ -115,14 +115,14 @@ else if (bf.containsBean(qualifier)) {
 	 * Check whether the named bean declares a qualifier of the given name.
 	 * @param qualifier the qualifier to match
 	 * @param beanName the name of the candidate bean
-	 * @param beanFactory the {@code BeanFactory} from which to retrieve the named bean
+	 * @param beanFactory the factory from which to retrieve the named bean
 	 * @return {@code true} if either the bean definition (in the XML case)
 	 * or the bean's factory method (in the {@code @Bean} case) defines a matching
 	 * qualifier value (through {@code <qualifier>} or {@code @Qualifier})
 	 * @since 5.0
 	 */
-	public static boolean isQualifierMatch(Predicate<String> qualifier, String beanName,
-			@Nullable BeanFactory beanFactory) {
+	public static boolean isQualifierMatch(
+			Predicate<String> qualifier, String beanName, @Nullable BeanFactory beanFactory) {
 
 		// Try quick bean name or alias match first...
 		if (qualifier.test(beanName)) {

spring-core/src/main/java/org/springframework/core/io/PathResource.java

@@ -42,9 +42,9 @@
  * @author Philippe Marschall
  * @author Juergen Hoeller
  * @since 4.0
- * @see FileSystemResource
  * @see java.nio.file.Path
  * @see java.nio.file.Files
+ * @see FileSystemResource
  */
 public class PathResource extends AbstractResource implements WritableResource {
 
@@ -81,8 +81,8 @@ public PathResource(String path) {
 	 * <p>Note: Unlike {@link FileSystemResource}, when building relative resources
 	 * via {@link #createRelative}, the relative path will be built <i>underneath</i>
 	 * the given root: e.g. Paths.get("C:/dir1/"), relative path "dir2" -> "C:/dir1/dir2"!
-	 * @see java.nio.file.Paths#get(URI)
 	 * @param uri a path URI
+	 * @see java.nio.file.Paths#get(URI)
 	 */
 	public PathResource(URI uri) {
 		Assert.notNull(uri, "URI must not be null");
@@ -99,7 +99,7 @@ public final String getPath() {
 
 	/**
 	 * This implementation returns whether the underlying file exists.
-	 * @see org.springframework.core.io.PathResource#exists()
+	 * @see java.nio.file.Files#exists(Path, java.nio.file.LinkOption...)
 	 */
 	@Override
 	public boolean exists() {

spring-core/src/main/java/org/springframework/core/io/Resource.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,9 +43,9 @@
  * @see WritableResource
  * @see ContextResource
  * @see UrlResource
- * @see ClassPathResource
+ * @see FileUrlResource
  * @see FileSystemResource
- * @see PathResource
+ * @see ClassPathResource
  * @see ByteArrayResource
  * @see InputStreamResource
  */

spring-core/src/main/java/org/springframework/core/type/classreading/AbstractRecursiveAnnotationVisitor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,6 +31,8 @@
 import org.springframework.util.ReflectionUtils;
 
 /**
+ * {@link AnnotationVisitor} to recursively visit annotations.
+ *
  * @author Chris Beams
  * @author Juergen Hoeller
  * @author Phillip Webb

spring-core/src/main/java/org/springframework/core/type/classreading/AnnotationMetadataReadingVisitor.java

@@ -84,7 +84,7 @@ public MethodVisitor visitMethod(int access, String name, String desc, String si
 	}
 
 	@Override
-	public AnnotationVisitor visitAnnotation(final String desc, boolean visible) {
+	public AnnotationVisitor visitAnnotation(String desc, boolean visible) {
 		String className = Type.getType(desc).getClassName();
 		this.annotationSet.add(className);
 		return new AnnotationAttributesReadingVisitor(

spring-core/src/main/java/org/springframework/core/type/classreading/RecursiveAnnotationAttributesVisitor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,11 +16,14 @@
 
 package org.springframework.core.type.classreading;
 
+import org.springframework.asm.AnnotationVisitor;
 import org.springframework.core.annotation.AnnotationAttributes;
 import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.lang.Nullable;
 
 /**
+ * {@link AnnotationVisitor} to recursively visit annotation attributes.
+ *
  * @author Chris Beams
  * @author Juergen Hoeller
  * @since 3.1.1

src/docs/asciidoc/web/webmvc.adoc

@@ -1380,13 +1380,13 @@ and security (see next section for more details).
 To completely disable the use of file extensions, you must set both of these:
 
 * `useSuffixPatternMatching(false)`, see <<mvc-config-path-matching,PathMatchConfigurer>>
-* `favorPathExtension(false)`, see <<mvc-config-content-negotiation,ContentNeogiationConfigurer>>
+* `favorPathExtension(false)`, see <<mvc-config-content-negotiation,ContentNegotiationConfigurer>>
 
 URL-based content negotiation can still be useful, for example when typing a URL in a
 browser. To enable that we recommend a query parameter based strategy to avoid most of
 the issues that come with file extensions. Or if you must use file extensions, consider
 restricting them to a list of explicitly registered extensions through the
-`mediaTypes` property of <<mvc-config-content-negotiation,ContentNeogiationConfigurer>>.
+`mediaTypes` property of <<mvc-config-content-negotiation,ContentNegotiationConfigurer>>.
 
 
 [[mvc-ann-requestmapping-rfd]]