UserManager


1   package org.apache.turbine.services.security;
2   
3   /*
4    * Copyright 2001-2004 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * 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, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.util.List  ;
20  
21  import org.apache.commons.configuration.Configuration;
22  
23  import org.apache.torque.util.Criteria;
24  
25  import org.apache.turbine.om.security.User;
26  import org.apache.turbine.services.InitializationException;
27  import org.apache.turbine.util.security.DataBackendException;
28  import org.apache.turbine.util.security.EntityExistsException;
29  import org.apache.turbine.util.security.PasswordMismatchException;
30  import org.apache.turbine.util.security.UnknownEntityException;
31  
32  /**
33   * An UserManager performs {@link org.apache.turbine.om.security.User} objects
34   * related tasks on behalf of the
35   * {@link org.apache.turbine.services.security.BaseSecurityService}.
36   *
37   * The responsibilities of this class include loading data of an user from the
38   * storage and putting them into the
39   * {@link org.apache.turbine.om.security.User} objects, saving those data
40   * to the permanent storage, and authenticating users.
41   *
42   * @author <a HREF="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
43   * @author <a HREF="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
44   * @version $Id: UserManager.java,v 1.12.2.3 2004/10/08 12:09:43 henning Exp $
45   */
46  public interface UserManager
47  {
48      /**
49       * Initializes the UserManager
50       *
51       * @param conf A Configuration object to init this Manager
52       *
53       * @throws InitializationException When something went wrong.
54       */
55      void init(Configuration conf)
56          throws InitializationException;
57      
58      /**
59       * Check whether a specified user's account exists.
60       *
61       * The login name is used for looking up the account.
62       *
63       * @param user The user to be checked.
64       * @return true if the specified account exists
65       * @throws DataBackendException if there was an error accessing the data
66       *         backend.
67       */
68      boolean accountExists(User user)
69              throws DataBackendException;
70  
71      /**
72       * Check whether a specified user's account exists.
73       *
74       * The login name is used for looking up the account.
75       *
76       * @param userName The name of the user to be checked.
77       * @return true if the specified account exists
78       * @throws DataBackendException if there was an error accessing the data
79       *         backend.
80       */
81      boolean accountExists(String   userName)
82              throws DataBackendException;
83  
84      /**
85       * Retrieve a user from persistent storage using username as the
86       * key.
87       *
88       * @param username the name of the user.
89       * @return an User object.
90       * @throws UnknownEntityException if the user's record does not
91       *         exist in the database.
92       * @throws DataBackendException if there is a problem accessing the
93       *         storage.
94       */
95      User retrieve(String   username)
96              throws UnknownEntityException, DataBackendException;
97  
98      /**
99       * Retrieve a user from persistent storage using the primary key
100      *
101      * @param key The primary key object
102      * @return an User object.
103      * @throws UnknownEntityException if the user's record does not
104      *         exist in the database.
105      * @throws DataBackendException if there is a problem accessing the
106      *         storage.
107      */
108     User retrieveById(Object   key)
109             throws UnknownEntityException, DataBackendException;
110 
111     /**
112      * Retrieve a set of users that meet the specified criteria.
113      *
114      * As the keys for the criteria, you should use the constants that
115      * are defined in {@link User} interface, plus the names
116      * of the custom attributes you added to your user representation
117      * in the data storage. Use verbatim names of the attributes -
118      * without table name prefix in case of DB implementation.
119      *
120      * @param criteria The criteria of selection.
121      * @return a List of users meeting the criteria.
122      * @throws DataBackendException if there is a problem accessing the
123      *         storage.
124      * @deprecated Use retrieveList(Criteria crit)
125      */
126     User[] retrieve(Criteria criteria) throws DataBackendException;
127 
128     /**
129      * Retrieve a list of users that meet the specified criteria.
130      *
131      * As the keys for the criteria, you should use the constants that
132      * are defined in {@link User} interface, plus the names
133      * of the custom attributes you added to your user representation
134      * in the data storage. Use verbatim names of the attributes -
135      * without table name prefix in case of DB implementation.
136      *
137      * @param criteria The criteria of selection.
138      * @return a List of users meeting the criteria.
139      * @throws DataBackendException if there is a problem accessing the
140      *         storage.
141      */
142     List   retrieveList(Criteria criteria)
143         throws DataBackendException;
144 
145     /**
146      * Retrieve a user from persistent storage using username as the
147      * key, and authenticate the user. The implementation may chose
148      * to authenticate to the server as the user whose data is being
149      * retrieved.
150      *
151      * @param username the name of the user.
152      * @param password the user supplied password.
153      * @return an User object.
154      * @throws PasswordMismatchException if the supplied password was incorrect.
155      * @throws UnknownEntityException if the user's record does not
156      *         exist in the database.
157      * @throws DataBackendException if there is a problem accessing the storage.
158      */
159     User retrieve(String   username, String   password)
160             throws PasswordMismatchException, UnknownEntityException,
161             DataBackendException;
162 
163     /**
164      * Save an User object to persistent storage. User's record is
165      * required to exist in the storage.
166      *
167      * @param user an User object to store.
168      * @throws UnknownEntityException if the user's record does not
169      *         exist in the database.
170      * @throws DataBackendException if there is a problem accessing the storage.
171      */
172     void store(User user)
173             throws UnknownEntityException, DataBackendException;
174 
175     /**
176      * Saves User data when the session is unbound. The user account is required
177      * to exist in the storage.
178      *
179      * LastLogin, AccessCounter, persistent pull tools, and any data stored
180      * in the permData hashtable that is not mapped to a column will be saved.
181      *
182      * @exception UnknownEntityException if the user's account does not
183      *            exist in the database.
184      * @exception DataBackendException if there is a problem accessing the
185      *            storage.
186      */
187     public void saveOnSessionUnbind(User user)
188             throws UnknownEntityException, DataBackendException;
189 
190     /**
191      * Authenticate an User with the specified password. If authentication
192      * is successful the method returns nothing. If there are any problems,
193      * exception was thrown.
194      *
195      * @param user an User object to authenticate.
196      * @param password the user supplied password.
197      * @throws PasswordMismatchException if the supplied password was incorrect.
198      * @throws UnknownEntityException if the user's record does not
199      *         exist in the database.
200      * @throws DataBackendException if there is a problem accessing the storage.
201      */
202     void authenticate(User user, String   password)
203             throws PasswordMismatchException, UnknownEntityException,
204             DataBackendException;
205 
206     /**
207      * Creates new user account with specified attributes.
208      *
209      * @param user the object describing account to be created.
210      * @param initialPassword password for the new user
211      * @throws DataBackendException if there was an error accessing the data
212      *         backend.
213      * @throws EntityExistsException if the user account already exists.
214      */
215     void createAccount(User user, String   initialPassword)
216             throws EntityExistsException, DataBackendException;
217 
218     /**
219      * Removes an user account from the system.
220      *
221      * @param user the object describing the account to be removed.
222      * @throws DataBackendException if there was an error accessing the data
223      *         backend.
224      * @throws UnknownEntityException if the user account is not present.
225      */
226     void removeAccount(User user)
227             throws UnknownEntityException, DataBackendException;
228 
229     /**
230      * Change the password for an User.
231      *
232      * @param user an User to change password for.
233      * @param oldPassword the current password suplied by the user.
234      * @param newPassword the current password requested by the user.
235      * @throws PasswordMismatchException if the supplied password was incorrect.
236      * @throws UnknownEntityException if the user's record does not
237      *         exist in the database.
238      * @throws DataBackendException if there is a problem accessing the storage.
239      */
240     void changePassword(User user, String   oldPassword,
241                         String   newPassword)
242             throws PasswordMismatchException, UnknownEntityException,
243             DataBackendException;
244 
245     /**
246      * Forcibly sets new password for an User.
247      *
248      * This is supposed by the administrator to change the forgotten or
249      * compromised passwords. Certain implementatations of this feature
250      * would require administrative level access to the authenticating
251      * server / program.
252      *
253      * @param user an User to change password for.
254      * @param password the new password.
255      * @throws UnknownEntityException if the user's record does not
256      *            exist in the database.
257      * @throws DataBackendException if there is a problem accessing the storage.
258      */
259     void forcePassword(User user, String   password)
260             throws UnknownEntityException, DataBackendException;
261 }
262
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags