Refines the HasValue documentation, in particular wrt use of null and value equality. Desk review by jlabanca
git-svn-id: https://google-web-toolkit.googlecode.com/svn/releases/1.6@4164 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/user/src/com/google/gwt/user/client/ui/CheckBox.java b/user/src/com/google/gwt/user/client/ui/CheckBox.java
index 1b1a8f3..a9eba4f 100644
--- a/user/src/com/google/gwt/user/client/ui/CheckBox.java
+++ b/user/src/com/google/gwt/user/client/ui/CheckBox.java
@@ -219,6 +219,7 @@
}
public void setValue(Boolean value, boolean fireEvents) {
+ assert null != value : "Value must not be null";
if (isChecked() == value) {
return;
}
diff --git a/user/src/com/google/gwt/user/client/ui/HasValue.java b/user/src/com/google/gwt/user/client/ui/HasValue.java
index f3240e9..0c7d36f 100644
--- a/user/src/com/google/gwt/user/client/ui/HasValue.java
+++ b/user/src/com/google/gwt/user/client/ui/HasValue.java
@@ -20,6 +20,11 @@
/**
* An object that implements this interface should be a user input widget, where
* the user and programmer can both set and get the object's value.
+ * <p>
+ * It is a requirement that a value passed to {@link setValue} be
+ * {@link Object#equals} to that returned by an immediately succeeding call to
+ * {@link getValue}, or that both be null. Note that this is not a requirement
+ * that <code>setValue(null)</code> be supported by all implementors.
*
* @param <T> the type of value.
*/
@@ -33,8 +38,11 @@
T getValue();
/**
- * Sets this object's value without firing any events. Should call setValue(T
- * value, false).
+ * Sets this object's value without firing any events. This should be
+ * identical to calling setValue(value, false).
+ * <p>
+ * It is acceptable to fail assertions or throw (documented) unchecked
+ * exceptions in response to bad values.
*
* @param value the object's new value
*/
@@ -44,6 +52,9 @@
* Sets this object's value. Fires
* {@link com.google.gwt.event.logical.shared.ValueChangeEvent} when
* fireEvents is true and the new value does not equal the existing value.
+ * <p>
+ * It is acceptable to fail assertions or throw (documented) unchecked
+ * exceptions in response to bad values.
*
* @param value the object's new value
* @param fireEvents fire events if true and value is new
diff --git a/user/src/com/google/gwt/user/client/ui/TextBoxBase.java b/user/src/com/google/gwt/user/client/ui/TextBoxBase.java
index 3a8554e..3f7660a 100644
--- a/user/src/com/google/gwt/user/client/ui/TextBoxBase.java
+++ b/user/src/com/google/gwt/user/client/ui/TextBoxBase.java
@@ -301,6 +301,7 @@
}
public void setValue(String value, boolean fireEvents) {
+ assert null != value : "Value must not be null";
String oldValue = getText();
setText(value);
if (fireEvents) {
