1   package com.atlassian.user;
2   
3   import com.atlassian.user.impl.RepositoryException;
4   import com.atlassian.user.search.page.Pager;
5   import com.atlassian.user.security.password.Credential;
6   import com.atlassian.user.security.password.PasswordEncryptor;
7   import com.atlassian.user.impl.DuplicateEntityException;
8   
9   public interface UserManager extends EntityManager
10  {
11      /**
12       * @return a {@link Pager} holding all users being managed.
13       * @throws EntityException
14       */
15      Pager<User> getUsers()  throws EntityException;
16  
17      /**
18       * @return a {@link Pager} holding the names of all users being managed.
19       * @throws EntityException
20       */
21      Pager<String> getUserNames() throws EntityException;
22  
23      /**
24       * @return a <code>null</code> or a {@link User} if one could be found.
25       */
26      User getUser(String username) throws EntityException;
27  
28      /**
29       * Creates a new user with the username provided. Returns the newly created user.
30       *
31       * @return a {@link User} object representing the new user.
32       * @throws DuplicateEntityException if a user with the username already exists.
33       * @throws UnsupportedOperationException - if {@link UserManager#isCreative()} returns <code>false</code>.
34       * @deprecated since 2.2 use {@link #createUser(User, Credential)} to create users without using the deprecated
35       * setFullName() and setEmail() methods on the User interface. Calls to this method can generally be replace with
36       * the following: <code>createUser(new DefaultUser(username), Credential.NONE)</code>.
37       */
38      User createUser(String username) throws EntityException;
39  
40      /**
41       * Creates a new user with the provided user details and encrypted password. Returns the newly created user.
42       *
43       * @param userTemplate the user template to use, which must have a non-null user name
44       * @param credential the user's password
45       * @return the newly created user, which should be used for subsequent operations on that user
46       * @throws DuplicateEntityException if a user with the same name already exists
47       * @throws RepositoryException if there is a problem communicating with the underlying storage mechanism
48       * @throws UnsupportedOperationException if {@link #isCreative()} returns {@code false}
49       * @throws IllegalArgumentException if the user, user name or credential is null
50       * @since 2.2
51       */
52      User createUser(User userTemplate, Credential credential)
53          throws EntityException, UnsupportedOperationException, IllegalArgumentException;
54  
55      /**
56       * Encrypts the plain password, sets it on the user, and saves the user.
57       * Implementations supporting this will usually have an internal {@link PasswordEncryptor}.
58       *
59       * @throws UnsupportedOperationException - if {@link UserManager#isCreative()} returns <code>false</code>.
60       */
61      void alterPassword(User user, String plainTextPass) throws EntityException;
62  
63      /**
64       * Persists any changes made to the user to the storage system used by this user manager.
65       * <p/>
66       * To ensure consistent behaviour across all repository types, clients must call this method after
67       * using {@link User#setEmail(String)}, {@link User#setFullName(String)} or {@link User#setPassword(String)}.
68       *
69       * @throws UnsupportedOperationException - if {@link UserManager#isCreative()} returns <code>false</code>
70       * @throws IllegalArgumentException if the user is null or not managed by this repository
71       */
72      void saveUser(User user) throws EntityException, IllegalArgumentException;
73  
74      /**
75       * Removes the specified user from the repository.
76       *
77       * @throws UnsupportedOperationException if {@link UserManager#isReadOnly(User)} returns <code>true</code>.
78       * @throws IllegalArgumentException if the user is null or not managed by this repository
79       */
80      void removeUser(User user) throws EntityException, IllegalArgumentException;
81  
82      /**
83       * @return true indicates that information on the user object cannot be altered in the storage system
84       * (see {@link com.atlassian.user.repository.RepositoryIdentifier}),
85       * false indicates that the storage system will save changes or that this {@link UserManager} does not 
86       * know about the {@link User}.
87       */
88      boolean isReadOnly(User user) throws EntityException;
89  }
90