Correct documentation of default HttpMessageConverters in RestTemplate

Issue: SPR-7885

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

@@ -64,8 +64,10 @@ import org.springframework.util.StringUtils;
  *
  * <p>For example, the following snippet shows how to submit an HTML form:
  * <pre class="code">
- * RestTemplate template = new RestTemplate();  // FormHttpMessageConverter is configured by default
+ * RestTemplate template = new RestTemplate();
- * MultiValueMap&lt;String, String&gt; form = new LinkedMultiValueMap&lt;String, String&gt;();
+ * // AllEncompassingFormHttpMessageConverter is configured by default
+ *
+ * MultiValueMap&lt;String, String&gt; form = new LinkedMultiValueMap&lt;&gt;();
  * form.add("field 1", "value 1");
  * form.add("field 2", "value 2");
  * form.add("field 2", "value 3");
@@ -74,7 +76,7 @@ import org.springframework.util.StringUtils;
  *
  * <p>The following snippet shows how to do a file upload:
  * <pre class="code">
- * MultiValueMap&lt;String, Object&gt; parts = new LinkedMultiValueMap&lt;String, Object&gt;();
+ * MultiValueMap&lt;String, Object&gt; parts = new LinkedMultiValueMap&lt;&gt;();
  * parts.add("field 1", "value 1");
  * parts.add("file", new ClassPathResource("myFile.jpg"));
  * template.postForLocation("http://example.com/myFileUpload", parts);
@@ -87,7 +89,8 @@ import org.springframework.util.StringUtils;
  * @author Rossen Stoyanchev
  * @author Juergen Hoeller
  * @since 3.0
- * @see MultiValueMap
+ * @see org.springframework.http.converter.support.AllEncompassingFormHttpMessageConverter
+ * @see org.springframework.util.MultiValueMap
  */
 public class FormHttpMessageConverter implements HttpMessageConverter<MultiValueMap<String, ?>> {
 

src/docs/asciidoc/integration.adoc

@@ -1014,23 +1014,23 @@ exception processing the HTTP request, an exception of the type `RestClientExcep
 will be thrown; this behavior can be changed by plugging in another
 `ResponseErrorHandler` implementation into the `RestTemplate`.
 
-The `exchange` and `execute` methods are generalized versions of the more
+The `exchange` and `execute` methods are generalized versions of the more specific
-specific methods listed above them and can support additional combinations and methods,
+methods listed above them and can support additional combinations and methods,
-like HTTP PATCH. However, note that the underlying HTTP library must also support the
+e.g. HTTP PATCH. However, note that the underlying HTTP library must also support the
-desired combination. The JDK `HttpURLConnection` does not support the `PATCH` method, but
+desired combination. The JDK `HttpURLConnection` does not support the `PATCH` method
-Apache HttpComponents HttpClient version 4.2 or later does. They also enable
+but Apache HttpComponents HttpClient version 4.2 or later does. They also enable
-`RestTemplate` to read an HTTP response to a generic type (e.g. `List<Account>`), using a
+`RestTemplate` to read an HTTP response to a generic type (e.g. `List<Account>`),
-`ParameterizedTypeReference`, a new class that enables capturing and passing generic
+using a `ParameterizedTypeReference`, a new class that enables capturing and passing
-type info.
+generic type info.
 
 Objects passed to and returned from these methods are converted to and from HTTP
-messages by `HttpMessageConverter` instances. Converters for the main mime types are
+messages by `HttpMessageConverter` implementations. Converters for the main MIME types
-registered by default, but you can also write your own converter and register it via the
+are registered by default, but you can also override the defaults and register custom
-`messageConverters()` bean property. The default converter instances registered with the
+converters via the `messageConverters()` bean property. The default converters are
-template are `ByteArrayHttpMessageConverter`, `StringHttpMessageConverter`,
+`ByteArrayHttpMessageConverter`, `StringHttpMessageConverter`,
-`FormHttpMessageConverter` and `SourceHttpMessageConverter`. You can override these
+`ResourceHttpMessageConverter`, `SourceHttpMessageConverter` as well as
-defaults using the `messageConverters()` bean property as would be required if using the
+`AllEncompassingFormHttpMessageConverter` and a few provider-specific converters:
-`MarshallingHttpMessageConverter` or `MappingJackson2HttpMessageConverter`.
+e.g. `MappingJackson2HttpMessageConverter` when Jackson is present on the classpath.
 
 Each method takes URI template arguments in two forms, either as a `String`
 variable-length argument or a `Map<String,String>`. For example,
@@ -1213,7 +1213,7 @@ writing the body of HTTP requests and responses via `InputStream` and `OutputStr
 ``HttpMessageConverter``'s are used on the client side, e.g. in the `RestTemplate`, and
 also on the server side, e.g. in Spring MVC REST controllers.
 
-Concrete implementations for the main media (mime) types are provided in the framework
+Concrete implementations for the main media (MIME) types are provided in the framework
 and are registered by default with the `RestTemplate` on the client-side and with
 `RequestMethodHandlerAdapter` on the server-side (see
 <<web.adoc#mvc-config-message-converters,Configuring Message Converters>>).
@@ -5601,9 +5601,8 @@ exception hierarchy.
 
 The `org.springframework.mail.javamail.JavaMailSender` interface adds specialized
 __JavaMail__ features such as MIME message support to the `MailSender` interface (from
-which it inherits). `JavaMailSender` also provides a callback interface for preparation
+which it inherits). `JavaMailSender` also provides a callback interface for preparing
-of JavaMail MIME messages, called
+a 'MimeMessage', called `org.springframework.mail.javamail.MimeMessagePreparator`.
-`org.springframework.mail.javamail.MimeMessagePreparator`
 
 
 
@@ -5726,23 +5725,17 @@ callback interface. Please note in this case that the `mailSender` property is o
 		}
 
 		public void placeOrder(final Order order) {
-
 			// Do the business calculations...
-
 			// Call the collaborators to persist the order...
 
 			MimeMessagePreparator preparator = new MimeMessagePreparator() {
-
 				public void prepare(MimeMessage mimeMessage) throws Exception {
-
 					mimeMessage.setRecipient(Message.RecipientType.TO,
 							new InternetAddress(order.getCustomer().getEmailAddress()));
 					mimeMessage.setFrom(new InternetAddress("mail@mycompany.com"));
-					mimeMessage.setText(
+					mimeMessage.setText("Dear " + order.getCustomer().getFirstName() + " " +
-							"Dear " + order.getCustomer().getFirstName() + " "
+							order.getCustomer().getLastName() + ", thanks for your order. " +
-								+ order.getCustomer().getLastName()
+							"Your order number is " + order.getOrderNumber() + ".");
-								+ ", thank you for placing order. Your order number is "
-								+ order.getOrderNumber());
 				}
 			};
 
@@ -5858,10 +5851,10 @@ along with an inline image.
 
 [WARNING]
 ====
-Inline resources are added to the mime message using the specified `Content-ID` (
+Inline resources are added to the `MimeMessage` using the specified `Content-ID`
-`identifier1234` in the above example). The order in which you are adding the text and
+(`identifier1234` in the above example). The order in which you are adding the text
-the resource are __very__ important. Be sure to __first add the text__ and after that
+and the resource are __very__ important. Be sure to __first add the text__ and after
-the resources. If you are doing it the other way around, it won't work!
+that the resources. If you are doing it the other way around, it won't work!
 ====