001package org.apache.turbine.services.security;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.util.List;
023
024import org.apache.commons.configuration.Configuration;
025import org.apache.fulcrum.security.acl.AccessControlList;
026import org.apache.fulcrum.security.util.DataBackendException;
027import org.apache.fulcrum.security.util.EntityExistsException;
028import org.apache.fulcrum.security.util.PasswordMismatchException;
029import org.apache.fulcrum.security.util.UnknownEntityException;
030import org.apache.turbine.om.security.User;
031import org.apache.turbine.services.InitializationException;
032
033/**
034 * An UserManager performs {@link org.apache.turbine.om.security.User} objects
035 * related tasks on behalf of the
036 * {@link org.apache.turbine.services.security.DefaultSecurityService}.
037 *
038 * The responsibilities of this class include loading data of an user from the
039 * storage and putting them into the
040 * {@link org.apache.turbine.om.security.User} objects, saving those data
041 * to the permanent storage, and authenticating users.
042 *
043 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
044 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
045 * @version $Id: UserManager.java 1821129 2018-01-15 08:11:20Z gk $
046 */
047public interface UserManager
048{
049    /**
050     * Initializes the UserManager
051     *
052     * @param conf A Configuration object to init this Manager
053     *
054     * @throws InitializationException When something went wrong.
055     */
056    void init(Configuration conf)
057        throws InitializationException;
058
059    /**
060     * Check whether a specified user's account exists.
061     *
062     * The login name is used for looking up the account.
063     *
064     * @param user The user to be checked.
065     * @return true if the specified account exists
066     * @throws DataBackendException if there was an error accessing the data
067     *         backend.
068     */
069    boolean accountExists(User user)
070            throws DataBackendException;
071
072    /**
073     * Check whether a specified user's account exists.
074     *
075     * The login name is used for looking up the account.
076     *
077     * @param userName The name of the user to be checked.
078     * @return true if the specified account exists
079     * @throws DataBackendException if there was an error accessing the data
080     *         backend.
081     */
082    boolean accountExists(String userName)
083            throws DataBackendException;
084
085    /**
086     * Retrieve a user from persistent storage using username as the
087     * key.
088     *
089     * @param username the name of the user.
090     * @return an User object.
091     * @throws UnknownEntityException if the user's record does not
092     *         exist in the database.
093     * @throws DataBackendException if there is a problem accessing the
094     *         storage.
095     */
096    <U extends User> U retrieve(String username)
097            throws UnknownEntityException, DataBackendException;
098
099    /**
100     * Retrieve a list of users that meet the specified criteria.
101     *
102     * As the keys for the criteria, you should use the constants that
103     * are defined in {@link User} interface, plus the names
104     * of the custom attributes you added to your user representation
105     * in the data storage. Use verbatim names of the attributes -
106     * without table name prefix in case of DB implementation.
107     *
108     * @param criteria The criteria of selection.
109     * @return a List of users meeting the criteria.
110     * @throws DataBackendException if there is a problem accessing the
111     *         storage.
112     */
113    List<? extends User> retrieveList(Object criteria)
114        throws DataBackendException;
115
116    /**
117     * Retrieve a user from persistent storage using username as the
118     * key, and authenticate the user. The implementation may chose
119     * to authenticate to the server as the user whose data is being
120     * retrieved.
121     *
122     * @param username the name of the user.
123     * @param password the user supplied password.
124     * @return an User object.
125     * @throws PasswordMismatchException if the supplied password was incorrect.
126     * @throws UnknownEntityException if the user's record does not
127     *         exist in the database.
128     * @throws DataBackendException if there is a problem accessing the storage.
129     */
130    <U extends User> U retrieve(String username, String password)
131            throws PasswordMismatchException, UnknownEntityException,
132            DataBackendException;
133
134    /**
135     * Save an User object to persistent storage. User's record is
136     * required to exist in the storage.
137     *
138     * @param user an User object to store.
139     * @throws UnknownEntityException if the user's record does not
140     *         exist in the database.
141     * @throws DataBackendException if there is a problem accessing the storage.
142     */
143    void store(User user)
144            throws UnknownEntityException, DataBackendException;
145
146    /**
147     * Saves User data when the session is unbound. The user account is required
148     * to exist in the storage.
149     *
150     * LastLogin, AccessCounter, persistent pull tools, and any data stored
151     * in the permData hashtable that is not mapped to a column will be saved.
152     *
153     * @param user the user in the session
154     *
155     * @throws UnknownEntityException if the user's account does not
156     *            exist in the database.
157     * @throws DataBackendException if there is a problem accessing the
158     *            storage.
159     */
160    void saveOnSessionUnbind(User user)
161            throws UnknownEntityException, DataBackendException;
162
163    /**
164     * Authenticate an User with the specified password. If authentication
165     * is successful the method returns nothing. If there are any problems,
166     * exception was thrown.
167     *
168     * @param user an User object to authenticate.
169     * @param password the user supplied password.
170     * @throws PasswordMismatchException if the supplied password was incorrect.
171     * @throws UnknownEntityException if the user's record does not
172     *         exist in the database.
173     * @throws DataBackendException if there is a problem accessing the storage.
174     */
175    void authenticate(User user, String password)
176            throws PasswordMismatchException, UnknownEntityException,
177            DataBackendException;
178
179    /**
180     * Creates new user account with specified attributes.
181     *
182     * @param user the object describing account to be created.
183     * @param initialPassword password for the new user
184     * @throws DataBackendException if there was an error accessing the data
185     *         backend.
186     * @throws EntityExistsException if the user account already exists.
187     */
188    void createAccount(User user, String initialPassword)
189            throws UnknownEntityException, EntityExistsException, DataBackendException;
190
191    /**
192     * Removes an user account from the system.
193     *
194     * @param user the object describing the account to be removed.
195     * @throws DataBackendException if there was an error accessing the data
196     *         backend.
197     * @throws UnknownEntityException if the user account is not present.
198     */
199    void removeAccount(User user)
200            throws UnknownEntityException, DataBackendException;
201
202    /**
203     * Change the password for an User.
204     *
205     * @param user an User to change password for.
206     * @param oldPassword the current password suplied by the user.
207     * @param newPassword the current password requested by the user.
208     * @throws PasswordMismatchException if the supplied password was incorrect.
209     * @throws UnknownEntityException if the user's record does not
210     *         exist in the database.
211     * @throws DataBackendException if there is a problem accessing the storage.
212     */
213    void changePassword(User user, String oldPassword,
214                        String newPassword)
215            throws PasswordMismatchException, UnknownEntityException,
216            DataBackendException;
217
218    /**
219     * Forcibly sets new password for an User.
220     *
221     * This is supposed by the administrator to change the forgotten or
222     * compromised passwords. Certain implementatations of this feature
223     * would require administrative level access to the authenticating
224     * server / program.
225     *
226     * @param user an User to change password for.
227     * @param password the new password.
228     * @throws UnknownEntityException if the user's record does not
229     *            exist in the database.
230     * @throws DataBackendException if there is a problem accessing the storage.
231     */
232    void forcePassword(User user, String password)
233            throws UnknownEntityException, DataBackendException;
234
235    /**
236     * Constructs an User object to represent an anonymous user of the
237     * application.
238     *
239     * @return An anonymous Turbine User.
240     * @throws UnknownEntityException
241     *             if the anonymous User object couldn't be constructed.
242     */
243    <U extends User> U getAnonymousUser() throws UnknownEntityException;
244
245    /**
246     * Checks whether a passed user object matches the anonymous user pattern
247     * according to the configured user manager
248     *
249     * @param u a user object
250     *
251     * @return True if this is an anonymous user
252     *
253     */
254    boolean isAnonymousUser(User u);
255
256    /**
257     * Construct a blank User object.
258     *
259     * This method calls getUserClass, and then creates a new object using the
260     * default constructor.
261     *
262     * @return an object implementing User interface.
263     * @throws DataBackendException
264     *             if the object could not be instantiated.
265     */
266    <U extends User> U getUserInstance() throws DataBackendException;
267
268    /**
269     * Construct a blank User object.
270     *
271     * This method calls getUserClass, and then creates a new object using the
272     * default constructor.
273     *
274     * @param userName
275     *            The name of the user.
276     *
277     * @return an object implementing User interface.
278     * @throws DataBackendException
279     *             if the object could not be instantiated.
280     */
281    <U extends User> U getUserInstance(String userName) throws DataBackendException;
282
283    /**
284     * Return a Class object representing the system's chosen implementation of
285     * of ACL interface for the given user
286     *
287     * @param user the user
288     * @return systems's chosen implementation of ACL interface.
289     * @throws UnknownEntityException
290     *             if the implementation of ACL interface could not be
291     *             determined, or does not exist.
292     */
293    <A extends AccessControlList> A getACL(User user) throws UnknownEntityException;
294}