View Javadoc

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