Polishing

spring-aop/src/main/java/org/springframework/aop/aspectj/annotation/ReflectiveAspectJAdvisorFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -80,9 +80,8 @@ public class ReflectiveAspectJAdvisorFactory extends AbstractAspectJAdvisorFacto
 				new Converter<Method, Annotation>() {
 					@Override
 					public Annotation convert(Method method) {
-						AspectJAnnotation<?> annotation =
-								AbstractAspectJAdvisorFactory.findAspectJAnnotationOnMethod(method);
-						return (annotation != null ? annotation.getAnnotation() : null);
+						AspectJAnnotation<?> ann = AbstractAspectJAdvisorFactory.findAspectJAnnotationOnMethod(method);
+						return (ann != null ? ann.getAnnotation() : null);
 					}
 				}));
 		comparator.addComparator(new ConvertingComparator<Method, String>(

spring-aop/src/main/java/org/springframework/aop/aspectj/autoproxy/AspectJPrecedenceComparator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -136,14 +136,8 @@ class AspectJPrecedenceComparator implements Comparator<Advisor> {
 	}
 
 	private int getAspectDeclarationOrder(Advisor anAdvisor) {
-		AspectJPrecedenceInformation precedenceInfo =
-			AspectJAopUtils.getAspectJPrecedenceInformationFor(anAdvisor);
-		if (precedenceInfo != null) {
-			return precedenceInfo.getDeclarationOrder();
-		}
-		else {
-			return 0;
-		}
+		AspectJPrecedenceInformation precedenceInfo = AspectJAopUtils.getAspectJPrecedenceInformationFor(anAdvisor);
+		return (precedenceInfo != null ? precedenceInfo.getDeclarationOrder() : 0);
 	}
 
 }

spring-aop/src/main/java/org/springframework/aop/config/AopNamespaceHandler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -61,12 +61,12 @@ public class AopNamespaceHandler extends NamespaceHandlerSupport {
 	 */
 	@Override
 	public void init() {
-		// In 2.0 XSD as well as in 2.1 XSD.
+		// In 2.0 XSD as well as in 2.5+ XSDs
 		registerBeanDefinitionParser("config", new ConfigBeanDefinitionParser());
 		registerBeanDefinitionParser("aspectj-autoproxy", new AspectJAutoProxyBeanDefinitionParser());
 		registerBeanDefinitionDecorator("scoped-proxy", new ScopedProxyBeanDefinitionDecorator());
 
-		// Only in 2.0 XSD: moved to context namespace as of 2.1
+		// Only in 2.0 XSD: moved to context namespace in 2.5+
 		registerBeanDefinitionParser("spring-configured", new SpringConfiguredBeanDefinitionParser());
 	}
 

spring-beans/src/main/java/org/springframework/beans/CachedIntrospectionResults.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2020 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 @@ import org.springframework.util.StringUtils;
  * Internal class that caches JavaBeans {@link java.beans.PropertyDescriptor}
  * information for a Java class. Not intended for direct use by application code.
  *
- * <p>Necessary for own caching of descriptors within the application's
- * ClassLoader, rather than rely on the JDK's system-wide BeanInfo cache
- * (in order to avoid leaks on ClassLoader shutdown).
+ * <p>Necessary for Spring's own caching of bean descriptors within the application
+ * {@link ClassLoader}, rather than relying on the JDK's system-wide {@link BeanInfo}
+ * cache (in order to avoid leaks on individual application shutdown in a shared JVM).
  *
  * <p>Information is cached statically, so we don't need to create new
  * objects of this class for every JavaBean we manipulate. Hence, this class
@@ -97,7 +97,7 @@ public class CachedIntrospectionResults {
 			SpringProperties.getFlag(IGNORE_BEANINFO_PROPERTY_NAME);
 
 	/** Stores the BeanInfoFactory instances */
-	private static List<BeanInfoFactory> beanInfoFactories = SpringFactoriesLoader.loadFactories(
+	private static final List<BeanInfoFactory> beanInfoFactories = SpringFactoriesLoader.loadFactories(
 			BeanInfoFactory.class, CachedIntrospectionResults.class.getClassLoader());
 
 	private static final Log logger = LogFactory.getLog(CachedIntrospectionResults.class);

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -41,12 +41,11 @@ import java.lang.annotation.Target;
  * regular constructors: i.e. lookup methods cannot get replaced on beans returned
  * from factory methods where we cannot dynamically provide a subclass for them.
  *
- * <p><b>Concrete limitations in typical Spring configuration scenarios:</b>
- * When used with component scanning or any other mechanism that filters out abstract
- * beans, provide stub implementations of your lookup methods to be able to declare
- * them as concrete classes. And please remember that lookup methods won't work on
- * beans returned from {@code @Bean} methods in configuration classes; you'll have
- * to resort to {@code @Inject Provider&lt;TargetBean&gt;} or the like instead.
+ * <p><b>Recommendations for typical Spring configuration scenarios:</b>
+ * When a concrete class may be needed in certain scenarios, consider providing stub
+ * implementations of your lookup methods. And please remember that lookup methods
+ * won't work on beans returned from {@code @Bean} methods in configuration classes;
+ * you'll have to resort to {@code @Inject Provider<TargetBean>} or the like instead.
  *
  * @author Juergen Hoeller
  * @since 4.1

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

@@ -879,7 +879,7 @@ public abstract class AbstractBeanFactory extends FactoryBeanRegistrySupport imp
 
 	/**
 	 * Return whether this factory holds a InstantiationAwareBeanPostProcessor
-	 * that will get applied to singleton beans on shutdown.
+	 * that will get applied to singleton beans on creation.
 	 * @see #addBeanPostProcessor
 	 * @see org.springframework.beans.factory.config.InstantiationAwareBeanPostProcessor
 	 */
@@ -1508,7 +1508,7 @@ public abstract class AbstractBeanFactory extends FactoryBeanRegistrySupport imp
 	 * should be used as fallback.
 	 * @param beanName the name of the bean
 	 * @param mbd the merged bean definition for the bean
-	 * @return the type for the bean if determinable, or {@code null} else
+	 * @return the type for the bean if determinable, or {@code null} otherwise
 	 * @see org.springframework.beans.factory.FactoryBean#getObjectType()
 	 * @see #getBean(String)
 	 */

spring-context-support/src/main/java/org/springframework/cache/caffeine/CaffeineCache.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -35,6 +35,7 @@ import org.springframework.util.Assert;
  * @author Juergen Hoeller
  * @author Stephane Nicoll
  * @since 4.3
+ * @see CaffeineCacheManager
  */
 @UsesJava8
 public class CaffeineCache extends AbstractValueAdaptingCache {

spring-context-support/src/main/java/org/springframework/cache/ehcache/EhCacheCache.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -92,7 +92,6 @@ public class EhCacheCache implements Cache {
 				this.cache.releaseWriteLockOnKey(key);
 			}
 		}
-
 	}
 
 	private <T> T loadValue(Object key, Callable<T> valueLoader) {

spring-context-support/src/main/java/org/springframework/cache/ehcache/EhCacheCacheManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -32,6 +32,7 @@ import org.springframework.cache.transaction.AbstractTransactionSupportingCacheM
  * @author Juergen Hoeller
  * @author Stephane Nicoll
  * @since 3.1
+ * @see EhCacheCache
  */
 public class EhCacheCacheManager extends AbstractTransactionSupportingCacheManager {
 

spring-context-support/src/main/java/org/springframework/cache/jcache/JCacheCache.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -27,13 +27,14 @@ import org.springframework.util.Assert;
 
 /**
  * {@link org.springframework.cache.Cache} implementation on top of a
- * {@link javax.cache.Cache} instance.
+ * {@link Cache javax.cache.Cache} instance.
  *
  * <p>Note: This class has been updated for JCache 1.0, as of Spring 4.0.
  *
  * @author Juergen Hoeller
  * @author Stephane Nicoll
  * @since 3.2
+ * @see JCacheCacheManager
  */
 public class JCacheCache extends AbstractValueAdaptingCache {
 
@@ -41,7 +42,7 @@ public class JCacheCache extends AbstractValueAdaptingCache {
 
 
 	/**
-	 * Create an {@link org.springframework.cache.jcache.JCacheCache} instance.
+	 * Create a {@code JCacheCache} instance.
 	 * @param jcache backing JCache Cache instance
 	 */
 	public JCacheCache(Cache<Object, Object> jcache) {
@@ -49,7 +50,7 @@ public class JCacheCache extends AbstractValueAdaptingCache {
 	}
 
 	/**
-	 * Create an {@link org.springframework.cache.jcache.JCacheCache} instance.
+	 * Create a {@code JCacheCache} instance.
 	 * @param jcache backing JCache Cache instance
 	 * @param allowNullValues whether to accept and convert null values for this cache
 	 */
@@ -123,7 +124,7 @@ public class JCacheCache extends AbstractValueAdaptingCache {
 				}
 				catch (Exception ex) {
 					throw new EntryProcessorException("Value loader '" + valueLoader + "' failed " +
-							"to compute  value for key '" + entry.getKey() + "'", ex);
+							"to compute value for key '" + entry.getKey() + "'", ex);
 				}
 				entry.setValue(toStoreValue(value));
 				return value;

spring-context-support/src/main/java/org/springframework/cache/jcache/JCacheCacheManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -26,7 +26,7 @@ import org.springframework.cache.transaction.AbstractTransactionSupportingCacheM
 
 /**
  * {@link org.springframework.cache.CacheManager} implementation
- * backed by a JCache {@link javax.cache.CacheManager}.
+ * backed by a JCache {@link CacheManager javax.cache.CacheManager}.
  *
  * <p>Note: This class has been updated for JCache 1.0, as of Spring 4.0.
  *
@@ -42,15 +42,18 @@ public class JCacheCacheManager extends AbstractTransactionSupportingCacheManage
 
 
 	/**
-	 * Create a new JCacheCacheManager, setting the target JCache CacheManager
-	 * through the {@link #setCacheManager} bean property.
+	 * Create a new {@code JCacheCacheManager} without a backing JCache
+	 * {@link CacheManager javax.cache.CacheManager}.
+	 * <p>The backing JCache {@code javax.cache.CacheManager} can be set via the
+	 * {@link #setCacheManager} bean property.
 	 */
 	public JCacheCacheManager() {
 	}
 
 	/**
-	 * Create a new JCacheCacheManager for the given backing JCache.
-	 * @param cacheManager the backing JCache {@link javax.cache.CacheManager}
+	 * Create a new {@code JCacheCacheManager} for the given backing JCache
+	 * {@link CacheManager javax.cache.CacheManager}.
+	 * @param cacheManager the backing JCache {@code javax.cache.CacheManager}
 	 */
 	public JCacheCacheManager(CacheManager cacheManager) {
 		this.cacheManager = cacheManager;
@@ -58,14 +61,14 @@ public class JCacheCacheManager extends AbstractTransactionSupportingCacheManage
 
 
 	/**
-	 * Set the backing JCache {@link javax.cache.CacheManager}.
+	 * Set the backing JCache {@link CacheManager javax.cache.CacheManager}.
 	 */
 	public void setCacheManager(CacheManager cacheManager) {
 		this.cacheManager = cacheManager;
 	}
 
 	/**
-	 * Return the backing JCache {@link javax.cache.CacheManager}.
+	 * Return the backing JCache {@link CacheManager javax.cache.CacheManager}.
 	 */
 	public CacheManager getCacheManager() {
 		return this.cacheManager;

spring-context/src/main/java/org/springframework/cache/support/NoOpCache.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -29,6 +29,7 @@ import org.springframework.util.Assert;
  * @author Costin Leau
  * @author Stephane Nicoll
  * @since 4.3.4
+ * @see NoOpCacheManager
  */
 public class NoOpCache implements Cache {
 
@@ -36,7 +37,7 @@ public class NoOpCache implements Cache {
 
 
 	/**
-	 * Create a {@link NoOpCache} instance with the specified name
+	 * Create a {@link NoOpCache} instance with the specified name.
 	 * @param name the name of the cache
 	 */
 	public NoOpCache(String name) {

spring-context/src/main/java/org/springframework/cache/support/NoOpCacheManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -36,7 +36,7 @@ import org.springframework.cache.CacheManager;
  * @author Costin Leau
  * @author Stephane Nicoll
  * @since 3.1
- * @see CompositeCacheManager
+ * @see NoOpCache
  */
 public class NoOpCacheManager implements CacheManager {
 

spring-jdbc/src/main/java/org/springframework/jdbc/core/JdbcOperations.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -97,7 +97,7 @@ public interface JdbcOperations {
 	 * @param rse a callback that will extract all rows of results
 	 * @return an arbitrary result object, as returned by the ResultSetExtractor
 	 * @throws DataAccessException if there is any problem executing the query
-	 * @see #query(String, Object[], ResultSetExtractor)
+	 * @see #query(String, ResultSetExtractor, Object...)
 	 */
 	<T> T query(String sql, ResultSetExtractor<T> rse) throws DataAccessException;
 
@@ -110,7 +110,7 @@ public interface JdbcOperations {
 	 * @param sql the SQL query to execute
 	 * @param rch a callback that will extract results, one row at a time
 	 * @throws DataAccessException if there is any problem executing the query
-	 * @see #query(String, Object[], RowCallbackHandler)
+	 * @see #query(String, RowCallbackHandler, Object...)
 	 */
 	void query(String sql, RowCallbackHandler rch) throws DataAccessException;
 
@@ -124,7 +124,7 @@ public interface JdbcOperations {
 	 * @param rowMapper a callback that will map one object per row
 	 * @return the result List, containing mapped objects
 	 * @throws DataAccessException if there is any problem executing the query
-	 * @see #query(String, Object[], RowMapper)
+	 * @see #query(String, RowMapper, Object...)
 	 */
 	<T> List<T> query(String sql, RowMapper<T> rowMapper) throws DataAccessException;
 
@@ -142,7 +142,7 @@ public interface JdbcOperations {
 	 * @throws IncorrectResultSizeDataAccessException if the query does not
 	 * return exactly one row
 	 * @throws DataAccessException if there is any problem executing the query
-	 * @see #queryForObject(String, Object[], RowMapper)
+	 * @see #queryForObject(String, RowMapper, Object...)
 	 */
 	<T> T queryForObject(String sql, RowMapper<T> rowMapper) throws DataAccessException;
 
@@ -161,7 +161,7 @@ public interface JdbcOperations {
 	 * @throws IncorrectResultSizeDataAccessException if the query does not return
 	 * exactly one row, or does not return exactly one column in that row
 	 * @throws DataAccessException if there is any problem executing the query
-	 * @see #queryForObject(String, Object[], Class)
+	 * @see #queryForObject(String, Class, Object...)
 	 */
 	<T> T queryForObject(String sql, Class<T> requiredType) throws DataAccessException;
 
@@ -178,7 +178,7 @@ public interface JdbcOperations {
 	 * @throws IncorrectResultSizeDataAccessException if the query does not
 	 * return exactly one row
 	 * @throws DataAccessException if there is any problem executing the query
-	 * @see #queryForMap(String, Object[])
+	 * @see #queryForMap(String, Object...)
 	 * @see ColumnMapRowMapper
 	 */
 	Map<String, Object> queryForMap(String sql) throws DataAccessException;
@@ -195,7 +195,7 @@ public interface JdbcOperations {
 	 * (for example, {@code Integer.class})
 	 * @return a List of objects that match the specified element type
 	 * @throws DataAccessException if there is any problem executing the query
-	 * @see #queryForList(String, Object[], Class)
+	 * @see #queryForList(String, Class, Object...)
 	 * @see SingleColumnRowMapper
 	 */
 	<T> List<T> queryForList(String sql, Class<T> elementType) throws DataAccessException;
@@ -212,7 +212,7 @@ public interface JdbcOperations {
 	 * @param sql the SQL query to execute
 	 * @return an List that contains a Map per row
 	 * @throws DataAccessException if there is any problem executing the query
-	 * @see #queryForList(String, Object[])
+	 * @see #queryForList(String, Object...)
 	 */
 	List<Map<String, Object>> queryForList(String sql) throws DataAccessException;
 
@@ -231,7 +231,7 @@ public interface JdbcOperations {
 	 * @return a SqlRowSet representation (possibly a wrapper around a
 	 * {@code javax.sql.rowset.CachedRowSet})
 	 * @throws DataAccessException if there is any problem executing the query
-	 * @see #queryForRowSet(String, Object[])
+	 * @see #queryForRowSet(String, Object...)
 	 * @see SqlRowSetResultSetExtractor
 	 * @see javax.sql.rowset.CachedRowSet
 	 */
@@ -884,6 +884,7 @@ public interface JdbcOperations {
 	 * @param sql the SQL statement to execute
 	 * @param batchArgs the List of Object arrays containing the batch of arguments for the query
 	 * @return an array containing the numbers of rows affected by each update in the batch
+	 * @throws DataAccessException if there is any problem issuing the update
 	 */
 	int[] batchUpdate(String sql, List<Object[]> batchArgs) throws DataAccessException;
 
@@ -894,6 +895,7 @@ public interface JdbcOperations {
 	 * @param argTypes the SQL types of the arguments
 	 * (constants from {@code java.sql.Types})
 	 * @return an array containing the numbers of rows affected by each update in the batch
+	 * @throws DataAccessException if there is any problem issuing the update
 	 */
 	int[] batchUpdate(String sql, List<Object[]> batchArgs, int[] argTypes) throws DataAccessException;
 
@@ -907,6 +909,7 @@ public interface JdbcOperations {
 	 * @param pss the ParameterizedPreparedStatementSetter to use
 	 * @return an array containing for each batch another array containing the numbers of rows affected
 	 * by each update in the batch
+	 * @throws DataAccessException if there is any problem issuing the update
 	 * @since 3.1
 	 */
 	<T> int[][] batchUpdate(String sql, Collection<T> batchArgs, int batchSize,

spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcOperations.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -61,7 +61,7 @@ public interface NamedParameterJdbcOperations {
 	 * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
 	 * <p>The callback action can return a result object, for example a
 	 * domain object or a collection of domain objects.
-	 * @param sql SQL to execute
+	 * @param sql the SQL to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @param action callback object that specifies the action
 	 * @return a result object returned by the action, or {@code null}
@@ -78,7 +78,7 @@ public interface NamedParameterJdbcOperations {
 	 * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
 	 * <p>The callback action can return a result object, for example a
 	 * domain object or a collection of domain objects.
-	 * @param sql SQL to execute
+	 * @param sql the SQL to execute
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @param action callback object that specifies the action
@@ -96,7 +96,7 @@ public interface NamedParameterJdbcOperations {
 	 * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
 	 * <p>The callback action can return a result object, for example a
 	 * domain object or a collection of domain objects.
-	 * @param sql SQL to execute
+	 * @param sql the SQL to execute
 	 * @param action callback object that specifies the action
 	 * @return a result object returned by the action, or {@code null}
 	 * @throws DataAccessException if there is any problem
@@ -107,7 +107,7 @@ public interface NamedParameterJdbcOperations {
 	 * Query given SQL to create a prepared statement from SQL and a list
 	 * of arguments to bind to the query, reading the ResultSet with a
 	 * ResultSetExtractor.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @param rse object that will extract results
 	 * @return an arbitrary result object, as returned by the ResultSetExtractor
@@ -120,12 +120,12 @@ public interface NamedParameterJdbcOperations {
 	 * Query given SQL to create a prepared statement from SQL and a list
 	 * of arguments to bind to the query, reading the ResultSet with a
 	 * ResultSetExtractor.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @param rse object that will extract results
 	 * @return an arbitrary result object, as returned by the ResultSetExtractor
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 */
 	<T> T query(String sql, Map<String, ?> paramMap, ResultSetExtractor<T> rse)
 			throws DataAccessException;
@@ -136,10 +136,10 @@ public interface NamedParameterJdbcOperations {
 	 * <p>Note: In contrast to the JdbcOperations method with the same signature,
 	 * this query variant always uses a PreparedStatement. It is effectively
 	 * equivalent to a query call with an empty parameter Map.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param rse object that will extract results
 	 * @return an arbitrary result object, as returned by the ResultSetExtractor
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 */
 	<T> T query(String sql, ResultSetExtractor<T> rse) throws DataAccessException;
 
@@ -147,7 +147,7 @@ public interface NamedParameterJdbcOperations {
 	 * Query given SQL to create a prepared statement from SQL and a list of
 	 * arguments to bind to the query, reading the ResultSet on a per-row basis
 	 * with a RowCallbackHandler.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @param rch object that will extract results, one row at a time
 	 * @throws DataAccessException if the query fails
@@ -159,11 +159,11 @@ public interface NamedParameterJdbcOperations {
 	 * Query given SQL to create a prepared statement from SQL and a list of
 	 * arguments to bind to the query, reading the ResultSet on a per-row basis
 	 * with a RowCallbackHandler.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @param rch object that will extract results, one row at a time
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 */
 	void query(String sql, Map<String, ?> paramMap, RowCallbackHandler rch) throws DataAccessException;
 
@@ -173,9 +173,9 @@ public interface NamedParameterJdbcOperations {
 	 * <p>Note: In contrast to the JdbcOperations method with the same signature,
 	 * this query variant always uses a PreparedStatement. It is effectively
 	 * equivalent to a query call with an empty parameter Map.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param rch object that will extract results, one row at a time
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 */
 	void query(String sql, RowCallbackHandler rch) throws DataAccessException;
 
@@ -183,11 +183,11 @@ public interface NamedParameterJdbcOperations {
 	 * Query given SQL to create a prepared statement from SQL and a list
 	 * of arguments to bind to the query, mapping each row to a Java object
 	 * via a RowMapper.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @param rowMapper object that will map one object per row
 	 * @return the result List, containing mapped objects
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 */
 	<T> List<T> query(String sql, SqlParameterSource paramSource, RowMapper<T> rowMapper)
 			throws DataAccessException;
@@ -196,12 +196,12 @@ public interface NamedParameterJdbcOperations {
 	 * Query given SQL to create a prepared statement from SQL and a list
 	 * of arguments to bind to the query, mapping each row to a Java object
 	 * via a RowMapper.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @param rowMapper object that will map one object per row
 	 * @return the result List, containing mapped objects
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 */
 	<T> List<T> query(String sql, Map<String, ?> paramMap, RowMapper<T> rowMapper)
 			throws DataAccessException;
@@ -212,10 +212,10 @@ public interface NamedParameterJdbcOperations {
 	 * <p>Note: In contrast to the JdbcOperations method with the same signature,
 	 * this query variant always uses a PreparedStatement. It is effectively
 	 * equivalent to a query call with an empty parameter Map.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param rowMapper object that will map one object per row
 	 * @return the result List, containing mapped objects
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 */
 	<T> List<T> query(String sql, RowMapper<T> rowMapper) throws DataAccessException;
 
@@ -223,7 +223,7 @@ public interface NamedParameterJdbcOperations {
 	 * Query given SQL to create a prepared statement from SQL and a list
 	 * of arguments to bind to the query, mapping a single result row to a
 	 * Java object via a RowMapper.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @param rowMapper object that will map one object per row
 	 * @return the single mapped object (may be {@code null} if the given
@@ -231,7 +231,7 @@ public interface NamedParameterJdbcOperations {
 	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
 	 * if the query does not return exactly one row, or does not return exactly
 	 * one column in that row
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 */
 	<T> T queryForObject(String sql, SqlParameterSource paramSource, RowMapper<T> rowMapper)
 			throws DataAccessException;
@@ -240,7 +240,7 @@ public interface NamedParameterJdbcOperations {
 	 * Query given SQL to create a prepared statement from SQL and a list
 	 * of arguments to bind to the query, mapping a single result row to a
 	 * Java object via a RowMapper.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @param rowMapper object that will map one object per row
@@ -249,7 +249,7 @@ public interface NamedParameterJdbcOperations {
 	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
 	 * if the query does not return exactly one row, or does not return exactly
 	 * one column in that row
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 */
 	<T> T queryForObject(String sql, Map<String, ?> paramMap, RowMapper<T> rowMapper)
 			throws DataAccessException;
@@ -259,14 +259,14 @@ public interface NamedParameterJdbcOperations {
 	 * list of arguments to bind to the query, expecting a result object.
 	 * <p>The query is expected to be a single row/single column query; the returned
 	 * result will be directly mapped to the corresponding object type.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @param requiredType the type that the result object is expected to match
 	 * @return the result object of the required type, or {@code null} in case of SQL NULL
 	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
 	 * if the query does not return exactly one row, or does not return exactly
 	 * one column in that row
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForObject(String, Class)
 	 */
 	<T> T queryForObject(String sql, SqlParameterSource paramSource, Class<T> requiredType)
@@ -277,7 +277,7 @@ public interface NamedParameterJdbcOperations {
 	 * list of arguments to bind to the query, expecting a result object.
 	 * <p>The query is expected to be a single row/single column query; the returned
 	 * result will be directly mapped to the corresponding object type.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @param requiredType the type that the result object is expected to match
@@ -285,7 +285,7 @@ public interface NamedParameterJdbcOperations {
 	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
 	 * if the query does not return exactly one row, or does not return exactly
 	 * one column in that row
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForObject(String, Class)
 	 */
 	<T> T queryForObject(String sql, Map<String, ?> paramMap, Class<T> requiredType)
@@ -296,12 +296,12 @@ public interface NamedParameterJdbcOperations {
 	 * list of arguments to bind to the query, expecting a result Map.
 	 * <p>The query is expected to be a single row query; the result row will be
 	 * mapped to a Map (one entry for each column, using the column name as the key).
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @return the result Map (one entry for each column, using the column name as the key)
 	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
 	 * if the query does not return exactly one row
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForMap(String)
 	 * @see org.springframework.jdbc.core.ColumnMapRowMapper
 	 */
@@ -315,13 +315,13 @@ public interface NamedParameterJdbcOperations {
 	 * one of the queryForObject() methods.
 	 * <p>The query is expected to be a single row query; the result row will be
 	 * mapped to a Map (one entry for each column, using the column name as the key).
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @return the result Map (one entry for each column, using the column name as the key)
 	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
 	 * if the query does not return exactly one row
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForMap(String)
 	 * @see org.springframework.jdbc.core.ColumnMapRowMapper
 	 */
@@ -332,12 +332,12 @@ public interface NamedParameterJdbcOperations {
 	 * list of arguments to bind to the query, expecting a result list.
 	 * <p>The results will be mapped to a List (one entry for each row) of
 	 * result objects, each of them matching the specified element type.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @param elementType the required type of element in the result list
 	 * (for example, {@code Integer.class})
 	 * @return a List of objects that match the specified element type
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String, Class)
 	 * @see org.springframework.jdbc.core.SingleColumnRowMapper
 	 */
@@ -349,13 +349,13 @@ public interface NamedParameterJdbcOperations {
 	 * list of arguments to bind to the query, expecting a result list.
 	 * <p>The results will be mapped to a List (one entry for each row) of
 	 * result objects, each of them matching the specified element type.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @param elementType the required type of element in the result list
 	 * (for example, {@code Integer.class})
 	 * @return a List of objects that match the specified element type
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String, Class)
 	 * @see org.springframework.jdbc.core.SingleColumnRowMapper
 	 */
@@ -369,10 +369,10 @@ public interface NamedParameterJdbcOperations {
 	 * Maps (one entry for each column, using the column name as the key).
 	 * Each element in the list will be of the form returned by this interface's
 	 * {@code queryForMap} methods.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @return a List that contains a Map per row
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String)
 	 */
 	List<Map<String, Object>> queryForList(String sql, SqlParameterSource paramSource) throws DataAccessException;
@@ -384,11 +384,11 @@ public interface NamedParameterJdbcOperations {
 	 * Maps (one entry for each column, using the column name as the key).
 	 * Each element in the list will be of the form returned by this interface's
 	 * {@code queryForMap} methods.
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @return a List that contains a Map per row
-	 * @throws org.springframework.dao.DataAccessException if the query fails
+	 * @throws DataAccessException if the query fails
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String)
 	 */
 	List<Map<String, Object>> queryForList(String sql, Map<String, ?> paramMap) throws DataAccessException;
@@ -402,11 +402,11 @@ public interface NamedParameterJdbcOperations {
 	 * be available at runtime: by default, Sun's {@code com.sun.rowset.CachedRowSetImpl}
 	 * class is used, which is part of JDK 1.5+ and also available separately as part of
 	 * Sun's JDBC RowSet Implementations download (rowset.jar).
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @return a SqlRowSet representation (possibly a wrapper around a
 	 * {@code javax.sql.rowset.CachedRowSet})
-	 * @throws org.springframework.dao.DataAccessException if there is any problem executing the query
+	 * @throws DataAccessException if there is any problem executing the query
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForRowSet(String)
 	 * @see org.springframework.jdbc.core.SqlRowSetResultSetExtractor
 	 * @see javax.sql.rowset.CachedRowSet
@@ -422,12 +422,12 @@ public interface NamedParameterJdbcOperations {
 	 * be available at runtime: by default, Sun's {@code com.sun.rowset.CachedRowSetImpl}
 	 * class is used, which is part of JDK 1.5+ and also available separately as part of
 	 * Sun's JDBC RowSet Implementations download (rowset.jar).
-	 * @param sql SQL query to execute
+	 * @param sql the SQL query to execute
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @return a SqlRowSet representation (possibly a wrapper around a
 	 * {@code javax.sql.rowset.CachedRowSet})
-	 * @throws org.springframework.dao.DataAccessException if there is any problem executing the query
+	 * @throws DataAccessException if there is any problem executing the query
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForRowSet(String)
 	 * @see org.springframework.jdbc.core.SqlRowSetResultSetExtractor
 	 * @see javax.sql.rowset.CachedRowSet
@@ -436,31 +436,31 @@ public interface NamedParameterJdbcOperations {
 
 	/**
 	 * Issue an update via a prepared statement, binding the given arguments.
-	 * @param sql SQL containing named parameters
+	 * @param sql the SQL containing named parameters
 	 * @param paramSource container of arguments and SQL types to bind to the query
 	 * @return the number of rows affected
-	 * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
+	 * @throws DataAccessException if there is any problem issuing the update
 	 */
 	int update(String sql, SqlParameterSource paramSource) throws DataAccessException;
 
 	/**
 	 * Issue an update via a prepared statement, binding the given arguments.
-	 * @param sql SQL containing named parameters
+	 * @param sql the SQL containing named parameters
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @return the number of rows affected
-	 * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
+	 * @throws DataAccessException if there is any problem issuing the update
 	 */
 	int update(String sql, Map<String, ?> paramMap) throws DataAccessException;
 
 	/**
 	 * Issue an update via a prepared statement, binding the given arguments,
 	 * returning generated keys.
-	 * @param sql SQL containing named parameters
+	 * @param sql the SQL containing named parameters
 	 * @param paramSource container of arguments and SQL types to bind to the query
-	 * @param generatedKeyHolder KeyHolder that will hold the generated keys
+	 * @param generatedKeyHolder a {@link KeyHolder} that will hold the generated keys
 	 * @return the number of rows affected
-	 * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
+	 * @throws DataAccessException if there is any problem issuing the update
 	 * @see MapSqlParameterSource
 	 * @see org.springframework.jdbc.support.GeneratedKeyHolder
 	 */
@@ -470,12 +470,12 @@ public interface NamedParameterJdbcOperations {
 	/**
 	 * Issue an update via a prepared statement, binding the given arguments,
 	 * returning generated keys.
-	 * @param sql SQL containing named parameters
+	 * @param sql the SQL containing named parameters
 	 * @param paramSource container of arguments and SQL types to bind to the query
-	 * @param generatedKeyHolder KeyHolder that will hold the generated keys
+	 * @param generatedKeyHolder a {@link KeyHolder} that will hold the generated keys
 	 * @param keyColumnNames names of the columns that will have keys generated for them
 	 * @return the number of rows affected
-	 * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
+	 * @throws DataAccessException if there is any problem issuing the update
 	 * @see MapSqlParameterSource
 	 * @see org.springframework.jdbc.support.GeneratedKeyHolder
 	 */
@@ -487,6 +487,7 @@ public interface NamedParameterJdbcOperations {
 	 * @param sql the SQL statement to execute
 	 * @param batchValues the array of Maps containing the batch of arguments for the query
 	 * @return an array containing the numbers of rows affected by each update in the batch
+	 * @throws DataAccessException if there is any problem issuing the update
 	 */
 	int[] batchUpdate(String sql, Map<String, ?>[] batchValues);
 
@@ -495,6 +496,7 @@ public interface NamedParameterJdbcOperations {
 	 * @param sql the SQL statement to execute
 	 * @param batchArgs the array of {@link SqlParameterSource} containing the batch of arguments for the query
 	 * @return an array containing the numbers of rows affected by each update in the batch
+	 * @throws DataAccessException if there is any problem issuing the update
 	 */
 	int[] batchUpdate(String sql, SqlParameterSource[] batchArgs);
 

spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DataSourceTransactionManager.java

@@ -178,7 +178,7 @@ public class DataSourceTransactionManager extends AbstractPlatformTransactionMan
 	 * through an explicit statement on the transactional connection:
 	 * "SET TRANSACTION READ ONLY" as understood by Oracle, MySQL and Postgres.
 	 * <p>The exact treatment, including any SQL statement executed on the connection,
-	 * can be customized through through {@link #prepareTransactionalConnection}.
+	 * can be customized through {@link #prepareTransactionalConnection}.
 	 * <p>This mode of read-only handling goes beyond the {@link Connection#setReadOnly}
 	 * hint that Spring applies by default. In contrast to that standard JDBC hint,
 	 * "SET TRANSACTION READ ONLY" enforces an isolation-level-like connection mode
@@ -233,9 +233,6 @@ public class DataSourceTransactionManager extends AbstractPlatformTransactionMan
 		return (txObject.hasConnectionHolder() && txObject.getConnectionHolder().isTransactionActive());
 	}
 
-	/**
-	 * This implementation sets the isolation level but ignores the timeout.
-	 */
 	@Override
 	protected void doBegin(Object transaction, TransactionDefinition definition) {
 		DataSourceTransactionObject txObject = (DataSourceTransactionObject) transaction;

spring-orm/src/main/java/org/springframework/orm/jpa/JpaTransactionManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -133,7 +133,7 @@ public class JpaTransactionManager extends AbstractPlatformTransactionManager
 
 	/**
 	 * Create a new JpaTransactionManager instance.
-	 * @param emf EntityManagerFactory to manage transactions for
+	 * @param emf the EntityManagerFactory to manage transactions for
 	 */
 	public JpaTransactionManager(EntityManagerFactory emf) {
 		this();
@@ -400,8 +400,7 @@ public class JpaTransactionManager extends AbstractPlatformTransactionManager
 						conHolder.setTimeoutInSeconds(timeoutToUse);
 					}
 					if (logger.isDebugEnabled()) {
-						logger.debug("Exposing JPA transaction as JDBC transaction [" +
-								conHolder.getConnectionHandle() + "]");
+						logger.debug("Exposing JPA transaction as JDBC [" + conHolder.getConnectionHandle() + "]");
 					}
 					TransactionSynchronizationManager.bindResource(getDataSource(), conHolder);
 					txObject.setConnectionHolder(conHolder);
@@ -581,13 +580,16 @@ public class JpaTransactionManager extends AbstractPlatformTransactionManager
 		// Remove the JDBC connection holder from the thread, if exposed.
 		if (txObject.hasConnectionHolder()) {
 			TransactionSynchronizationManager.unbindResource(getDataSource());
-			try {
-				getJpaDialect().releaseJdbcConnection(txObject.getConnectionHolder().getConnectionHandle(),
-						txObject.getEntityManagerHolder().getEntityManager());
-			}
-			catch (Exception ex) {
-				// Just log it, to keep a transaction-related exception.
-				logger.error("Could not close JDBC connection after transaction", ex);
+			ConnectionHandle conHandle = txObject.getConnectionHolder().getConnectionHandle();
+			if (conHandle != null) {
+				try {
+					getJpaDialect().releaseJdbcConnection(conHandle,
+							txObject.getEntityManagerHolder().getEntityManager());
+				}
+				catch (Throwable ex) {
+					// Just log it, to keep a transaction-related exception.
+					logger.error("Failed to release JDBC connection after transaction", ex);
+				}
 			}
 		}