From d1a6ceecc2b859c3967fdfec1ce470c11f2759fd Mon Sep 17 00:00:00 2001
From: Rossen Stoyanchev <rstoyanchev@vmware.com>
Date: Wed, 5 Dec 2012 09:39:14 -0500
Subject: [PATCH] Update @ModelAttribute javadoc

The @ModelAttribute javadoc now explicitly mentions that model content
is not available after an Exception is raised. This is a very common
question given that @ExceptionHandler methods are co-located with
@ModelAttribute and @RequestMapping methods.

Issue: SPR-10071
---
 .../web/bind/annotation/ModelAttribute.java   | 24 +++++++++++++------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/spring-web/src/main/java/org/springframework/web/bind/annotation/ModelAttribute.java b/spring-web/src/main/java/org/springframework/web/bind/annotation/ModelAttribute.java
index dbd293ff867..39f3141338f 100644
--- a/spring-web/src/main/java/org/springframework/web/bind/annotation/ModelAttribute.java
+++ b/spring-web/src/main/java/org/springframework/web/bind/annotation/ModelAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2007 the original author or authors.
+ * Copyright 2002-2012 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,22 +22,32 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.springframework.ui.Model;
+
 /**
  * Annotation that binds a method parameter or method return value
  * to a named model attribute, exposed to a web view. Supported
- * for {@link RequestMapping} annotated handler classes.
+ * for controller classes with {@link RequestMapping @RequestMapping}
+ * methods.
  *
  * <p>Can be used to expose command objects to a web view, using
  * specific attribute names, through annotating corresponding
- * parameters of a {@link RequestMapping} annotated handler method).
+ * parameters of an {@link RequestMapping @RequestMapping} method.
  *
  * <p>Can also be used to expose reference data to a web view
- * through annotating accessor methods in a controller class which
- * is based on {@link RequestMapping} annotated handler methods,
- * with such accessor methods allowed to have any arguments that
- * {@link RequestMapping} supports for handler methods, returning
+ * through annotating accessor methods in a controller class with
+ * {@link RequestMapping @RequestMapping} methods. Such accessor
+ * methods are allowed to have any arguments that
+ * {@link RequestMapping @RequestMapping} methods support, returning
  * the model attribute value to expose.
  *
+ * <p>Note however that reference data and all other model content is
+ * not available to web views when request processing results in an
+ * {@code Exception} since the exception could be raised at any time
+ * making the content of the model unreliable. For this reason
+ * {@link ExceptionHandler @ExceptionHandler} methods do not provide
+ * access to a {@link Model} argument.
+ *
  * @author Juergen Hoeller
  * @since 2.5
  */