Polishing

Author: jhoeller

spring-messaging/src/main/java/org/springframework/messaging/handler/invocation/AsyncHandlerMethodReturnValueHandler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 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.
@@ -42,8 +42,8 @@ public interface AsyncHandlerMethodReturnValueHandler extends HandlerMethodRetur
 	 * {@link #supportsReturnType(org.springframework.core.MethodParameter)}
 	 * is called and it returns {@code true}.
 	 * @param returnValue the value returned from the handler method
-	 * @param returnType the type of the return value.
-	 * @return true if the return value type represents an async value.
+	 * @param returnType the type of the return value
+	 * @return {@code true} if the return value type represents an async value
 	 */
 	boolean isAsyncReturnValue(Object returnValue, MethodParameter returnType);
 
@@ -57,9 +57,9 @@ public interface AsyncHandlerMethodReturnValueHandler extends HandlerMethodRetur
 	 * {@link #supportsReturnType(org.springframework.core.MethodParameter)}
 	 * is called and it returns {@code true}.
 	 * @param returnValue the value returned from the handler method
-	 * @param returnType the type of the return value.
-	 * @return the resulting ListenableFuture or {@code null} in which case no
-	 * further handling will be performed.
+	 * @param returnType the type of the return value
+	 * @return the resulting ListenableFuture, or {@code null} in which case
+	 * no further handling will be performed
 	 */
 	ListenableFuture<?> toListenableFuture(Object returnValue, MethodParameter returnType);
 

spring-messaging/src/main/java/org/springframework/messaging/support/AbstractMessageChannel.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 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.
@@ -41,10 +41,10 @@ public abstract class AbstractMessageChannel implements MessageChannel, Intercep
 
 	protected final Log logger = LogFactory.getLog(getClass());
 
-	private final List<ChannelInterceptor> interceptors = new ArrayList<ChannelInterceptor>(5);
-
 	private String beanName;
 
+	private final List<ChannelInterceptor> interceptors = new ArrayList<ChannelInterceptor>(5);
+
 
 	public AbstractMessageChannel() {
 		this.beanName = getClass().getSimpleName() + "@" + ObjectUtils.getIdentityHexString(this);

spring-oxm/src/main/java/org/springframework/oxm/jaxb/Jaxb2Marshaller.java

@@ -337,8 +337,8 @@ public void setSchemaLanguage(String schemaLanguage) {
 	/**
 	 * Set the resource resolver, as used to load the schema resources.
 	 * @see SchemaFactory#setResourceResolver(org.w3c.dom.ls.LSResourceResolver)
-	 * @see #setSchema(Resource)
-	 * @see #setSchemas(Resource[])
+	 * @see #setSchema
+	 * @see #setSchemas
 	 */
 	public void setSchemaResourceResolver(LSResourceResolver schemaResourceResolver) {
 		this.schemaResourceResolver = schemaResourceResolver;
@@ -401,22 +401,22 @@ public void setMappedClass(Class<?> mappedClass) {
 	}
 
 	/**
-	 * Indicates whether DTD parsing should be supported.
+	 * Indicate whether DTD parsing should be supported.
 	 * <p>Default is {@code false} meaning that DTD is disabled.
 	 */
 	public void setSupportDtd(boolean supportDtd) {
 		this.supportDtd = supportDtd;
 	}
 
 	/**
-	 * Whether DTD parsing is supported.
+	 * Return whether DTD parsing is supported.
 	 */
 	public boolean isSupportDtd() {
 		return this.supportDtd;
 	}
 
 	/**
-	 * Indicates whether external XML entities are processed when unmarshalling.
+	 * Indicate whether external XML entities are processed when unmarshalling.
 	 * <p>Default is {@code false}, meaning that external entities are not resolved.
 	 * Note that processing of external entities will only be enabled/disabled when the
 	 * {@code Source} passed to {@link #unmarshal(Source)} is a {@link SAXSource} or
@@ -433,7 +433,7 @@ public void setProcessExternalEntities(boolean processExternalEntities) {
 	}
 
 	/**
-	 * Returns the configured value for whether XML external entities are allowed.
+	 * Return whether XML external entities are allowed.
 	 */
 	public boolean isProcessExternalEntities() {
 		return this.processExternalEntities;

spring-oxm/src/main/java/org/springframework/oxm/support/AbstractMarshaller.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 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.
@@ -82,22 +82,22 @@ public abstract class AbstractMarshaller implements Marshaller, Unmarshaller {
 
 
 	/**
-	 * Indicates whether DTD parsing should be supported.
+	 * Indicate whether DTD parsing should be supported.
 	 * <p>Default is {@code false} meaning that DTD is disabled.
 	 */
 	public void setSupportDtd(boolean supportDtd) {
 		this.supportDtd = supportDtd;
 	}
 
 	/**
-	 * Whether DTD parsing is supported.
+	 * Return whether DTD parsing is supported.
 	 */
 	public boolean isSupportDtd() {
 		return this.supportDtd;
 	}
 
 	/**
-	 * Indicates whether external XML entities are processed when unmarshalling.
+	 * Indicate whether external XML entities are processed when unmarshalling.
 	 * <p>Default is {@code false}, meaning that external entities are not resolved.
 	 * Note that processing of external entities will only be enabled/disabled when the
 	 * {@code Source} passed to {@link #unmarshal(Source)} is a {@link SAXSource} or
@@ -114,7 +114,7 @@ public void setProcessExternalEntities(boolean processExternalEntities) {
 	}
 
 	/**
-	 * Returns the configured value for whether XML external entities are allowed.
+	 * Return whether XML external entities are allowed.
 	 * @see #createXmlReader()
 	 */
 	public boolean isProcessExternalEntities() {

spring-tx/src/main/java/org/springframework/transaction/annotation/Propagation.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.
@@ -40,7 +40,7 @@ public enum Propagation {
 	 * Support a current transaction, execute non-transactionally if none exists.
 	 * Analogous to EJB transaction attribute of the same name.
 	 * <p>Note: For transaction managers with transaction synchronization,
-	 * PROPAGATION_SUPPORTS is slightly different from no transaction at all,
+	 * {@code SUPPORTS} is slightly different from no transaction at all,
 	 * as it defines a transaction scope that synchronization will apply for.
 	 * As a consequence, the same resources (JDBC Connection, Hibernate Session, etc)
 	 * will be shared for the entire specified scope. Note that this depends on
@@ -87,7 +87,7 @@ public enum Propagation {
 
 	/**
 	 * Execute within a nested transaction if a current transaction exists,
-	 * behave like PROPAGATION_REQUIRED else. There is no analogous feature in EJB.
+	 * behave like {@code REQUIRED} else. There is no analogous feature in EJB.
 	 * <p>Note: Actual creation of a nested transaction will only work on specific
 	 * transaction managers. Out of the box, this only applies to the JDBC
 	 * DataSourceTransactionManager when working on a JDBC 3.0 driver.

spring-web/src/main/java/org/springframework/http/converter/xml/Jaxb2RootElementHttpMessageConverter.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.
@@ -54,9 +54,8 @@
  * {@link XmlType}, and write classes annotated with {@link XmlRootElement},
  * or subclasses thereof.
  *
- * <p>Note that if using Spring's Marshaller/Unmarshaller abstractions from the
- * {@code spring-oxm} module you should can the
- * {@link MarshallingHttpMessageConverter} instead.
+ * <p>Note: When using Spring's Marshaller/Unmarshaller abstractions from {@code spring-oxm},
+ * you should use the {@link MarshallingHttpMessageConverter} instead.
  *
  * @author Arjen Poutsma
  * @author Sebastien Deleuze
@@ -72,22 +71,22 @@ public class Jaxb2RootElementHttpMessageConverter extends AbstractJaxb2HttpMessa
 
 
 	/**
-	 * Indicates whether DTD parsing should be supported.
+	 * Indicate whether DTD parsing should be supported.
 	 * <p>Default is {@code false} meaning that DTD is disabled.
 	 */
 	public void setSupportDtd(boolean supportDtd) {
 		this.supportDtd = supportDtd;
 	}
 
 	/**
-	 * Whether DTD parsing is supported.
+	 * Return whether DTD parsing is supported.
 	 */
 	public boolean isSupportDtd() {
 		return this.supportDtd;
 	}
 
 	/**
-	 * Indicates whether external XML entities are processed when converting to a Source.
+	 * Indicate whether external XML entities are processed when converting to a Source.
 	 * <p>Default is {@code false}, meaning that external entities are not resolved.
 	 * <p><strong>Note:</strong> setting this option to {@code true} also
 	 * automatically sets {@link #setSupportDtd} to {@code true}.
@@ -100,7 +99,7 @@ public void setProcessExternalEntities(boolean processExternalEntities) {
 	}
 
 	/**
-	 * Returns the configured value for whether XML external entities are allowed.
+	 * Return whether XML external entities are allowed.
 	 */
 	public boolean isProcessExternalEntities() {
 		return this.processExternalEntities;

spring-web/src/main/java/org/springframework/http/converter/xml/SourceHttpMessageConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 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.
@@ -94,22 +94,22 @@ public SourceHttpMessageConverter() {
 
 
 	/**
-	 * Indicates whether DTD parsing should be supported.
+	 * Indicate whether DTD parsing should be supported.
 	 * <p>Default is {@code false} meaning that DTD is disabled.
 	 */
 	public void setSupportDtd(boolean supportDtd) {
 		this.supportDtd = supportDtd;
 	}
 
 	/**
-	 * Whether DTD parsing is supported.
+	 * Return whether DTD parsing is supported.
 	 */
 	public boolean isSupportDtd() {
 		return this.supportDtd;
 	}
 
 	/**
-	 * Indicates whether external XML entities are processed when converting to a Source.
+	 * Indicate whether external XML entities are processed when converting to a Source.
 	 * <p>Default is {@code false}, meaning that external entities are not resolved.
 	 * <p><strong>Note:</strong> setting this option to {@code true} also
 	 * automatically sets {@link #setSupportDtd} to {@code true}.
@@ -122,7 +122,7 @@ public void setProcessExternalEntities(boolean processExternalEntities) {
 	}
 
 	/**
-	 * Returns the configured value for whether XML external entities are allowed.
+	 * Return whether XML external entities are allowed.
 	 */
 	public boolean isProcessExternalEntities() {
 		return this.processExternalEntities;

spring-web/src/main/java/org/springframework/web/method/support/AsyncHandlerMethodReturnValueHandler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 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.
@@ -27,7 +27,8 @@
  * For example custom (async) handlers, by default ordered after built-in
  * handlers, should take precedence over {@code @ResponseBody} or
  * {@code @ModelAttribute} handling, which should occur once the async value is
- * ready.
+ * ready. By contrast, built-in (async) handlers are already ordered ahead of
+ * sync handlers.
  *
  * @author Rossen Stoyanchev
  * @since 4.2
@@ -36,9 +37,9 @@ public interface AsyncHandlerMethodReturnValueHandler extends HandlerMethodRetur
 
 	/**
 	 * Whether the given return value represents asynchronous computation.
-	 * @param returnValue the return value
+	 * @param returnValue the value returned from the handler method
 	 * @param returnType the return type
-	 * @return {@code true} if the return value is asynchronous.
+	 * @return {@code true} if the return value type represents an async value
 	 */
 	boolean isAsyncReturnValue(Object returnValue, MethodParameter returnType);
 

spring-webmvc/src/main/java/org/springframework/web/servlet/support/RequestContextUtils.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.
@@ -256,9 +256,8 @@ public static Theme getTheme(HttpServletRequest request) {
 	}
 
 	/**
-	 * Return a read-only {@link Map} with "input" flash attributes saved on a
-	 * previous request.
-	 * @param request the current request
+	 * Return read-only "input" flash attributes from request before redirect.
+	 * @param request current request
 	 * @return a read-only Map, or {@code null} if not found
 	 * @see FlashMap
 	 */
@@ -268,20 +267,20 @@ public static Theme getTheme(HttpServletRequest request) {
 	}
 
 	/**
-	 * Return the "output" FlashMap with attributes to save for a subsequent request.
-	 * @param request the current request
-	 * @return a {@link FlashMap} instance (never {@code null} within a DispatcherServlet request)
-	 * @see FlashMap
+	 * Return "output" FlashMap to save attributes for request after redirect.
+	 * @param request current request
+	 * @return a {@link FlashMap} instance, never {@code null} within a
+	 * {@code DispatcherServlet}-handled request
 	 */
 	public static FlashMap getOutputFlashMap(HttpServletRequest request) {
 		return (FlashMap) request.getAttribute(DispatcherServlet.OUTPUT_FLASH_MAP_ATTRIBUTE);
 	}
 
 	/**
-	 * Return the FlashMapManager instance to save flash attributes with
-	 * before a redirect.
+	 * Return the {@code FlashMapManager} instance to save flash attributes.
 	 * @param request the current request
-	 * @return a {@link FlashMapManager} instance (never {@code null} within a DispatcherServlet request)
+	 * @return a {@link FlashMapManager} instance, never {@code null} within a
+	 * {@code DispatcherServlet}-handled request
 	 */
 	public static FlashMapManager getFlashMapManager(HttpServletRequest request) {
 		return (FlashMapManager) request.getAttribute(DispatcherServlet.FLASH_MAP_MANAGER_ATTRIBUTE);

spring-webmvc/src/main/java/org/springframework/web/servlet/view/RedirectView.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 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.
@@ -371,7 +371,7 @@ private String getContextPath(HttpServletRequest request) {
 	 * attributes or URI variables from the current request. Model attributes
 	 * referenced in the URL are removed from the model.
 	 * @param targetUrl the redirect URL
-	 * @param model Map that contains model attributes
+	 * @param model a Map that contains model attributes
 	 * @param currentUriVariables current request URI variables to use
 	 * @param encodingScheme the encoding scheme to use
 	 * @throws UnsupportedEncodingException if string encoding failed
@@ -438,7 +438,7 @@ protected void appendCurrentQueryParams(StringBuilder targetUrl, HttpServletRequ
 	 * Append query properties to the redirect URL.
 	 * Stringifies, URL-encodes and formats model attributes as query properties.
 	 * @param targetUrl the StringBuilder to append the properties to
-	 * @param model Map that contains model attributes
+	 * @param model a Map that contains model attributes
 	 * @param encodingScheme the encoding scheme to use
 	 * @throws UnsupportedEncodingException if string encoding failed
 	 * @see #queryProperties
@@ -557,8 +557,9 @@ protected boolean isEligibleProperty(String key, Object value) {
 
 	/**
 	 * Determine whether the given model element value is eligible for exposure.
-	 * <p>The default implementation considers primitives, Strings, Numbers, Dates,
-	 * URIs, URLs and Locale objects as eligible. This can be overridden in subclasses.
+	 * <p>The default implementation considers primitives, strings, numbers, dates,
+	 * URIs, URLs etc as eligible, according to {@link BeanUtils#isSimpleValueType}.
+	 * This can be overridden in subclasses.
 	 * @param value the model element value
 	 * @return whether the element value is eligible
 	 * @see BeanUtils#isSimpleValueType
@@ -575,7 +576,6 @@ protected boolean isEligibleValue(Object value) {
 	 * @return the encoded output String
 	 * @throws UnsupportedEncodingException if thrown by the JDK URLEncoder
 	 * @see java.net.URLEncoder#encode(String, String)
-	 * @see java.net.URLEncoder#encode(String)
 	 */
 	protected String urlEncode(String input, String encodingScheme) throws UnsupportedEncodingException {
 		return (input != null ? URLEncoder.encode(input, encodingScheme) : null);
@@ -605,7 +605,7 @@ protected String updateTargetUrl(String targetUrl, Map<String, Object> model,
 	}
 
 	/**
-	 * Send a redirect back to the HTTP client
+	 * Send a redirect back to the HTTP client.
 	 * @param request current HTTP request (allows for reacting to request method)
 	 * @param response current HTTP response (for sending response headers)
 	 * @param targetUrl the target URL to redirect to