UserProvider


1   /**
2    * $RCSfile: UserProvider.java,v $
3    * $Revision: 1.5 $
4    * $Date: 2005/07/08 20:22:32 $
5    *
6    * Copyright (C) 2004 Jive Software. All rights reserved.
7    *
8    * This software is published under the terms of the GNU Public License (GPL),
9    * a copy of which is included in this distribution.
10   */
11  
12  package org.jivesoftware.messenger.user;
13  
14  import java.util.Date  ;
15  import java.util.Collection  ;
16  import java.util.Set  ;
17  
18  /**
19   * Provider interface for the user system.
20   *
21   * @author Matt Tucker
22   */
23  public interface UserProvider {
24  
25      /**
26       * Loads the specified user by username.
27       *
28       * @param username the username
29       * @return the User.
30       * @throws UserNotFoundException if the User could not be loaded.
31       */
32      public User loadUser(String   username) throws UserNotFoundException;
33  
34      /**
35       * Creates a new user. This method should throw an
36       * UnsupportedOperationException if this operation is not
37       * supporte by the backend user store.
38       *
39       * @param username the username.
40       * @param password the plain-text password.
41       * @param name the user's name, which can be <tt>null</tt>.
42       * @param email the user's email address, which can be <tt>null</tt>.
43       * @return a new User.
44       * @throws UserAlreadyExistsException if the username is already in use.
45       */
46      public User createUser(String   username, String   password, String   name, String   email)
47              throws UserAlreadyExistsException;
48  
49      /**
50       * Delets a user. This method should throw an
51       * UnsupportedOperationException if this operation is not
52       * supported by the backend user store.
53       *
54       * @param username the username to delete.
55       */
56      public void deleteUser(String   username);
57  
58      /**
59       * Returns the number of users in the system.
60       *
61       * @return the total number of users.
62       */
63      public int getUserCount();
64  
65      /**
66       * Returns an unmodifiable Collections of all users in the system. The
67       * {@link UserCollection} class can be used to assist in the implementation
68       * of this method. It takes a String [] of usernames and presents it as a
69       * Collection of User objects (obtained with calls to
70       * {@link UserManager#getUser(String)}.
71       *
72       * @return an unmodifiable Collection of all users.
73       */
74      public Collection  <User> getUsers();
75  
76      /**
77       * Returns an unmodifiable Collections of users in the system within the
78       * specified range. The {@link UserCollection} class can be used to assist
79       * in the implementation of this method. It takes a String [] of usernames
80       * and presents it as a  Collection of User objects (obtained with calls to
81       * {@link UserManager#getUser(String)}.<p>
82       *
83       * It is possible that the number of results returned will be less than that
84       * specified by <tt>numResults</tt> if <tt>numResults</tt> is greater than the
85       * number of records left to display.
86       *
87       * @param startIndex the beginning index to start the results at.
88       * @param numResults the total number of results to return.
89       * @return an unmodifiable Collection of users within the specified range.
90       */
91      public Collection  <User> getUsers(int startIndex, int numResults);
92  
93      /**
94       * Returns the user's password. This method should throw an UnsupportedOperationException
95       * if this operation is not supported by the backend user store.
96       *
97       * @param username the username of the user.
98       * @return the user's password.
99       * @throws UserNotFoundException if the given user could not be loaded.
100      * @throws UnsupportedOperationException if the provider does not
101      *      support the operation (this is an optional operation).
102      */
103     public String   getPassword(String   username) throws UserNotFoundException,
104             UnsupportedOperationException  ;
105 
106     /**
107      * Sets the users's password. This method should throw an UnsupportedOperationException
108      * if this operation is not supported by the backend user store.
109      *
110      * @param username the username of the user.
111      * @param password the new plaintext password for the user.
112      * @throws UserNotFoundException if the given user could not be loaded.
113      * @throws UnsupportedOperationException if the provider does not
114      *      support the operation (this is an optional operation).
115      */
116     public void setPassword(String   username, String   password)
117             throws UserNotFoundException, UnsupportedOperationException  ;
118 
119     /**
120      * Sets the user's name. This method should throw an UnsupportedOperationException
121      * if this operation is not supported by the backend user store.
122      *
123      * @param username the username.
124      * @param name the name.
125      * @throws UserNotFoundException if the user could not be found.
126      */
127     public void setName(String   username, String   name) throws UserNotFoundException;
128 
129     /**
130      * Sets the user's email address. This method should throw an
131      * UnsupportedOperationException if this operation is not supported
132      * by the backend user store.
133      *
134      * @param username the username.
135      * @param email the email address.
136      * @throws UserNotFoundException if the user could not be found.
137      */
138     public void setEmail(String   username, String   email) throws UserNotFoundException;
139 
140     /**
141      * Sets the date the user was created. This method should throw an
142      * UnsupportedOperationException if this operation is not supported
143      * by the backend user store.
144      *
145      * @param username the username.
146      * @param creationDate the date the user was created.
147      * @throws UserNotFoundException if the user could not be found.
148      */
149     public void setCreationDate(String   username, Date   creationDate) throws UserNotFoundException;
150 
151     /**
152      * Sets the date the user was last modified. This method should throw an
153      * UnsupportedOperationException if this operation is not supported
154      * by the backend user store.
155      *
156      * @param username the username.
157      * @param modificationDate the date the user was last modified.
158      * @throws UserNotFoundException if the user could not be found.
159      */
160     public void setModificationDate(String   username, Date   modificationDate)
161             throws UserNotFoundException;
162 
163     /**
164      * Returns the set of fields that can be used for searching for users. Each field
165      * returned must support wild-card and keyword searching. For example, an
166      * implementation might send back the set {"Username", "Name", "Email"}. Any of
167      * those three fields can then be used in a search with the
168      * {@link #findUsers(Set,String)} method.<p>
169      *
170      * This method should throw an UnsupportedOperationException if this
171      * operation is not supported by the backend user store.
172      *
173      * @return the valid search fields.
174      * @throws UnsupportedOperationException if the provider does not
175      *      support the operation (this is an optional operation).
176      */
177     public Set  <String  > getSearchFields() throws UnsupportedOperationException  ;
178 
179     /**
180      * Searches for users based on a set of fields and a query string. The fields must
181      * be taken from the values returned by {@link #getSearchFields()}. The query can
182      * include wildcards. For example, a search on the field "Name" with a query of "Ma*"
183      * might return user's with the name "Matt", "Martha" and "Madeline".<p>
184      *
185      * This method should throw an UnsupportedOperationException if this
186      * operation is not supported by the backend user store. 
187      *
188      * @param fields the fields to search on.
189      * @param query the query string.
190      * @return a Collection of users that match the search.
191      * @throws UnsupportedOperationException if the provider does not
192      *      support the operation (this is an optional operation).
193      */
194     public Collection  <User> findUsers(Set  <String  > fields, String   query)
195             throws UnsupportedOperationException  ;
196 
197     /**
198      * Searches for users based on a set of fields and a query string. The fields must
199      * be taken from the values returned by {@link #getSearchFields()}. The query can
200      * include wildcards. For example, a search on the field "Name" with a query of "Ma*"
201      * might return user's with the name "Matt", "Martha" and "Madeline".<p>
202      *
203      * The startIndex and numResults parameters are used to page through search
204      * results. For example, if the startIndex is 0 and numResults is 10, the first
205      * 10 search results will be returned. Note that numResults is a request for the
206      * number of results to return and that the actual number of results returned
207      * may be fewer.<p>
208      *
209      * This method should throw an UnsupportedOperationException if this
210      * operation is not supported by the backend user store.
211      *
212      * @param fields the fields to search on.
213      * @param query the query string.
214      * @return a Collection of users that match the search.
215      * @return startIndex the starting index in the search result to return.
216      * @return numResults the number of users to return in the search result.
217      * @throws UnsupportedOperationException if the provider does not
218      *      support the operation (this is an optional operation).
219      */
220     public Collection  <User> findUsers(Set  <String  > fields, String   query, int startIndex,
221             int numResults) throws UnsupportedOperationException  ;
222 
223     /**
224      * Returns true if this UserProvider is read-only. When read-only,
225      * users can not be created, deleted, or modified.
226      *
227      * @return true if the user provider is read-only.
228      */
229     public boolean isReadOnly();
230 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags