1 /****************************************************************
2 * Licensed to the Apache Software Foundation (ASF) under one *
3 * or more contributor license agreements. See the NOTICE file *
4 * distributed with this work for additional information *
5 * regarding copyright ownership. The ASF licenses this file *
6 * to you under the Apache License, Version 2.0 (the *
7 * "License"); you may not use this file except in compliance *
8 * with the License. You may obtain a copy of the License at *
9 * *
10 * http://www.apache.org/licenses/LICENSE-2.0 *
11 * *
12 * Unless required by applicable law or agreed to in writing, *
13 * software distributed under the License is distributed on an *
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
15 * KIND, either express or implied. See the License for the *
16 * specific language governing permissions and limitations *
17 * under the License. *
18 ****************************************************************/
19
20
21
22 package org.apache.james.api.user.management;
23
24 import java.util.List;
25
26 /**
27 * Expose user account management functionality through JMX.
28 *
29 * @phoenix:mx-topic name="UserAdministration"
30 */
31 public interface UserManagementMBean {
32
33 /**
34 * Adds a user to this mail server.
35 *
36 * @phoenix:mx-operation
37 * @phoenix:mx-description Add a new user
38 *
39 * @param userName The name of the user being added
40 * @param password The password of the user being added
41 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
42 * repository is used.
43 * @return if the operation was successfull
44 */
45 boolean addUser(String userName, String password, String repositoryName) throws UserManagementException;
46
47 /**
48 * Deletes a user from this mail server.
49 *
50 * @phoenix:mx-operation
51 * @phoenix:mx-description Delete an existing user
52 *
53 * @param userName The name of the user being deleted
54 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
55 * repository is used.
56 * @return if the operation was successfull
57 */
58 boolean deleteUser(String userName, String repositoryName) throws UserManagementException;
59
60 /**
61 * Check if a user exists with the given name.
62 *
63 * @phoenix:mx-operation
64 * @phoenix:mx-description Check for existing user name
65 *
66 * @param userName The name of the user
67 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
68 * repository is used.
69 * @return TRUE, if the user exists
70 */
71 boolean verifyExists(String userName, String repositoryName) throws UserManagementException;
72
73 /**
74 * Total count of existing users
75 *
76 * @phoenix:mx-operation
77 * @phoenix:mx-description Total count of existing users
78 *
79 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
80 * repository is used.
81 * @return Total count of existing users
82 */
83 long countUsers(String repositoryName) throws UserManagementException;
84
85 /**
86 * List the names of all users
87 *
88 * @phoenix:mx-operation
89 * @phoenix:mx-description List all existing users
90 *
91 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
92 * repository is used.
93 * @return List of all user names
94 */
95 String[] listAllUsers(String repositoryName) throws UserManagementException;
96
97 /**
98 * Set a user's password
99 *
100 * @phoenix:mx-operation
101 * @phoenix:mx-description Set a user's password
102 *
103 * @param userName The name of the user whose password will be changed
104 * @param password The new password
105 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
106 * repository is used.
107 * @return if the user has been found and the password was changed successfully
108 */
109 boolean setPassword(String userName, String password, String repositoryName) throws UserManagementException;
110
111 /**
112 * Set a user's alias to whom all mail is forwarded to
113 *
114 * @phoenix:mx-operation
115 * @phoenix:mx-description Set a user's alias to whom all mail is forwarded to
116 *
117 * @param userName The name of the user whose alias is set
118 * @param aliasUserName The user becoming the new alias
119 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
120 * repository is used.
121 * @return if the user has been found and the password was changed successfully
122 */
123 boolean setAlias(String userName, String aliasUserName, String repositoryName) throws UserManagementException;
124
125 /**
126 * Removes a user's alias which terminates local mail forwarding
127 *
128 * @phoenix:mx-operation
129 * @phoenix:mx-description Removes a user's alias which terminates local mail forwarding
130 *
131 * @param userName The name of the user whose alias is unset
132 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
133 * repository is used.
134 * @return if the user has been found and the alias was removed
135 */
136 boolean unsetAlias(String userName, String repositoryName) throws UserManagementException;
137
138 /**
139 * Retrieves the user's alias, if set
140 *
141 * @phoenix:mx-operation
142 * @phoenix:mx-description Retrieves the user's alias, if set
143 *
144 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
145 * repository is used.
146 * @return User's alias, or NULL, if no alias is set
147 */
148 String getAlias(String userName, String repositoryName) throws UserManagementException;
149
150 /**
151 * Set a user's forward email address to whom all mail is forwarded to
152 *
153 * @phoenix:mx-operation
154 * @phoenix:mx-description Set a user's forward email address to whom all mail is forwarded to
155 *
156 * @param userName The name of the user whose forward is set
157 * @param forwardEmailAddress The new forward email address
158 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
159 * repository is used.
160 * @return if the user has been found and the password was changed successfully
161 */
162 boolean setForwardAddress(String userName, String forwardEmailAddress, String repositoryName) throws UserManagementException;
163
164 /**
165 * Removes a user's forward email address which terminates remote mail forwarding
166 *
167 * @phoenix:mx-operation
168 * @phoenix:mx-description Removes a user's forward email address which terminates remote mail forwarding
169 *
170 * @param userName The name of the user whose forward is unset
171 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
172 * repository is used.
173 * @return if the user has been found and the forward was removed
174 */
175 boolean unsetForwardAddress(String userName, String repositoryName) throws UserManagementException;
176
177 /**
178 * Retrieves the user's forward, if set
179 *
180 * @phoenix:mx-operation
181 * @phoenix:mx-description Retrieves the user's forward, if set
182 *
183 * @param userName The name of the user whose forward is set
184 * @param repositoryName The user repository, to which the operation should be applied. If NULL, the LocalUsers
185 * repository is used.
186 * @return User's forward email address, or NULL, if no forward is set
187 */
188 String getForwardAddress(String userName, String repositoryName) throws UserManagementException;
189
190 /**
191 * Retrieves a list of the names of all available user repositories
192 *
193 * @phoenix:mx-operation
194 * @phoenix:mx-description Retrieves a list of the names of all available user repositories
195 *
196 * @return List<String> of repository names
197 */
198 List getUserRepositoryNames();
199 }