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;
23
24 import java.util.Iterator;
25
26 /**
27 * Interface for a repository of users. A repository represents a logical
28 * grouping of users, typically by common purpose. E.g. the users served by an
29 * email server or the members of a mailing list.
30 *
31 *
32 * @version $Revision: 684562 $
33 */
34 public interface UsersRepository {
35
36 /**
37 * The component role used by components implementing this service
38 */
39 String ROLE = "org.apache.james.api.user.UsersRepository";
40
41 String USER = "USER";
42
43 /**
44 * Adds a user to the repository with the specified User object.
45 *
46 * @param user the user to be added
47 *
48 * @return true if succesful, false otherwise
49 * @since James 1.2.2
50 *
51 * @deprecated James 2.4 user should be added using username/password
52 * because specific implementations of UsersRepository will support specific
53 * implementations of users object.
54 */
55 boolean addUser(User user);
56
57 /**
58 * Adds a user to the repository with the specified attributes. In current
59 * implementations, the Object attributes is generally a String password.
60 *
61 * @param name the name of the user to be added
62 * @param attributes see decription
63 *
64 * @deprecated James 2.4 user is always added using username/password and
65 * eventually modified by retrieving it later.
66 */
67 void addUser(String name, Object attributes);
68
69 /**
70 * Adds a user to the repository with the specified password
71 *
72 * @param username the username of the user to be added
73 * @param password the password of the user to add
74 * @return true if succesful, false otherwise
75 *
76 * @since James 2.3.0
77 */
78 boolean addUser(String username, String password);
79
80 /**
81 * Get the user object with the specified user name. Return null if no
82 * such user.
83 *
84 * @param name the name of the user to retrieve
85 * @return the user being retrieved, null if the user doesn't exist
86 *
87 * @since James 1.2.2
88 */
89 User getUserByName(String name);
90
91 /**
92 * Get the user object with the specified user name. Match user naems on
93 * a case insensitive basis. Return null if no such user.
94 *
95 * @param name the name of the user to retrieve
96 * @return the user being retrieved, null if the user doesn't exist
97 *
98 * @since James 1.2.2
99 * @deprecated James 2.4 now caseSensitive is a property of the repository
100 * implementations and the getUserByName will search according to this property.
101 */
102 User getUserByNameCaseInsensitive(String name);
103
104 /**
105 * Returns the user name of the user matching name on an equalsIgnoreCase
106 * basis. Returns null if no match.
107 *
108 * @param name the name to case-correct
109 * @return the case-correct name of the user, null if the user doesn't exist
110 */
111 String getRealName(String name);
112
113 /**
114 * Update the repository with the specified user object. A user object
115 * with this username must already exist.
116 *
117 * @return true if successful.
118 */
119 boolean updateUser(User user);
120
121 /**
122 * Removes a user from the repository
123 *
124 * @param name the user to remove from the repository
125 */
126 void removeUser(String name);
127
128 /**
129 * Returns whether or not this user is in the repository
130 *
131 * @param name the name to check in the repository
132 * @return whether the user is in the repository
133 */
134 boolean contains(String name);
135
136 /**
137 * Returns whether or not this user is in the repository. Names are
138 * matched on a case insensitive basis.
139 *
140 * @param name the name to check in the repository
141 * @return whether the user is in the repository
142 *
143 * @deprecated James 2.4 now caseSensitive is a property of the repository
144 * implementations and the contains will search according to this property.
145 */
146 boolean containsCaseInsensitive(String name);
147
148 /**
149 * Test if user with name 'name' has password 'password'.
150 *
151 * @param name the name of the user to be tested
152 * @param password the password to be tested
153 *
154 * @return true if the test is successful, false if the user
155 * doesn't exist or if the password is incorrect
156 *
157 * @since James 1.2.2
158 */
159 boolean test(String name, String password);
160
161 /**
162 * Returns a count of the users in the repository.
163 *
164 * @return the number of users in the repository
165 */
166 int countUsers();
167
168 /**
169 * List users in repository.
170 *
171 * @return Iterator over a collection of Strings, each being one user in the repository.
172 */
173 Iterator list();
174
175 }