From 0cb28f5b4119ffbefae4c67f7afffce9f3b5a14b Mon Sep 17 00:00:00 2001
From: Keith Donald <kdonald@vmware.com>
Date: Mon, 8 Jun 2009 05:06:37 +0000
Subject: [PATCH] javdoc

---
 .../springframework/ui/binding/Binder.java    | 45 +++++++++++++++++++
 .../springframework/ui/binding/Binding.java   | 28 ++++++++++++
 .../ui/binding/BindingConfiguration.java      | 16 +++++++
 .../springframework/ui/binding/package.html   |  7 +++
 .../ui/format/date/package.html               |  7 +++
 .../ui/format/number/package.html             |  7 +++
 .../springframework/ui/format/package.html    |  7 +++
 .../springframework/ui/message/package.html   |  2 +-
 .../ui/message/support/package.html           |  7 +++
 9 files changed, 125 insertions(+), 1 deletion(-)
 create mode 100644 org.springframework.context/src/main/java/org/springframework/ui/binding/package.html
 create mode 100644 org.springframework.context/src/main/java/org/springframework/ui/format/date/package.html
 create mode 100644 org.springframework.context/src/main/java/org/springframework/ui/format/number/package.html
 create mode 100644 org.springframework.context/src/main/java/org/springframework/ui/format/package.html
 create mode 100644 org.springframework.context/src/main/java/org/springframework/ui/message/support/package.html

diff --git a/org.springframework.context/src/main/java/org/springframework/ui/binding/Binder.java b/org.springframework.context/src/main/java/org/springframework/ui/binding/Binder.java
index 4672295924..6b4cdf3cd2 100644
--- a/org.springframework.context/src/main/java/org/springframework/ui/binding/Binder.java
+++ b/org.springframework.context/src/main/java/org/springframework/ui/binding/Binder.java
@@ -44,6 +44,14 @@ import org.springframework.expression.spel.support.StandardTypeConverter;
 import org.springframework.ui.format.AnnotationFormatterFactory;
 import org.springframework.ui.format.Formatter;
 
+/**
+ * Binds user-entered values to properties of a model object.
+ * @author Keith Donald
+ *
+ * @param <T> The type of model object this binder binds to
+ * @see #add(BindingConfiguration)
+ * @see #bind(Map)
+ */
 @SuppressWarnings("unchecked")
 public class Binder<T> {
 
@@ -83,6 +91,10 @@ public class Binder<T> {
 		}		
 	};
 	
