getUserValue intial commit

spring-binding/src/main/java/org/springframework/binding/message/Message.java

@@ -20,9 +20,10 @@ import java.io.Serializable;
 import org.springframework.core.style.ToStringCreator;
 
 /**
- * An object of communication that provides text information from a source. For example, a validation message may inform
- * a web application user a business rule was violated. A messages comes from a source, has text providing the basis for
- * communication, and has severity indicating the priority or intensity of the message for its receiver.
+ * An object of communication that provides text information. For example, a validation message may inform a web
+ * application user a business rule was violated. A message can be associated with a particular source element or
+ * component, has text providing the basis for communication, and has severity indicating the priority or intensity of
+ * the message for its receiver.
  * 
  * @author Keith Donald
  */
@@ -47,7 +48,8 @@ public class Message implements Serializable {
 	}
 
 	/**
-	 * Returns the source of this message. The source is the object that sent the message.
+	 * A reference to the source element this message is associated with. This could be a field on a form in UI, or null
+	 * if the message is not associated with a any particular element.
 	 * @return the source
 	 */
 	public Object getSource() {
@@ -55,7 +57,7 @@ public class Message implements Serializable {
 	}
 
 	/**
-	 * Returns the message text. The text is the message's communication payload.
+	 * The message text. The text is the message's communication payload.
 	 * @return the message text
 	 */
 	public String getText() {
@@ -63,7 +65,7 @@ public class Message implements Serializable {
 	}
 
 	/**
-	 * Returns the severity of this message. The severity indicates the intensity or priority of the communication.
+	 * The severity of this message. The severity indicates the intensity or priority of the communication.
 	 * @return the message severity
 	 */
 	public Severity getSeverity() {
@@ -71,7 +73,8 @@ public class Message implements Serializable {
 	}
 
 	public String toString() {
-		return new ToStringCreator(this).append("severity", severity).append("text", text).toString();
+		return new ToStringCreator(this).append("source", source).append("severity", severity).append("text", text)
+				.toString();
 	}
 
 }

spring-binding/src/main/java/org/springframework/binding/message/MessageBuilder.java

@@ -28,13 +28,13 @@ import org.springframework.core.style.ToStringCreator;
 /**
  * A convenient builder for building {@link MessageResolver} objects programmatically. Often used by model code such as
  * validation logic to conveniently record validation messages. Supports the production of message resolvers that
- * hard-code their message text, as well as message resolvers that retrieve their text from a
- * {@link MessageSource message resource bundle}.
+ * hard-code their message text, as well as message resolvers that retrieve their text from a {@link MessageSource
+ * message resource bundle}.
  * 
  * Usage example:
  * <p>
  * <code>
- * new MessageBuilder().error().source(this).code(&quot;mycode&quot;).arg(arg1).arg(arg2).defaultText(&quot;text&quot;).build();
+ * new MessageBuilder().error().source(&quot;field&quot;).code(&quot;mycode&quot;).arg(arg1).arg(arg2).defaultText(&quot;text&quot;).build();
  * </code>
  * </p>
  * @author Keith Donald
@@ -90,7 +90,7 @@ public class MessageBuilder {
 
 	/**
 	 * Records that the message being built is against the provided source.
-	 * @param source the source generating the message
+	 * @param source the source to associate the message with
 	 * @return this, for fluent API usage
 	 */
 	public MessageBuilder source(Object source) {

spring-binding/src/main/java/org/springframework/binding/validation/ValidationContext.java

@@ -21,25 +21,32 @@ import java.security.Principal;
 import org.springframework.binding.message.MessageContext;
 
 /**
- * A context for validation events.
+ * A validator context. Allows for recording validation error messages, as well as validating data entered by the user.
  * 
+ * @author Keith Donald
  * @author Scott Andrews
  */
 public interface ValidationContext {
 
 	/**
-	 * Get the context for recording messages
+	 * The context for recording validation messages
 	 */
 	public MessageContext getMessageContext();
 
 	/**
-	 * Get the current user principal
+	 * The current user.
 	 */
 	public Principal getUserPrincipal();
 
 	/**
-	 * Get the event that triggered validation
+	 * The current user event that triggered validation.
 	 */
 	public String getUserEvent();
 
+	/**
+	 * Obtain the value entered by the current user in a field. This value can then be validated.
+	 * @param field the name of the field
+	 * @return the value the user entered in the field
+	 */
+	public Object getUserValue(String field);
 }