Extended/BindingAwareModelMap are not meant to be referred to in user code

Issue: SPR-12896

spring-context/src/main/java/org/springframework/ui/ExtendedModelMap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -23,6 +23,11 @@ import java.util.Map;
  * Subclass of {@link ModelMap} that implements the {@link Model} interface.
  * Java 5 specific like the {@code Model} interface itself.
  *
+ * <p>This is an implementation class exposed to handler methods by Spring MVC, typically via
+ * a declaration of the {@link org.springframework.ui.Model} interface. There is no need to
+ * build it within user code; a plain {@link org.springframework.ui.ModelMap} or even a just
+ * a regular {@link Map} with String keys will be good enough to return a user model.
+ *
  * @author Juergen Hoeller
  * @since 2.5.1
  */

spring-context/src/main/java/org/springframework/validation/support/BindingAwareModelMap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -22,12 +22,14 @@ import org.springframework.ui.ExtendedModelMap;
 import org.springframework.validation.BindingResult;
 
 /**
- * Subclass of {@link org.springframework.ui.ExtendedModelMap} that
+ * Subclass of {@link org.springframework.ui.ExtendedModelMap} that automatically removes
- * automatically removes a {@link org.springframework.validation.BindingResult}
+ * a {@link org.springframework.validation.BindingResult} object if the corresponding
- * object if the corresponding target attribute gets replaced.
+ * target attribute gets replaced through regulat {@link Map} operations.
  *
- * <p>Used by {@link org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter}
+ * <p>This is the class exposed to handler methods by Spring MVC, typically consumed through
- * and {@link org.springframework.web.portlet.mvc.annotation.AnnotationMethodHandlerAdapter}.
+ * a declaration of the {@link org.springframework.ui.Model} interface. There is no need to
+ * build it within user code; a plain {@link org.springframework.ui.ModelMap} or even a just
+ * a regular {@link Map} with String keys will be good enough to return a user model.
  *
  * @author Juergen Hoeller
  * @since 2.5.6