+	/**
+	 * Creates a new binder for the model object.
+	 * @param model the model object containing properties this binder will bind to
+	 */
 	public Binder(T model) {
 		this.model = model;
 		bindings = new HashMap<String, Binding>();
@@ -93,10 +105,21 @@ public class Binder<T> {
 		typeConverter = new DefaultTypeConverter();
 	}
 	
+	/**
+	 * Configures if this binder is <i>strict</i>; a strict binder requires all bindings to be registered explicitly using {@link #add(BindingConfiguration)}.
+	 * An <i>optimistic</i> binder will implicitly create bindings as required to support {@link #bind(Map)} operations.
+	 * Default is optimistic.
+	 * @param strict strict binder status
+	 */
 	public void setStrict(boolean strict) {
 		this.strict = strict;
 	}
 
+	/**
+	 * Adds new binding.
+	 * @param binding the binding configuration
+	 * @return the new binding created from the configuration provided
+	 */
 	public Binding add(BindingConfiguration binding) {
 		Binding newBinding;
 		try {
@@ -108,6 +131,11 @@ public class Binder<T> {
 		return newBinding;
 	}
 
+	/**
+	 * Adds a Formatter that will format property values of type <code>propertyType</coe>.
+	 * @param formatter the formatter
+	 * @param propertyType the property type
+	 */
 	public void add(Formatter<?> formatter, Class<?> propertyType) {
 		if (propertyType.isAnnotation()) {
 			annotationFormatters.put(propertyType, new SimpleAnnotationFormatterFactory(formatter));
@@ -116,14 +144,27 @@ public class Binder<T> {
 		}
 	}
 	
+	/**
+	 * Adds a AnnotationFormatterFactory that will format values of properties annotated with a specific annotation.
+	 * @param factory the annotation formatter factory
+	 */
 	public void add(AnnotationFormatterFactory<?, ?> factory) {
 		annotationFormatters.put(getAnnotationType(factory), factory);
 	}
 
+	/**
+	 * The model object this binder binds to.
+	 * @return the model object
+	 */
 	public T getModel() {
 		return model;
 	}
 
+	/**
+	 * Returns the binding for the property.
+	 * @param property the property path
+	 * @return the binding
+	 */
 	public Binding getBinding(String property) {
 		Binding binding = bindings.get(property);
 		if (binding == null && !strict) {
@@ -133,6 +174,10 @@ public class Binder<T> {
 		}
 	}
 
+	/**
+	 * Bind values in the map to the properties of the model object.
+	 * @param propertyValues the property values map
+	 */
 	public void bind(Map<String, ? extends Object> propertyValues) {
 		for (Map.Entry<String, ? extends Object> entry : propertyValues
 				.entrySet()) {
diff --git a/org.springframework.context/src/main/java/org/springframework/ui/binding/Binding.java b/org.springframework.context/src/main/java/org/springframework/ui/binding/Binding.java
index ba0a3d82d8..fc5fec1dc1 100644
--- a/org.springframework.context/src/main/java/org/springframework/ui/binding/Binding.java
+++ b/org.springframework.context/src/main/java/org/springframework/ui/binding/Binding.java
@@ -15,22 +15,50 @@
  */
 package org.springframework.ui.binding;
 
+/**
+ * A binding between a user interface element and a model property.
+ * @author Keith Donald
+ */
 public interface Binding {
 
 	// single-value properties
 	
+	/**
+	 * The formatted value to display in the user interface.
+	 */
 	String getValue();
 	
+	/**
+	 * Sets the model property value a from user-entered value.
+	 * @param formatted the value entered by the user
+	 */
 	void setValue(String formatted);
 
+	/**
+	 * Formats a candidate model property value for display in the user interface.
+	 * @param selectableValue a possible value
+	 * @return the formatted value to display in the user interface
+	 */
 	String format(Object selectableValue);
 
 	// multi-value properties
 	
+	/**
+	 * Is this binding associated with a collection or array property?
+	 * If so, a client should call {@link #getValues()} to display property values in the user interface.
+	 * A client should call {@link #setValues(String[])} to set model property values from user-entered/selected values.
+	 */
 	boolean isCollection();
 
+	/**
+	 * When a collection binding, the formatted values to display in the user interface.
+	 */
 	String[] getValues();
 
+	/**
+	 * When a collection binding, sets the model property values a from user-entered/selected values.
+	 * @param formattedValues the values entered by the user
+	 */
 	void setValues(String[] formattedValues);
 	
 }
\ No newline at end of file
diff --git a/org.springframework.context/src/main/java/org/springframework/ui/binding/BindingConfiguration.java b/org.springframework.context/src/main/java/org/springframework/ui/binding/BindingConfiguration.java
index 90f0b77d9e..c7c78fa18d 100644
--- a/org.springframework.context/src/main/java/org/springframework/ui/binding/BindingConfiguration.java
+++ b/org.springframework.context/src/main/java/org/springframework/ui/binding/BindingConfiguration.java
@@ -17,21 +17,37 @@ package org.springframework.ui.binding;
 
 import org.springframework.ui.format.Formatter;
 
+/**
+ * Configuration used to create a new {@link Binding} registered with a {@link Binder}.
+ * @author Keith Donald
+ * @see Binder#add(BindingConfiguration)
+ */
 public class BindingConfiguration {
 	
 	private String property;
 	
 	private Formatter<?> formatter;
 	
+	/**
+	 * Creates a new Binding configuration.
+	 * @param property the property to bind to
+	 * @param formatter the formatter to use to format property values
+	 */
 	public BindingConfiguration(String property, Formatter<?> formatter) {
 		this.property = property;
 		this.formatter = formatter;
 	}
 
+	/**
+	 * The name of the model property to bind to.
+	 */
 	public String getProperty() {
 		return property;
 	}
 
+	/**
+	 * THe Formatter to use to format bound property values.
+	 */
 	public Formatter<?> getFormatter() {
 		return formatter;
 	}
diff --git a/org.springframework.context/src/main/java/org/springframework/ui/binding/package.html b/org.springframework.context/src/main/java/org/springframework/ui/binding/package.html
new file mode 100644
index 0000000000..299fcd6f87
--- /dev/null
+++ b/org.springframework.context/src/main/java/org/springframework/ui/binding/package.html
@@ -0,0 +1,7 @@
+<html>
+<body>
+<p>
+An API for binding property values to fields displayed in a user interface.
+</p>
+</body>
+</html>
\ No newline at end of file
diff --git a/org.springframework.context/src/main/java/org/springframework/ui/format/date/package.html b/org.springframework.context/src/main/java/org/springframework/ui/format/date/package.html
new file mode 100644
index 0000000000..65e89477af
--- /dev/null
+++ b/org.springframework.context/src/main/java/org/springframework/ui/format/date/package.html
@@ -0,0 +1,7 @@
+<html>
+<body>
+<p>
+Formatters for <code>java.util.Date</code>c properties.
+</p>
+</body>
+</html>
\ No newline at end of file
diff --git a/org.springframework.context/src/main/java/org/springframework/ui/format/number/package.html b/org.springframework.context/src/main/java/org/springframework/ui/format/number/package.html
new file mode 100644
index 0000000000..b1e7aaa68e
--- /dev/null
+++ b/org.springframework.context/src/main/java/org/springframework/ui/format/number/package.html
@@ -0,0 +1,7 @@
+<html>
+<body>
+<p>
+Formatters for <code>java.lang.Number</code> properties.
+</p>
+</body>
+</html>
\ No newline at end of file
diff --git a/org.springframework.context/src/main/java/org/springframework/ui/format/package.html b/org.springframework.context/src/main/java/org/springframework/ui/format/package.html
new file mode 100644
index 0000000000..6473ca939a
--- /dev/null
+++ b/org.springframework.context/src/main/java/org/springframework/ui/format/package.html
@@ -0,0 +1,7 @@
+<html>
+<body>
+<p>
+A SPI for defining Formatters to format property values for display in a user interface.
+</p>
+</body>
+</html>
\ No newline at end of file
diff --git a/org.springframework.context/src/main/java/org/springframework/ui/message/package.html b/org.springframework.context/src/main/java/org/springframework/ui/message/package.html
index bc513ce393..e13cbb51fe 100644
--- a/org.springframework.context/src/main/java/org/springframework/ui/message/package.html
+++ b/org.springframework.context/src/main/java/org/springframework/ui/message/package.html
@@ -1,7 +1,7 @@
 <html>
 <body>
 <p>
-A system for creating and managing localized messages to display in a UI.
+An API for creating and managing localized messages to display in a UI.
 </p>
 </body>
 </html>
\ No newline at end of file
diff --git a/org.springframework.context/src/main/java/org/springframework/ui/message/support/package.html b/org.springframework.context/src/main/java/org/springframework/ui/message/support/package.html
new file mode 100644
index 0000000000..e52c72dae1
--- /dev/null
+++ b/org.springframework.context/src/main/java/org/springframework/ui/message/support/package.html
@@ -0,0 +1,7 @@
+<html>
+<body>
+<p>
+Support implementation of the MessageContext API.
+</p>
+</body>
+</html>
\ No newline at end of file