Polishing

spring-aop/src/main/java/org/springframework/aop/framework/autoproxy/AbstractAdvisorAutoProxyCreator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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,8 +31,8 @@ import org.springframework.util.Assert;
  * Generic auto proxy creator that builds AOP proxies for specific beans
  * based on detected Advisors for each bean.
  *
- * <p>Subclasses must implement the abstract {@link #findCandidateAdvisors()}
+ * <p>Subclasses may override the {@link #findCandidateAdvisors()} method to
- * method to return a list of Advisors applying to any object. Subclasses can
+ * return a custom list of Advisors applying to any object. Subclasses can
  * also override the inherited {@link #shouldSkip} method to exclude certain
  * objects from auto-proxying.
  *
@@ -160,7 +160,7 @@ public abstract class AbstractAdvisorAutoProxyCreator extends AbstractAutoProxyC
 	 * <p>The default implementation is empty.
 	 * <p>Typically used to add Advisors that expose contextual information
 	 * required by some of the later advisors.
-	 * @param candidateAdvisors Advisors that have already been identified as
+	 * @param candidateAdvisors the Advisors that have already been identified as
 	 * applying to a given bean
 	 */
 	protected void extendAdvisors(List<Advisor> candidateAdvisors) {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -28,7 +28,7 @@ import org.springframework.core.io.Resource;
 import org.springframework.lang.Nullable;
 
 /**
- * EntityResolver implementation for the Spring beans DTD,
+ * {@link EntityResolver} implementation for the Spring beans DTD,
  * to load the DTD from the Spring class path (or JAR file).
  *
  * <p>Fetches "spring-beans.dtd" from the class path resource
@@ -57,6 +57,7 @@ public class BeansDtdResolver implements EntityResolver {
 			logger.trace("Trying to resolve XML entity with public ID [" + publicId +
 					"] and system ID [" + systemId + "]");
 		}
+
 		if (systemId != null && systemId.endsWith(DTD_EXTENSION)) {
 			int lastPathSeparator = systemId.lastIndexOf('/');
 			int dtdNameStart = systemId.indexOf(DTD_NAME, lastPathSeparator);
@@ -80,11 +81,10 @@ public class BeansDtdResolver implements EntityResolver {
 						logger.debug("Could not resolve beans DTD [" + systemId + "]: not found in classpath", ex);
 					}
 				}
-
 			}
 		}
 
-		// Use the default behavior -> download from website or wherever.
+		// Fall back to the parser's default behavior.
 		return null;
 	}
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -38,15 +38,15 @@ import org.springframework.util.CollectionUtils;
  * {@link EntityResolver} implementation that attempts to resolve schema URLs into
  * local {@link ClassPathResource classpath resources} using a set of mappings files.
  *
- * <p>By default, this class will look for mapping files in the classpath using the pattern:
+ * <p>By default, this class will look for mapping files in the classpath using the
- * {@code META-INF/spring.schemas} allowing for multiple files to exist on the
+ * pattern: {@code META-INF/spring.schemas} allowing for multiple files to exist on
- * classpath at any one time.
+ * the classpath at any one time.
  *
- * The format of {@code META-INF/spring.schemas} is a properties
+ * <p>The format of {@code META-INF/spring.schemas} is a properties file where each line
- * file where each line should be of the form {@code systemId=schema-location}
+ * should be of the form {@code systemId=schema-location} where {@code schema-location}
- * where {@code schema-location} should also be a schema file in the classpath.
+ * should also be a schema file in the classpath. Since systemId is commonly a URL,
- * Since systemId is commonly a URL, one must be careful to escape any ':' characters
+ * one must be careful to escape any ':' characters which are treated as delimiters
- * which are treated as delimiters in properties files.
+ * in properties files.
  *
  * <p>The pattern for the mapping files can be overidden using the
  * {@link #PluggableSchemaResolver(ClassLoader, String)} constructor
@@ -103,6 +103,7 @@ public class PluggableSchemaResolver implements EntityResolver {
 		this.schemaMappingsLocation = schemaMappingsLocation;
 	}
 
+
 	@Override
 	@Nullable
 	public InputSource resolveEntity(String publicId, @Nullable String systemId) throws IOException {
@@ -131,6 +132,8 @@ public class PluggableSchemaResolver implements EntityResolver {
 				}
 			}
 		}
+
+		// Fall back to the parser's default behavior.
 		return null;
 	}
 
@@ -169,7 +172,7 @@ public class PluggableSchemaResolver implements EntityResolver {
 
 	@Override
 	public String toString() {
-		return "EntityResolver using mappings " + getSchemaMappings();
+		return "EntityResolver using schema mappings " + getSchemaMappings();
 	}
 
 }

spring-jms/src/main/java/org/springframework/jms/connection/JmsResourceHolder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -19,7 +19,6 @@ package org.springframework.jms.connection;
 import java.lang.reflect.Method;
 import java.util.HashMap;
 import java.util.LinkedList;
-import java.util.List;
 import java.util.Map;
 import javax.jms.Connection;
 import javax.jms.ConnectionFactory;
@@ -58,11 +57,11 @@ public class JmsResourceHolder extends ResourceHolderSupport {
 
 	private boolean frozen = false;
 
-	private final List<Connection> connections = new LinkedList<>();
+	private final LinkedList<Connection> connections = new LinkedList<>();
 
-	private final List<Session> sessions = new LinkedList<>();
+	private final LinkedList<Session> sessions = new LinkedList<>();
 
-	private final Map<Connection, List<Session>> sessionsPerConnection = new HashMap<>();
+	private final Map<Connection, LinkedList<Session>> sessionsPerConnection = new HashMap<>();
 
 
 	/**
@@ -117,10 +116,19 @@ public class JmsResourceHolder extends ResourceHolderSupport {
 	}
 
 
+	/**
+	 * Return whether this resource holder is frozen, i.e. does not
+	 * allow for adding further Connections and Sessions to it.
+	 * @see #addConnection
+	 * @see #addSession
+	 */
 	public final boolean isFrozen() {
 		return this.frozen;
 	}
 
+	/**
+	 * Add the given Connection to this resource holder.
+	 */
 	public final void addConnection(Connection connection) {
 		Assert.isTrue(!this.frozen, "Cannot add Connection because JmsResourceHolder is frozen");
 		Assert.notNull(connection, "Connection must not be null");
@@ -129,54 +137,92 @@ public class JmsResourceHolder extends ResourceHolderSupport {
 		}
 	}
 
+	/**
+	 * Add the given Session to this resource holder.
+	 */
 	public final void addSession(Session session) {
 		addSession(session, null);
 	}
 
+	/**
+	 * Add the given Session to this resource holder,
+	 * registered for a specific Connection.
+	 */
 	public final void addSession(Session session, @Nullable Connection connection) {
 		Assert.isTrue(!this.frozen, "Cannot add Session because JmsResourceHolder is frozen");
 		Assert.notNull(session, "Session must not be null");
 		if (!this.sessions.contains(session)) {
 			this.sessions.add(session);
 			if (connection != null) {
-				List<Session> sessions = this.sessionsPerConnection.computeIfAbsent(connection, k -> new LinkedList<>());
+				LinkedList<Session> sessions =
+						this.sessionsPerConnection.computeIfAbsent(connection, k -> new LinkedList<>());
 				sessions.add(session);
 			}
 		}
 	}
 
+	/**
+	 * Determine whether the given Session is registered
+	 * with this resource holder.
+	 */
 	public boolean containsSession(Session session) {
 		return this.sessions.contains(session);
 	}
 
 
+	/**
+	 * Return this resource holder's default Connection,
+	 * or {@code null} if none.
+	 */
 	@Nullable
 	public Connection getConnection() {
-		return (!this.connections.isEmpty() ? this.connections.get(0) : null);
+		return this.connections.peek();
 	}
 
+	/**
+	 * Return this resource holder's Connection of the given type,
+	 * or {@code null} if none.
+	 */
 	@Nullable
-	public Connection getConnection(Class<? extends Connection> connectionType) {
+	public <C extends Connection> C getConnection(Class<C> connectionType) {
 		return CollectionUtils.findValueOfType(this.connections, connectionType);
 	}
 
+	/**
+	 * Return this resource holder's default Session,
+	 * or {@code null} if none.
+	 */
 	@Nullable
 	public Session getSession() {
-		return (!this.sessions.isEmpty() ? this.sessions.get(0) : null);
+		return this.sessions.peek();
 	}
 
+	/**
+	 * Return this resource holder's Session of the given type,
+	 * or {@code null} if none.
+	 */
 	@Nullable
-	public Session getSession(Class<? extends Session> sessionType) {
+	public <S extends Session> S getSession(Class<S> sessionType) {
 		return getSession(sessionType, null);
 	}
 
+	/**
+	 * Return this resource holder's Session of the given type
+	 * for the given connection, or {@code null} if none.
+	 */
 	@Nullable
-	public Session getSession(Class<? extends Session> sessionType, @Nullable Connection connection) {
+	public <S extends Session> S getSession(Class<S> sessionType, @Nullable Connection connection) {
-		List<Session> sessions = (connection != null ? this.sessionsPerConnection.get(connection) : this.sessions);
+		LinkedList<Session> sessions =
+				(connection != null ? this.sessionsPerConnection.get(connection) : this.sessions);
 		return CollectionUtils.findValueOfType(sessions, sessionType);
 	}
 
 
+	/**
+	 * Commit all of this resource holder's Sessions.
+	 * @throws JMSException if thrown from a Session commit attempt
+	 * @see Session#commit()
+	 */
 	public void commitAll() throws JMSException {
 		for (Session session : this.sessions) {
 			try {
@@ -218,6 +264,10 @@ public class JmsResourceHolder extends ResourceHolderSupport {
 		}
 	}
 
+	/**
+	 * Close all of this resource holder's Sessions and clear its state.
+	 * @see Session#close()
+	 */
 	public void closeAll() {
 		for (Session session : this.sessions) {
 			try {

spring-jms/src/main/java/org/springframework/jms/connection/JmsTransactionManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -128,7 +128,7 @@ public class JmsTransactionManager extends AbstractPlatformTransactionManager
 	 * Set the JMS ConnectionFactory that this instance should manage transactions for.
 	 */
 	public void setConnectionFactory(@Nullable ConnectionFactory cf) {
-		if (cf != null && cf instanceof TransactionAwareConnectionFactoryProxy) {
+		if (cf instanceof TransactionAwareConnectionFactoryProxy) {
 			// If we got a TransactionAwareConnectionFactoryProxy, we need to perform transactions
 			// for its underlying target ConnectionFactory, else JMS access code won't see
 			// properly exposed transactions (i.e. transactions for the target ConnectionFactory).