svn commit: r1005256 - /incubator/bval/sandbox/lang3-work/bval-jsr303d/src/main/java/org/apache/bval/jsr303/dynamic/ConstraintAppender.java

[mb...@apache.org]

Author: mbenson
Date: Wed Oct  6 21:07:36 2010
New Revision: 1005256

URL: http://svn.apache.org/viewvc?rev=1005256&view=rev
Log:
documnt principle of mutual annihilation

Modified:
    incubator/bval/sandbox/lang3-work/bval-jsr303d/src/main/java/org/apache/bval/jsr303/dynamic/ConstraintAppender.java

Modified: incubator/bval/sandbox/lang3-work/bval-jsr303d/src/main/java/org/apache/bval/jsr303/dynamic/ConstraintAppender.java
URL: http://svn.apache.org/viewvc/incubator/bval/sandbox/lang3-work/bval-jsr303d/src/main/java/org/apache/bval/jsr303/dynamic/ConstraintAppender.java?rev=1005256&r1=1005255&r2=1005256&view=diff
==============================================================================
--- incubator/bval/sandbox/lang3-work/bval-jsr303d/src/main/java/org/apache/bval/jsr303/dynamic/ConstraintAppender.java (original)
+++ incubator/bval/sandbox/lang3-work/bval-jsr303d/src/main/java/org/apache/bval/jsr303/dynamic/ConstraintAppender.java Wed Oct  6 21:07:36 2010
@@ -27,14 +27,18 @@ import java.util.Collection;
 import org.apache.bval.jsr303.util.SecureActions;
 
 /**
- * Interface specifying a means of applying a constraint annotation to a
+ * <p>Interface specifying a means of applying a constraint annotation to a
  * collection of same, thus allowing for the situation where the addition of a
  * constraint must result in the eviction or modification of existing
  * constraints, the added constraint, or, indeed, any imaginable combination
- * thereof. Caveat: Because dynamic constraints must be applied multiple times
- * (i.e. setup vs. "playback"), it's important that a {@link ConstraintAppender}
- * always contribute something to the collection, even when the true intent is
- * to do nothing.
+ * thereof.</p>
+ * <p>Current recommendation is to follow a principle of mutual annihilation
+ * when a constraint encounters its anti-constraint; conversely, to allow even
+ * a noop constraint to lie dormant in the collection of dynamic constraints
+ * with the expectation that a subsequent merge of dynamic metadata will
+ * result in its meeting its anti-constraint (that constraint having been specified
+ * at a more generic level).  Only time will tell if this approach satisfies
+ * the principle of least surprise.</p>
  * 
  * @version $Rev$ $Date$
  */