Method-level javadoc on XmlReaderContext etc

spring-beans/src/main/java/org/springframework/beans/factory/parsing/ReaderContext.java

@@ -38,6 +38,13 @@ public class ReaderContext {
 	private final SourceExtractor sourceExtractor;
 
 
+	/**
+	 * Construct a new {@code ReaderContext}.
+	 * @param resource the XML bean definition resource
+	 * @param problemReporter the problem reporter in use
+	 * @param eventListener the event listener in use
+	 * @param sourceExtractor the source extractor in use
+	 */
 	public ReaderContext(Resource resource, ProblemReporter problemReporter,
 			ReaderEventListener eventListener, SourceExtractor sourceExtractor) {
 
@@ -52,83 +59,150 @@ public class ReaderContext {
 	}
 
 
+	// Errors and warnings
+
+	/**
+	 * Raise a fatal error.
+	 */
 	public void fatal(String message, @Nullable Object source) {
 		fatal(message, source, null, null);
 	}
 
+	/**
+	 * Raise a fatal error.
+	 */
 	public void fatal(String message, @Nullable Object source, @Nullable Throwable cause) {
 		fatal(message, source, null, cause);
 	}
 
+	/**
+	 * Raise a fatal error.
+	 */
 	public void fatal(String message, @Nullable Object source, @Nullable ParseState parseState) {
 		fatal(message, source, parseState, null);
 	}
 
+	/**
+	 * Raise a fatal error.
+	 */
 	public void fatal(String message, @Nullable Object source, @Nullable ParseState parseState, @Nullable Throwable cause) {
 		Location location = new Location(getResource(), source);
 		this.problemReporter.fatal(new Problem(message, location, parseState, cause));
 	}
 
+	/**
+	 * Raise a fatal error.
+	 */
 	public void error(String message, @Nullable Object source) {
 		error(message, source, null, null);
 	}
 
+	/**
+	 * Raise a regular error.
+	 */
 	public void error(String message, @Nullable Object source, @Nullable Throwable cause) {
 		error(message, source, null, cause);
 	}
 
+	/**
+	 * Raise a regular error.
+	 */
 	public void error(String message, @Nullable Object source, @Nullable ParseState parseState) {
 		error(message, source, parseState, null);
 	}
 
+	/**
+	 * Raise a regular error.
+	 */
 	public void error(String message, @Nullable Object source, @Nullable ParseState parseState, @Nullable Throwable cause) {
 		Location location = new Location(getResource(), source);
 		this.problemReporter.error(new Problem(message, location, parseState, cause));
 	}
 
+	/**
+	 * Raise a non-critical warning.
+	 */
 	public void warning(String message, @Nullable Object source) {
 		warning(message, source, null, null);
 	}
 
+	/**
+	 * Raise a non-critical warning.
+	 */
 	public void warning(String message, @Nullable Object source, @Nullable Throwable cause) {
 		warning(message, source, null, cause);
 	}
 
+	/**
+	 * Raise a non-critical warning.
+	 */
 	public void warning(String message, @Nullable Object source, @Nullable ParseState parseState) {
 		warning(message, source, parseState, null);
 	}
 
+	/**
+	 * Raise a non-critical warning.
+	 */
 	public void warning(String message, @Nullable Object source, @Nullable ParseState parseState, @Nullable Throwable cause) {
 		Location location = new Location(getResource(), source);
 		this.problemReporter.warning(new Problem(message, location, parseState, cause));
 	}
 
 
+	// Explicit parse events
+
+	/**
+	 * Fire an defaults-registered event.
+	 */
 	public void fireDefaultsRegistered(DefaultsDefinition defaultsDefinition) {
 		this.eventListener.defaultsRegistered(defaultsDefinition);
 	}
 
+	/**
+	 * Fire an component-registered event.
+	 */
 	public void fireComponentRegistered(ComponentDefinition componentDefinition) {
 		this.eventListener.componentRegistered(componentDefinition);
 	}
 
+	/**
+	 * Fire an alias-registered event.
+	 */
 	public void fireAliasRegistered(String beanName, String alias, @Nullable Object source) {
 		this.eventListener.aliasRegistered(new AliasDefinition(beanName, alias, source));
 	}
 
+	/**
+	 * Fire an import-processed event.
+	 */
 	public void fireImportProcessed(String importedResource, @Nullable Object source) {
 		this.eventListener.importProcessed(new ImportDefinition(importedResource, source));
 	}
 
+	/**
+	 * Fire an import-processed event.
+	 */
 	public void fireImportProcessed(String importedResource, Resource[] actualResources, @Nullable Object source) {
 		this.eventListener.importProcessed(new ImportDefinition(importedResource, actualResources, source));
 	}
 
 
+	// Source extraction
+
+	/**
+	 * Return the source extractor in use.
+	 */
 	public SourceExtractor getSourceExtractor() {
 		return this.sourceExtractor;
 	}
 
+	/**
+	 * Call the source extractor for the given source object.
+	 * @param sourceCandidate the original source object
+	 * @return the source object to store, or {@code null} for none.
+	 * @see #getSourceExtractor()
+	 * @see SourceExtractor#extractSource
+	 */
 	@Nullable
 	public Object extractSource(Object sourceCandidate) {
 		return this.sourceExtractor.extractSource(sourceCandidate, this.resource);

spring-beans/src/main/java/org/springframework/beans/factory/support/AbstractAutowireCapableBeanFactory.java

@@ -298,6 +298,8 @@ public abstract class AbstractAutowireCapableBeanFactory extends AbstractBeanFac
 		RootBeanDefinition bd = new RootBeanDefinition(beanClass);
 		bd.setScope(SCOPE_PROTOTYPE);
 		bd.allowCaching = ClassUtils.isCacheSafe(beanClass, getBeanClassLoader());
+		// For the nullability warning, see the elaboration in AbstractBeanFactory.doGetBean;
+		// in short: This is never going to be null unless user-declared code enforces null.
 		return (T) createBean(beanClass.getName(), bd, null);
 	}
 
@@ -331,6 +333,8 @@ public abstract class AbstractAutowireCapableBeanFactory extends AbstractBeanFac
 		BeanWrapper bw = new BeanWrapperImpl(existingBean);
 		initBeanWrapper(bw);
 		populateBean(beanName, bd, bw);
+		// For the nullability warning, see the elaboration in AbstractBeanFactory.doGetBean;
+		// in short: This is never going to be null unless user-declared code enforces null.
 		return initializeBean(beanName, existingBean, bd);
 	}
 
@@ -349,6 +353,8 @@ public abstract class AbstractAutowireCapableBeanFactory extends AbstractBeanFac
 		// Use non-singleton bean definition, to avoid registering bean as dependent bean.
 		RootBeanDefinition bd = new RootBeanDefinition(beanClass, autowireMode, dependencyCheck);
 		bd.setScope(BeanDefinition.SCOPE_PROTOTYPE);
+		// For the nullability warning, see the elaboration in AbstractBeanFactory.doGetBean;
+		// in short: This is never going to be null unless user-declared code enforces null.
 		return createBean(beanClass.getName(), bd, null);
 	}
 

