SEC-1804: Updated Javadoc wrt immutability of User class.

core/src/main/java/org/springframework/security/core/userdetails/User.java

@@ -31,7 +31,6 @@ import org.springframework.util.Assert;
 /**
  * Models core user information retrieved by a {@link UserDetailsService}.
  * <p>
- * Implemented with value object semantics (immutable after construction, like a <code>String</code>).
  * Developers may use this class directly, subclass it, or write their own {@link UserDetails} implementation from
  * scratch.
  * <p>
@@ -39,6 +38,11 @@ import org.springframework.util.Assert;
  * intention is that lookups of the same user principal object (in a user registry, for example) will match
  * where the objects represent the same user, not just when all the properties (authorities, password for
  * example) are the same.
+ * <p>
+ * Note that this implementation is not immutable. It implements the {@code CredentialsContainer} interface, in order
+ * to allow the password to be erased after authentication. This may cause side-effects if you are storing instances
+ * in-memory and reusing them. If so, make sure you return a copy from your {@code UserDetailsService} each time it is
+ * invoked.
  *
  * @author Ben Alex
  * @author Luke Taylor

core/src/main/java/org/springframework/security/core/userdetails/UserDetails.java

@@ -35,16 +35,7 @@ import java.util.Collection;
  * Concrete implementations must take particular care to ensure the non-null
  * contract detailed for each method is enforced. See
  * {@link org.springframework.security.core.userdetails.User} for a
- * reference implementation (which you might like to extend).
- * <p>
- * Concrete implementations should be preferably be immutable &ndash; they should
- * have value object semantics, like a String. The <code>UserDetails</code> may be
- * stored in a cache and multiple threads may use the same instance. Immutable
- * objects are more robust and are guaranteed to be thread-safe. This is not strictly
- * essential (there's nothing within Spring Security itself which absolutely requires it),
- * but if your <tt>UserDetails</tt> object <em>can</em> be modified then it's up to you to make
- * sure that you do so safely and that you manage any caches which may contain copies of
- * the object.
+ * reference implementation (which you might like to extend or use in your code).
  *
  * @see UserDetailsService
  * @see UserCache

core/src/main/java/org/springframework/security/provisioning/InMemoryUserDetailsManager.java

@@ -117,4 +117,7 @@ public class InMemoryUserDetailsManager implements UserDetailsManager {
                 user.isCredentialsNonExpired(), user.isAccountNonLocked(), user.getAuthorities());
     }
 
+    public void setAuthenticationManager(AuthenticationManager authenticationManager) {
+        this.authenticationManager = authenticationManager;
+    }
 }