Update RestTemplate Javadoc

Closes gh-29311

Author: rstoyanchev

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2022 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,6 +54,10 @@ public abstract class InterceptingHttpAccessor extends HttpAccessor {
 	 * Set the request interceptors that this accessor should use.
 	 * <p>The interceptors will get immediately sorted according to their
 	 * {@linkplain AnnotationAwareOrderComparator#sort(List) order}.
+	 * <p><strong>Note:</strong> This method does not support concurrent changes,
+	 * and in most cases should not be called after initialization on startup.
+	 * See also related note on {@link org.springframework.web.client.RestTemplate}
+	 * regarding concurrent configuration changes.
 	 * @see #getRequestFactory()
 	 * @see AnnotationAwareOrderComparator
 	 */

spring-web/src/main/java/org/springframework/web/client/RestTemplate.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -68,11 +68,17 @@
 /**
  * Synchronous client to perform HTTP requests, exposing a simple, template
  * method API over underlying HTTP client libraries such as the JDK
- * {@code HttpURLConnection}, Apache HttpComponents, and others.
+ * {@code HttpURLConnection}, Apache HttpComponents, and others. RestTemplate
+ * offers templates for common scenarios by HTTP method, in addition to the
+ * generalized {@code exchange} and {@code execute} methods that support of
+ * less frequent cases.
  *
- * <p>The RestTemplate offers templates for common scenarios by HTTP method, in
- * addition to the generalized {@code exchange} and {@code execute} methods that
- * support of less frequent cases.
+ * <p>RestTemplate is typically used as a shared component. However, its
+ * configuration does not support concurrent modification, and as such its
+ * configuration is typically prepared on startup. If necessary, you can create
+ * multiple, differently configured RestTemplate instances on startup. Such
+ * instances may use the same the underlying {@link ClientHttpRequestFactory}
+ * if they need to share HTTP client resources.
  *
  * <p><strong>NOTE:</strong> As of 5.0 this class is in maintenance mode, with
  * only minor requests for changes and bugs to be accepted going forward. Please,