spring-beans/src/main/java/org/springframework/beans/factory/support/AbstractBeanFactory.java

@@ -56,7 +56,6 @@ import org.springframework.beans.factory.BeanNotOfRequiredTypeException;
 import org.springframework.beans.factory.CannotLoadBeanClassException;
 import org.springframework.beans.factory.FactoryBean;
 import org.springframework.beans.factory.NoSuchBeanDefinitionException;
-import org.springframework.beans.factory.ObjectFactory;
 import org.springframework.beans.factory.SmartFactoryBean;
 import org.springframework.beans.factory.config.BeanDefinition;
 import org.springframework.beans.factory.config.BeanDefinitionHolder;
@@ -336,16 +335,13 @@ public abstract class AbstractBeanFactory extends FactoryBeanRegistrySupport imp
 						throw new IllegalStateException("No Scope registered for scope name '" + scopeName + "'");
 					}
 					try {
-						Object scopedInstance = scope.get(beanName, new ObjectFactory<Object>() {
+						Object scopedInstance = scope.get(beanName, () -> {
-							@Override
+							beforePrototypeCreation(beanName);
-							public Object getObject() throws BeansException {
+							try {
-								beforePrototypeCreation(beanName);
+								return createBean(beanName, mbd, args);
-								try {
+							}
-									return createBean(beanName, mbd, args);
+							finally {
-								}
+								afterPrototypeCreation(beanName);
-								finally {
-									afterPrototypeCreation(beanName);
-								}
 							}
 						});
 						bean = getObjectForBeanInstance(scopedInstance, name, beanName, mbd);
@@ -389,7 +385,8 @@ public abstract class AbstractBeanFactory extends FactoryBeanRegistrySupport imp
 				throw new BeanNotOfRequiredTypeException(name, requiredType, bean.getClass());
 			}
 		}
-		// For the nullability warning, see the elaboration in the comment above.
+		// For the nullability warning, see the elaboration in the comment above;
+		// in short: This is never going to be null unless user-declared code enforces null.
 		return (T) bean;
 	}
 

spring-beans/src/main/java/org/springframework/beans/factory/xml/XmlReaderContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -49,6 +49,15 @@ public class XmlReaderContext extends ReaderContext {
 	private final NamespaceHandlerResolver namespaceHandlerResolver;
 
 
+	/**
+	 * Construct a new {@code XmlReaderContext}.
+	 * @param resource the XML bean definition resource
+	 * @param problemReporter the problem reporter in use
+	 * @param eventListener the event listener in use
+	 * @param sourceExtractor the source extractor in use
+	 * @param reader the XML bean definition reader in use
+	 * @param namespaceHandlerResolver the XML namespace resolver
+	 */
 	public XmlReaderContext(
 			Resource resource, ProblemReporter problemReporter,
 			ReaderEventListener eventListener, SourceExtractor sourceExtractor,
@@ -60,43 +69,89 @@ public class XmlReaderContext extends ReaderContext {
 	}
 
 
+	/**
+	 * Return the XML bean definition reader in use.
+	 */
 	public final XmlBeanDefinitionReader getReader() {
 		return this.reader;
 	}
 
+	/**
+	 * Return the bean definition registry to use.
+	 * @see XmlBeanDefinitionReader#XmlBeanDefinitionReader(BeanDefinitionRegistry)
+	 */
 	public final BeanDefinitionRegistry getRegistry() {
 		return this.reader.getRegistry();
 	}
 
+	/**
+	 * Return the resource loader to use, if any.
+	 * <p>This will be non-null in regular scenarios,
+	 * also allowing access to the resource class loader.
+	 * @see XmlBeanDefinitionReader#setResourceLoader
+	 * @see ResourceLoader#getClassLoader()
+	 */
 	@Nullable
 	public final ResourceLoader getResourceLoader() {
 		return this.reader.getResourceLoader();
 	}
 
+	/**
+	 * Return the bean class loader to use, if any.
+	 * <p>Note that this will be null in regular scenarios,
+	 * as an indication to lazily resolve bean classes.
+	 * @see XmlBeanDefinitionReader#setBeanClassLoader
+	 */
 	@Nullable
 	public final ClassLoader getBeanClassLoader() {
 		return this.reader.getBeanClassLoader();
 	}
 
+	/**
+	 * Return the environment to use.
+	 * @see XmlBeanDefinitionReader#setEnvironment
+	 */
 	public final Environment getEnvironment() {
 		return this.reader.getEnvironment();
 	}
 
+	/**
+	 * Return the namespace resolver.
+	 * @see XmlBeanDefinitionReader#setNamespaceHandlerResolver
+	 */
 	public final NamespaceHandlerResolver getNamespaceHandlerResolver() {
 		return this.namespaceHandlerResolver;
 	}
 
 
+	// Convenience methods to delegate to
+
+	/**
+	 * Call the bean name generator for the given bean definition.
+	 * @see XmlBeanDefinitionReader#getBeanNameGenerator()
+	 * @see org.springframework.beans.factory.support.BeanNameGenerator#generateBeanName
+	 */
 	public String generateBeanName(BeanDefinition beanDefinition) {
 		return this.reader.getBeanNameGenerator().generateBeanName(beanDefinition, getRegistry());
 	}
 
+	/**
+	 * Call the bean name generator for the given bean definition
+	 * and register the bean definition under the generated name.
+	 * @see XmlBeanDefinitionReader#getBeanNameGenerator()
+	 * @see org.springframework.beans.factory.support.BeanNameGenerator#generateBeanName
+	 * @see BeanDefinitionRegistry#registerBeanDefinition
+	 */
 	public String registerWithGeneratedName(BeanDefinition beanDefinition) {
 		String generatedName = generateBeanName(beanDefinition);
 		getRegistry().registerBeanDefinition(generatedName, beanDefinition);
 		return generatedName;
 	}
 
+	/**
+	 * Read an XML document from the given String.
+	 * @see #getReader()
+	 */
 	public Document readDocumentFromString(String documentContent) {
 		InputSource is = new InputSource(new StringReader(documentContent));
 		try {

spring-orm/src/main/java/org/springframework/orm/hibernate5/support/OpenSessionInterceptor.java

@@ -100,24 +100,38 @@ public class OpenSessionInterceptor implements MethodInterceptor, InitializingBe
 	}
 
 	/**
-	 * Open a Session for the SessionFactory that this interceptor uses.
+	 * Open a Session for the given SessionFactory.
 	 * <p>The default implementation delegates to the {@link SessionFactory#openSession}
 	 * method and sets the {@link Session}'s flush mode to "MANUAL".
+	 * @param sessionFactory the SessionFactory to use
 	 * @return the Session to use
 	 * @throws DataAccessResourceFailureException if the Session could not be created
-	 * @since 4.3.9
+	 * @since 5.0
 	 * @see FlushMode#MANUAL
 	 */
 	@SuppressWarnings("deprecation")
 	protected Session openSession(SessionFactory sessionFactory) throws DataAccessResourceFailureException {
-		try {
+		Session session = openSession();
-			Session session = sessionFactory.openSession();
+		if (session == null) {
-			session.setFlushMode(FlushMode.MANUAL);
+			try {
-			return session;
+				session = sessionFactory.openSession();
-		}
+				session.setFlushMode(FlushMode.MANUAL);
-		catch (HibernateException ex) {
+			}
-			throw new DataAccessResourceFailureException("Could not open Hibernate Session", ex);
+			catch (HibernateException ex) {
+				throw new DataAccessResourceFailureException("Could not open Hibernate Session", ex);
+			}
 		}
+		return session;
+	}
+
+	/**
+	 * Open a Session for the given SessionFactory.
+	 * @deprecated as of 5.0, in favor of {@link #openSession(SessionFactory)}
+	 */
+	@Deprecated
+	@Nullable
+	protected Session openSession() throws DataAccessResourceFailureException {
+		return null;
 	}
 
 }

spring-web/src/main/java/org/springframework/web/filter/ForwardedHeaderFilter.java

@@ -143,7 +143,6 @@ public class ForwardedHeaderFilter extends OncePerRequestFilter {
 
 		private final Map<String, List<String>> headers;
 
-
 		public ForwardedHeaderRemovingRequest(HttpServletRequest request) {
 			super(request);
 			this.headers = initHeaders(request);
@@ -182,6 +181,7 @@ public class ForwardedHeaderFilter extends OncePerRequestFilter {
 		}
 	}
 
+
 	/**
 	 * Extract and use "Forwarded" or "X-Forwarded-*" headers.
 	 */
@@ -201,7 +201,6 @@ public class ForwardedHeaderFilter extends OncePerRequestFilter {
 
 		private final String requestUrl;
 
-
 		public ForwardedHeaderExtractingRequest(HttpServletRequest request, UrlPathHelper pathHelper) {
 			super(request);
 
@@ -279,10 +278,8 @@ public class ForwardedHeaderFilter extends OncePerRequestFilter {
 
 		private static final String FOLDER_SEPARATOR = "/";
 
-
 		private final HttpServletRequest request;
 
-
 		public ForwardedHeaderExtractingResponse(HttpServletResponse response, HttpServletRequest request) {
 			super(response);
 			this.request = request;