SEC-367: Added clarification of immutability contract.

core/src/main/java/org/acegisecurity/userdetails/UserDetails.java

@@ -39,6 +39,12 @@ import java.io.Serializable;
  * reference implementation (which you might like to extend).
  * </p>
  * 
+ * <p>
+ * Concrete implementations should be immutable (value object semantics,
+ * like a String). This is because the <code>UserDetails</code> will be
+ * stored in caches and as such multiple threads may use the same instance.
+ * </p>
+ *
  * @author Ben Alex
  * @version $Id$
  */