Polishing

Author: jhoeller

spring-aop/src/main/java/org/springframework/aop/framework/autoproxy/AbstractAutoProxyCreator.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.
@@ -412,7 +412,7 @@ protected TargetSource getCustomTargetSource(Class<?> beanClass, String beanName
 					// Found a matching TargetSource.
 					if (logger.isDebugEnabled()) {
 						logger.debug("TargetSourceCreator [" + tsc +
-								" found custom TargetSource for bean with name '" + beanName + "'");
+								"] found custom TargetSource for bean with name '" + beanName + "'");
 					}
 					return ts;
 				}
@@ -553,7 +553,7 @@ private Advisor[] resolveInterceptorNames() {
 	 * Subclasses may choose to implement this: for example,
 	 * to change the interfaces exposed.
 	 * <p>The default implementation is empty.
-	 * @param proxyFactory ProxyFactory that is already configured with
+	 * @param proxyFactory a ProxyFactory that is already configured with
 	 * TargetSource and interfaces and will be used to create the proxy
 	 * immediately after this method returns
 	 */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 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.
@@ -80,9 +80,8 @@ public void inject(Object target, String beanName, PropertyValues pvs) throws Th
 		Collection<InjectedElement> elementsToIterate =
 				(this.checkedElements != null ? this.checkedElements : this.injectedElements);
 		if (!elementsToIterate.isEmpty()) {
-			boolean debug = logger.isDebugEnabled();
 			for (InjectedElement element : elementsToIterate) {
-				if (debug) {
+				if (logger.isDebugEnabled()) {
 					logger.debug("Processing injected element of bean '" + beanName + "': " + element);
 				}
 				element.inject(target, beanName, pvs);
@@ -109,7 +108,10 @@ public static boolean needsRefresh(InjectionMetadata metadata, Class<?> clazz) {
 	}
 
 
-	public static abstract class InjectedElement {
+	/**
+	 * A single injected element.
+	 */
+	public abstract static class InjectedElement {
 
 		protected final Member member;
 
@@ -216,6 +218,7 @@ else if (pvs instanceof MutablePropertyValues) {
 		}
 
 		/**
+		 * Clear property skipping for this element.
 		 * @since 3.2.13
 		 */
 		protected void clearPropertySkipping(PropertyValues pvs) {

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

@@ -541,29 +541,29 @@ public <T> Map<String, T> getBeansOfType(Class<T> type, boolean includeNonSingle
 
 	@Override
 	public String[] getBeanNamesForAnnotation(Class<? extends Annotation> annotationType) {
-		List<String> results = new ArrayList<String>();
+		List<String> result = new ArrayList<String>();
 		for (String beanName : this.beanDefinitionNames) {
 			BeanDefinition beanDefinition = getBeanDefinition(beanName);
 			if (!beanDefinition.isAbstract() && findAnnotationOnBean(beanName, annotationType) != null) {
-				results.add(beanName);
+				result.add(beanName);
 			}
 		}
 		for (String beanName : this.manualSingletonNames) {
-			if (!results.contains(beanName) && findAnnotationOnBean(beanName, annotationType) != null) {
-				results.add(beanName);
+			if (!result.contains(beanName) && findAnnotationOnBean(beanName, annotationType) != null) {
+				result.add(beanName);
 			}
 		}
-		return StringUtils.toStringArray(results);
+		return StringUtils.toStringArray(result);
 	}
 
 	@Override
 	public Map<String, Object> getBeansWithAnnotation(Class<? extends Annotation> annotationType) {
 		String[] beanNames = getBeanNamesForAnnotation(annotationType);
-		Map<String, Object> results = new LinkedHashMap<String, Object>(beanNames.length);
+		Map<String, Object> result = new LinkedHashMap<String, Object>(beanNames.length);
 		for (String beanName : beanNames) {
-			results.put(beanName, getBean(beanName));
+			result.put(beanName, getBean(beanName));
 		}
-		return results;
+		return result;
 	}
 
 	/**

spring-context/src/main/java/org/springframework/context/event/GenericApplicationListener.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 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.
@@ -23,23 +23,27 @@
 
 /**
  * Extended variant of the standard {@link ApplicationListener} interface,
- * exposing further metadata such as the supported event type.
+ * exposing further metadata such as the supported event and source type.
  *
- * <p>As of Spring Framework 4.2, supersedes {@link SmartApplicationListener} with
- * proper handling of generics-based event.
+ * <p>As of Spring Framework 4.2, this interface supersedes the Class-based
+ * {@link SmartApplicationListener} with full handling of generic event types.
  *
  * @author Stephane Nicoll
  * @since 4.2
+ * @see SmartApplicationListener
+ * @see GenericApplicationListenerAdapter
  */
 public interface GenericApplicationListener extends ApplicationListener<ApplicationEvent>, Ordered {
 
 	/**
 	 * Determine whether this listener actually supports the given event type.
+	 * @param eventType the event type (never {@code null})
 	 */
 	boolean supportsEventType(ResolvableType eventType);
 
 	/**
 	 * Determine whether this listener actually supports the given source type.
+	 * @param sourceType the source type, or {@code null} if no source
 	 */
 	boolean supportsSourceType(Class<?> sourceType);
 

spring-context/src/main/java/org/springframework/context/event/SmartApplicationListener.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 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,25 +22,27 @@
 
 /**
  * Extended variant of the standard {@link ApplicationListener} interface,
- * exposing further metadata such as the supported event type.
+ * exposing further metadata such as the supported event and source type.
  *
- * <p>Users are <bold>strongly advised</bold> to use the {@link GenericApplicationListener}
- * interface instead as it provides an improved detection of generics-based
- * event types.
+ * <p>For full introspection of generic event types, consider implementing
+ * the {@link GenericApplicationListener} interface instead.
  *
  * @author Juergen Hoeller
  * @since 3.0
  * @see GenericApplicationListener
+ * @see GenericApplicationListenerAdapter
  */
 public interface SmartApplicationListener extends ApplicationListener<ApplicationEvent>, Ordered {
 
 	/**
 	 * Determine whether this listener actually supports the given event type.
+	 * @param eventType the event type (never {@code null})
 	 */
 	boolean supportsEventType(Class<? extends ApplicationEvent> eventType);
 
 	/**
 	 * Determine whether this listener actually supports the given source type.
+	 * @param sourceType the source type, or {@code null} if no source
 	 */
 	boolean supportsSourceType(Class<?> sourceType);
 

spring-tx/src/main/java/org/springframework/transaction/TransactionStatus.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.
@@ -25,7 +25,7 @@
  * and to programmatically request a rollback (instead of throwing
  * an exception that causes an implicit rollback).
  *
- * <p>Derives from the SavepointManager interface to provide access
+ * <p>Includes the {@link SavepointManager} interface to provide access
  * to savepoint management facilities. Note that savepoint management
  * is only available if supported by the underlying transaction manager.
  *
@@ -39,9 +39,9 @@
 public interface TransactionStatus extends SavepointManager, Flushable {
 
 	/**
-	 * Return whether the present transaction is new (else participating
-	 * in an existing transaction, or potentially not running in an
-	 * actual transaction in the first place).
+	 * Return whether the present transaction is new; otherwise participating
+	 * in an existing transaction, or potentially not running in an actual
+	 * transaction in the first place.
 	 */
 	boolean isNewTransaction();
 
@@ -50,9 +50,9 @@ public interface TransactionStatus extends SavepointManager, Flushable {
 	 * that is, has been created as nested transaction based on a savepoint.
 	 * <p>This method is mainly here for diagnostic purposes, alongside
 	 * {@link #isNewTransaction()}. For programmatic handling of custom
-	 * savepoints, use SavepointManager's operations.
+	 * savepoints, use the operations provided by {@link SavepointManager}.
 	 * @see #isNewTransaction()
-	 * @see #createSavepoint
+	 * @see #createSavepoint()
 	 * @see #rollbackToSavepoint(Object)
 	 * @see #releaseSavepoint(Object)
 	 */

spring-tx/src/main/java/org/springframework/transaction/interceptor/DefaultTransactionAttribute.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.
@@ -17,6 +17,7 @@
 package org.springframework.transaction.interceptor;
 
 import org.springframework.transaction.support.DefaultTransactionDefinition;
+import org.springframework.util.StringUtils;
 
 /**
  * Spring's common transaction attribute implementation.
@@ -136,7 +137,7 @@ public boolean rollbackOn(Throwable ex) {
 	 */
 	protected final StringBuilder getAttributeDescription() {
 		StringBuilder result = getDefinitionDescription();
-		if (this.qualifier != null) {
+		if (StringUtils.hasText(this.qualifier)) {
 			result.append("; '").append(this.qualifier).append("'");
 		}
 		return result;

spring-tx/src/main/java/org/springframework/transaction/support/DefaultTransactionStatus.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 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.
@@ -62,14 +62,14 @@ public class DefaultTransactionStatus extends AbstractTransactionStatus {
 
 
 	/**
-	 * Create a new DefaultTransactionStatus instance.
-	 * @param transaction underlying transaction object that can hold
-	 * state for the internal transaction implementation
-	 * @param newTransaction if the transaction is new,
-	 * else participating in an existing transaction
-	 * @param newSynchronization if a new transaction synchronization
-	 * has been opened for the given transaction
-	 * @param readOnly whether the transaction is read-only
+	 * Create a new {@code DefaultTransactionStatus} instance.
+	 * @param transaction underlying transaction object that can hold state
+	 * for the internal transaction implementation
+	 * @param newTransaction if the transaction is new, otherwise participating
+	 * in an existing transaction
+	 * @param newSynchronization if a new transaction synchronization has been
+	 * opened for the given transaction
+	 * @param readOnly whether the transaction is marked as read-only
 	 * @param debug should debug logging be enabled for the handling of this transaction?
 	 * Caching it in here can prevent repeated calls to ask the logging system whether
 	 * debug logging should be enabled.
@@ -124,9 +124,9 @@ public boolean isReadOnly() {
 	}
 
 	/**
-	 * Return whether the progress of this transaction is debugged. This is used
-	 * by AbstractPlatformTransactionManager as an optimization, to prevent repeated
-	 * calls to logger.isDebug(). Not really intended for client code.
+	 * Return whether the progress of this transaction is debugged. This is used by
+	 * {@link AbstractPlatformTransactionManager} as an optimization, to prevent repeated
+	 * calls to {@code logger.isDebugEnabled()}. Not really intended for client code.
 	 */
 	public boolean isDebug() {
 		return this.debug;
@@ -146,11 +146,11 @@ public Object getSuspendedResources() {
 	//---------------------------------------------------------------------
 
 	/**
-	 * Determine the rollback-only flag via checking both the transaction object,
-	 * provided that the latter implements the {@link SmartTransactionObject} interface.
-	 * <p>Will return "true" if the transaction itself has been marked rollback-only
-	 * by the transaction coordinator, for example in case of a timeout.
-	 * @see SmartTransactionObject#isRollbackOnly
+	 * Determine the rollback-only flag via checking the transaction object, provided
+	 * that the latter implements the {@link SmartTransactionObject} interface.
+	 * <p>Will return {@code true} if the global transaction itself has been marked
+	 * rollback-only by the transaction coordinator, for example in case of a timeout.
+	 * @see SmartTransactionObject#isRollbackOnly()
 	 */
 	@Override
 	public boolean isGlobalRollbackOnly() {
@@ -159,8 +159,9 @@ public boolean isGlobalRollbackOnly() {
 	}
 
 	/**
-	 * Delegate the flushing to the transaction object,
-	 * provided that the latter implements the {@link SmartTransactionObject} interface.
+	 * Delegate the flushing to the transaction object, provided that the latter
+	 * implements the {@link SmartTransactionObject} interface.
+	 * @see SmartTransactionObject#flush()
 	 */
 	@Override
 	public void flush() {
@@ -170,23 +171,25 @@ public void flush() {
 	}
 
 	/**
-	 * This implementation exposes the SavepointManager interface
+	 * This implementation exposes the {@link SavepointManager} interface
 	 * of the underlying transaction object, if any.
+	 * @throws NestedTransactionNotSupportedException if savepoints are not supported
+	 * @see #isTransactionSavepointManager()
 	 */
 	@Override
 	protected SavepointManager getSavepointManager() {
 		if (!isTransactionSavepointManager()) {
 			throw new NestedTransactionNotSupportedException(
-				"Transaction object [" + getTransaction() + "] does not support savepoints");
+					"Transaction object [" + this.transaction + "] does not support savepoints");
 		}
 		return (SavepointManager) getTransaction();
 	}
 
 	/**
-	 * Return whether the underlying transaction implements the
-	 * SavepointManager interface.
-	 * @see #getTransaction
-	 * @see org.springframework.transaction.SavepointManager
+	 * Return whether the underlying transaction implements the {@link SavepointManager}
+	 * interface and therefore supports savepoints.
+	 * @see #getTransaction()
+	 * @see #getSavepointManager()
 	 */
 	public boolean isTransactionSavepointManager() {
 		return (getTransaction() instanceof SavepointManager);

spring-tx/src/main/java/org/springframework/transaction/support/SimpleTransactionStatus.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 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.
@@ -18,10 +18,8 @@
 
 /**
  * A simple {@link org.springframework.transaction.TransactionStatus}
- * implementation.
- *
- * <p>Derives from {@link AbstractTransactionStatus} and adds an explicit
- * {@link #isNewTransaction() "newTransaction"} flag.
+ * implementation. Derives from {@link AbstractTransactionStatus} and
+ * adds an explicit {@link #isNewTransaction() "newTransaction"} flag.
  *
  * <p>This class is not used by any of Spring's pre-built
  * {@link org.springframework.transaction.PlatformTransactionManager}
@@ -32,24 +30,23 @@
  *
  * @author Juergen Hoeller
  * @since 1.2.3
- * @see #SimpleTransactionStatus(boolean)
- * @see TransactionCallback
+ * @see TransactionCallback#doInTransaction
  */
 public class SimpleTransactionStatus extends AbstractTransactionStatus {
 
 	private final boolean newTransaction;
 
 
 	/**
-	 * Create a new instance of the {@link SimpleTransactionStatus} class,
+	 * Create a new {@code SimpleTransactionStatus} instance,
 	 * indicating a new transaction.
 	 */
 	public SimpleTransactionStatus() {
 		this(true);
 	}
 
 	/**
-	 * Create a new instance of the {@link SimpleTransactionStatus} class.
+	 * Create a new {@code SimpleTransactionStatus} instance.
 	 * @param newTransaction whether to indicate a new transaction
 	 */
 	public SimpleTransactionStatus(boolean newTransaction) {