UserManager


1   package org.apache.fulcrum.security;
2   
3   /* ====================================================================
4    * The Apache Software License, Version 1.1
5    *
6    * Copyright (c) 2001 The Apache Software Foundation.  All rights
7    * reserved.
8    *
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   *
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   *
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   *
21   * 3. The end-user documentation included with the redistribution,
22   *    if any, must include the following acknowledgment:
23   *       "This product includes software developed by the
24   *        Apache Software Foundation (http://www.apache.org/)."
25   *    Alternately, this acknowledgment may appear in the software itself,
26   *    if and wherever such third-party acknowledgments normally appear.
27   *
28   * 4. The names "Apache" and "Apache Software Foundation" and
29   *    "Apache Turbine" must not be used to endorse or promote products
30   *    derived from this software without prior written permission. For
31   *    written permission, please contact apache@apache.org.
32   *
33   * 5. Products derived from this software may not be called "Apache",
34   *    "Apache Turbine", nor may "Apache" appear in their name, without
35   *    prior written permission of the Apache Software Foundation.
36   *
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   *
51   * This software consists of voluntary contributions made by many
52   * individuals on behalf of the Apache Software Foundation.  For more
53   * information on the Apache Software Foundation, please see
54   * <http://www.apache.org/>.
55   */
56  
57  import org.apache.fulcrum.security.entity.User;
58  import org.apache.fulcrum.security.util.DataBackendException;
59  import org.apache.fulcrum.security.util.UnknownEntityException;
60  import org.apache.fulcrum.security.util.EntityExistsException;
61  import org.apache.fulcrum.security.util.PasswordMismatchException;
62  
63  import org.apache.torque.util.Criteria;
64  
65  /**
66   * An UserManager performs {@link org.apache.fulcrum.security.entity.User} objects
67   * related tasks on behalf of the {@link org.apache.fulcrum.security.BaseSecurityService}.
68   *
69   * The responsibilities of this class include loading data of an user from the
70   * storage and putting them into the {@link org.apache.fulcrum.security.entity.User} objects,
71   * saving those data to the permanent storage, and authenticating users.
72   *
73   * @author <a HREF="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
74   * @version $Id: UserManager.java,v 1.1 2004/11/12 10:26:14 epugh Exp $
75   */
76  public interface UserManager
77  {
78      /**
79       * Check whether a specified user's account exists.
80       *
81       * The login name is used for looking up the account.
82       *
83       * @param user The user to be checked.
84       * @return true if the specified account exists
85       * @throws DataBackendException if there was an error accessing the data backend.
86       */
87      boolean accountExists(User user)
88          throws DataBackendException;
89  
90      /**
91       * Check whether a specified user's account exists.
92       *
93       * The login name is used for looking up the account.
94       *
95       * @param userName The name of the user to be checked.
96       * @return true if the specified account exists
97       * @throws DataBackendException if there was an error accessing the data backend.
98       */
99      boolean accountExists(String   userName)
100         throws DataBackendException;
101 
102    /**
103      * Retrieve a user from persistent storage using username as the
104      * key.
105      *
106      * @param username the name of the user.
107      * @return an User object.
108      * @exception UnknownEntityException if the user's record does not
109      *            exist in the database.
110      * @exception DataBackendException if there is a problem accessing the
111      *            storage.
112      */
113     User retrieve(String   username)
114         throws UnknownEntityException, DataBackendException;
115 
116     /**
117      * Retrieve a set of users that meet the specified criteria.
118      *
119      * As the keys for the criteria, you should use the constants that
120      * are defined in {@link User} interface, plus the names
121      * of the custom attributes you added to your user representation
122      * in the data storage. Use verbatim names of the attributes -
123      * without table name prefix in case of DB implementation.
124      *
125      * @param criteria The criteria of selection.
126      * @return a List of users meeting the criteria.
127      * @throws DataBackendException if there is a problem accessing the
128      *         storage.
129      */
130     User[] retrieve(Criteria criteria)
131         throws DataBackendException;
132 
133     /**
134      * Retrieve a user from persistent storage using username as the
135      * key, and authenticate the user. The implementation may chose
136      * to authenticate to the server as the user whose data is being
137      * retrieved.
138      *
139      * @param username the name of the user.
140      * @param password the user supplied password.
141      * @return an User object.
142      * @exception PasswordMismatchException if the supplied password was
143      *            incorrect.
144      * @exception UnknownEntityException if the user's record does not
145      *            exist in the database.
146      * @exception DataBackendException if there is a problem accessing the
147      *            storage.
148      */
149     User retrieve(String   username, String   password)
150         throws PasswordMismatchException, UnknownEntityException,
151                DataBackendException;
152 
153     /**
154      * Save an User object to persistent storage. User's record is
155      * required to exist in the storage.
156      *
157      * @param user an User object to store.
158      * @exception UnknownEntityException if the user's record does not
159      *            exist in the database.
160      * @exception DataBackendException if there is a problem accessing the
161      *            storage.
162      */
163     void store(User user)
164         throws UnknownEntityException, DataBackendException;
165 
166     /**
167      * Authenticate an User with the specified password. If authentication
168      * is successful the method returns nothing. If there are any problems,
169      * exception was thrown.
170      *
171      * @param user an User object to authenticate.
172      * @param password the user supplied password.
173      * @exception PasswordMismatchException if the supplied password was
174      *            incorrect.
175      * @exception UnknownEntityException if the user's record does not
176      *            exist in the database.
177      * @exception DataBackendException if there is a problem accessing the
178      *            storage.
179      */
180     void authenticate(User user, String   password)
181         throws PasswordMismatchException, UnknownEntityException,
182                DataBackendException;
183 
184     /**
185      * Creates new user account with specified attributes.
186      *
187      * @param user the object describing account to be created.
188      * @param password The password to use for the object creation
189      *
190      * @throws DataBackendException if there was an error accessing the data backend.
191      * @throws EntityExistsException if the user account already exists.
192      */
193     void createAccount(User user, String   password)
194         throws EntityExistsException, DataBackendException;
195 
196     /**
197      * Removes an user account from the system.
198      *
199      * @param user the object describing the account to be removed.
200      * @throws DataBackendException if there was an error accessing the data backend.
201      * @throws UnknownEntityException if the user account is not present.
202      */
203     void removeAccount(User user)
204         throws UnknownEntityException, DataBackendException;
205     /**
206      * Change the password for an User.
207      *
208      * @param user an User to change password for.
209      * @param oldPassword the current password suplied by the user.
210      * @param newPassword the current password requested by the user.
211      * @exception PasswordMismatchException if the supplied password was
212      *            incorrect.
213      * @exception UnknownEntityException if the user's record does not
214      *            exist in the database.
215      * @exception DataBackendException if there is a problem accessing the
216      *            storage.
217      */
218     void changePassword(User user, String   oldPassword, String   newPassword)
219         throws PasswordMismatchException, UnknownEntityException,
220                DataBackendException;
221 
222     /**
223      * Forcibly sets new password for an User.
224      *
225      * This is supposed by the administrator to change the forgotten or
226      * compromised passwords. Certain implementatations of this feature
227      * would require administrative level access to the authenticating
228      * server / program.
229      *
230      * @param user an User to change password for.
231      * @param password the new password.
232      * @exception UnknownEntityException if the user's record does not
233      *            exist in the database.
234      * @exception DataBackendException if there is a problem accessing the
235      *            storage.
236      */
237     void forcePassword(User user, String   password)
238         throws UnknownEntityException, DataBackendException;
239 }
240
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags