Polishing

spring-core/src/main/java/org/springframework/core/annotation/AnnotationAwareOrderComparator.java

@@ -100,7 +100,7 @@ public class AnnotationAwareOrderComparator extends OrderComparator {
 
 
 	/**
-	 * Sort the given List with a default AnnotationAwareOrderComparator.
+	 * Sort the given list with a default {@link AnnotationAwareOrderComparator}.
 	 * <p>Optimized to skip sorting for lists with size 0 or 1,
 	 * in order to avoid unnecessary array extraction.
 	 * @param list the List to sort

spring-web/src/main/java/org/springframework/http/client/ClientHttpRequestInitializer.java

@@ -22,7 +22,7 @@ import org.springframework.http.client.support.HttpAccessor;
  * Callback interface for initializing a {@link ClientHttpRequest} prior to it
  * being used.
  *
- * <p> Typically used with {@link HttpAccessor} and subclasses such as
+ * <p>Typically used with {@link HttpAccessor} and subclasses such as
  * {@link org.springframework.web.client.RestTemplate RestTemplate} to apply
  * consistent settings or headers to each request.
  *

spring-web/src/main/java/org/springframework/http/client/support/HttpAccessor.java

@@ -38,10 +38,12 @@ import org.springframework.util.Assert;
  * such as the {@link ClientHttpRequestFactory} to operate on.
  *
  * <p>Not intended to be used directly.
- * See {@link org.springframework.web.client.RestTemplate} for an entry point.
+ *
+ * <p>See {@link org.springframework.web.client.RestTemplate} for an entry point.
  *
  * @author Arjen Poutsma
  * @author Juergen Hoeller
+ * @author Phillip Webb
  * @since 3.0
  * @see ClientHttpRequestFactory
  * @see org.springframework.web.client.RestTemplate
@@ -53,7 +55,7 @@ public abstract class HttpAccessor {
 
 	private ClientHttpRequestFactory requestFactory = new SimpleClientHttpRequestFactory();
 
-	private List<ClientHttpRequestInitializer> clientHttpRequestInitializers = new ArrayList<>();
+	private final List<ClientHttpRequestInitializer> clientHttpRequestInitializers = new ArrayList<>();
 
 
 	/**
@@ -81,12 +83,14 @@ public abstract class HttpAccessor {
 
 
 	/**
-	 * Set the request initializers the this accessor should use.
+	 * Set the request initializers that this accessor should use.
-	 * <p>The initializers will get sorted according to their order
+	 * <p>The initializers will get immediately sorted according to their
-	 * before the {@link ClientHttpRequest} is initialized.
+	 * {@linkplain AnnotationAwareOrderComparator#sort(List) order}.
+	 * @since 5.2
 	 */
 	public void setClientHttpRequestInitializers(
 			List<ClientHttpRequestInitializer> clientHttpRequestInitializers) {
+
 		if (this.clientHttpRequestInitializers != clientHttpRequestInitializers) {
 			this.clientHttpRequestInitializers.clear();
 			this.clientHttpRequestInitializers.addAll(clientHttpRequestInitializers);
@@ -95,8 +99,13 @@ public abstract class HttpAccessor {
 	}
 
 	/**
-	 * Return the request initializers that this accessor uses.
+	 * Get the request initializers that this accessor uses.
-	 * <p>The returned {@link List} is active and may get appended to.
+	 * <p>The returned {@link List} is active and may be modified. Note,
+	 * however, that the initializers will not be resorted according to their
+	 * {@linkplain AnnotationAwareOrderComparator#sort(List) order} before the
+	 * {@link ClientHttpRequest} is initialized.
+	 * @since 5.2
+	 * @see #setClientHttpRequestInitializers(List)
 	 */
 	public List<ClientHttpRequestInitializer> getClientHttpRequestInitializers() {
 		return this.clientHttpRequestInitializers;

spring-web/src/main/java/org/springframework/http/client/support/InterceptingHttpAccessor.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.
@@ -51,8 +51,8 @@ public abstract class InterceptingHttpAccessor extends HttpAccessor {
 
 	/**
 	 * Set the request interceptors that this accessor should use.
-	 * <p>The interceptors will get sorted according to their order
+	 * <p>The interceptors will get immediately sorted according to their
-	 * once the {@link ClientHttpRequestFactory} will be built.
+	 * {@linkplain AnnotationAwareOrderComparator#sort(List) order}.
 	 * @see #getRequestFactory()
 	 * @see AnnotationAwareOrderComparator
 	 */
@@ -66,8 +66,11 @@ public abstract class InterceptingHttpAccessor extends HttpAccessor {
 	}
 
 	/**
-	 * Return the request interceptors that this accessor uses.
+	 * Get the request interceptors that this accessor uses.
-	 * <p>The returned {@link List} is active and may get appended to.
+	 * <p>The returned {@link List} is active and may be modified. Note,
+	 * however, that the interceptors will not be resorted according to their
+	 * {@linkplain AnnotationAwareOrderComparator#sort(List) order} before the
+	 * {@link ClientHttpRequestFactory} is built.
 	 */
 	public List<ClientHttpRequestInterceptor> getInterceptors() {
 		return this.interceptors;