Coverage Report

Coverage Report - org.apache.turbine.services.security.UserManager

Classes in this File

 package org.apache.turbine.services.security;
 
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
  * under the License.
  */
 
 import java.util.List;
 
 import org.apache.commons.configuration2.Configuration;
 import org.apache.fulcrum.security.acl.AccessControlList;
 import org.apache.fulcrum.security.util.DataBackendException;
 import org.apache.fulcrum.security.util.EntityExistsException;
 import org.apache.fulcrum.security.util.PasswordMismatchException;
 import org.apache.fulcrum.security.util.UnknownEntityException;
 import org.apache.turbine.om.security.User;
 import org.apache.turbine.services.InitializationException;
 
 /**
  * An UserManager performs {@link org.apache.turbine.om.security.User} objects
  * related tasks on behalf of the
  * {@link org.apache.turbine.services.security.DefaultSecurityService}.
  *
  * The responsibilities of this class include loading data of an user from the
  * storage and putting them into the
  * {@link org.apache.turbine.om.security.User} objects, saving those data
  * to the permanent storage, and authenticating users.
  *
  * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
  * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
  * @version $Id: UserManager.java 1850675 2019-01-07 18:48:42Z painter $
  */
 public interface UserManager
 {
     /**
      * Initializes the UserManager
      *
      * @param conf A Configuration object to init this Manager
      *
      * @throws InitializationException When something went wrong.
      */
     void init(Configuration conf)
         throws InitializationException;
 
     /**
      * Check whether a specified user's account exists.
      *
      * The login name is used for looking up the account.
      *
      * @param user The user to be checked.
      * @return true if the specified account exists
      * @throws DataBackendException if there was an error accessing the data
      *         backend.
      */
     boolean accountExists(User user)
             throws DataBackendException;
 
     /**
      * Check whether a specified user's account exists.
      *
      * The login name is used for looking up the account.
      *
      * @param userName The name of the user to be checked.
      * @return true if the specified account exists
      * @throws DataBackendException if there was an error accessing the data
      *         backend.
      */
     boolean accountExists(String userName)
             throws DataBackendException;
 
     /**
      * Retrieve a user from persistent storage using username as the
      * key.
      *
      * @param <U> user class
      * @param username the name of the user.
      * @return an User object.
      * @throws UnknownEntityException if the user's record does not
      *         exist in the database.
      * @throws DataBackendException if there is a problem accessing the
      *         storage.
      */
     <U extends User> U retrieve(String username)
             throws UnknownEntityException, DataBackendException;
 
     /**
      * Retrieve a list of users that meet the specified criteria.
      *
      * As the keys for the criteria, you should use the constants that
      * are defined in {@link User} interface, plus the names
      * of the custom attributes you added to your user representation
      * in the data storage. Use verbatim names of the attributes -
      * without table name prefix in case of DB implementation.
      *
      * @param criteria The criteria of selection.
      * @return a List of users meeting the criteria.
      * @throws DataBackendException if there is a problem accessing the
      *         storage.
      */
     List<? extends User> retrieveList(Object criteria)
         throws DataBackendException;
 
     /**
      * Retrieve a user from persistent storage using username as the
      * key, and authenticate the user. The implementation may chose
      * to authenticate to the server as the user whose data is being
      * retrieved.
      *
      * @param <U> user class
      * @param username the name of the user.
      * @param password the user supplied password.
      * @return an User object.
      * @throws PasswordMismatchException if the supplied password was incorrect.
      * @throws UnknownEntityException if the user's record does not
      *         exist in the database.
      * @throws DataBackendException if there is a problem accessing the storage.
      */
     <U extends User> U retrieve(String username, String password)
             throws PasswordMismatchException, UnknownEntityException,
             DataBackendException;
 
     /**
      * Save an User object to persistent storage. User's record is
      * required to exist in the storage.
      *
      * @param user an User object to store.
      * @throws UnknownEntityException if the user's record does not
      *         exist in the database.
      * @throws DataBackendException if there is a problem accessing the storage.
      */
     void store(User user)
             throws UnknownEntityException, DataBackendException;
 
     /**
      * Saves User data when the session is unbound. The user account is required
      * to exist in the storage.
      *
      * LastLogin, AccessCounter, persistent pull tools, and any data stored
      * in the permData hashtable that is not mapped to a column will be saved.
      *
      * @param user the user in the session
      *
      * @throws UnknownEntityException if the user's account does not
      *            exist in the database.
      * @throws DataBackendException if there is a problem accessing the
      *            storage.
      */
     void saveOnSessionUnbind(User user)
             throws UnknownEntityException, DataBackendException;
 
     /**
      * Authenticate an User with the specified password. If authentication
      * is successful the method returns nothing. If there are any problems,
      * exception was thrown.
      *
      * @param user an User object to authenticate.
      * @param password the user supplied password.
      * @throws PasswordMismatchException if the supplied password was incorrect.
      * @throws UnknownEntityException if the user's record does not
      *         exist in the database.
      * @throws DataBackendException if there is a problem accessing the storage.
      */
     void authenticate(User user, String password)
             throws PasswordMismatchException, UnknownEntityException,
             DataBackendException;
 
     /**
      * Creates new user account with specified attributes.
      *
      * @param user the object describing account to be created.
      * @param initialPassword password for the new user
      * @throws UnknownEntityException if the user account cannot be created.
      * @throws DataBackendException if there was an error accessing the data
      *         backend.
      * @throws EntityExistsException if the user account already exists.
      */
     void createAccount(User user, String initialPassword)
             throws UnknownEntityException, EntityExistsException, DataBackendException;
 
     /**
      * Removes an user account from the system.
      *
      * @param user the object describing the account to be removed.
      * @throws DataBackendException if there was an error accessing the data
      *         backend.
      * @throws UnknownEntityException if the user account is not present.
      */
     void removeAccount(User user)
             throws UnknownEntityException, DataBackendException;
 
     /**
      * Change the password for an User.
      *
      * @param user an User to change password for.
      * @param oldPassword the current password suplied by the user.
      * @param newPassword the current password requested by the user.
      * @throws PasswordMismatchException if the supplied password was incorrect.
      * @throws UnknownEntityException if the user's record does not
      *         exist in the database.
      * @throws DataBackendException if there is a problem accessing the storage.
      */
     void changePassword(User user, String oldPassword,
                         String newPassword)
             throws PasswordMismatchException, UnknownEntityException,
             DataBackendException;
 
     /**
      * Forcibly sets new password for an User.
      *
      * This is supposed by the administrator to change the forgotten or
      * compromised passwords. Certain implementatations of this feature
      * would require administrative level access to the authenticating
      * server / program.
      *
      * @param user an User to change password for.
      * @param password the new password.
      * @throws UnknownEntityException if the user's record does not
      *            exist in the database.
      * @throws DataBackendException if there is a problem accessing the storage.
      */
     void forcePassword(User user, String password)
             throws UnknownEntityException, DataBackendException;
 
     /**
      * Constructs an User object to represent an anonymous user of the
      * application.
      *
      * @param <U> user class
      * @return An anonymous Turbine User.
      * @throws UnknownEntityException
      *             if the anonymous User object couldn't be constructed.
      */
     <U extends User> U getAnonymousUser() throws UnknownEntityException;
 
     /**
      * Checks whether a passed user object matches the anonymous user pattern
      * according to the configured user manager
      *
      * @param u a user object
      *
      * @return True if this is an anonymous user
      *
      */
     boolean isAnonymousUser(User u);
 
     /**
      * Construct a blank User object.
      *
      * This method calls getUserClass, and then creates a new object using the
      * default constructor.
      *
      * @param <U> user class
      * @return an object implementing User interface.
      * @throws DataBackendException
      *             if the object could not be instantiated.
      */
     <U extends User> U getUserInstance() throws DataBackendException;
 
     /**
      * Construct a blank User object.
      *
      * This method calls getUserClass, and then creates a new object using the
      * default constructor.
      *
      * @param <U> user class
      * @param userName
      *            The name of the user.
      *
      * @return an object implementing User interface.
      * @throws DataBackendException
      *             if the object could not be instantiated.
      */
     <U extends User> U getUserInstance(String userName) throws DataBackendException;
 
     /**
      * Return a Class object representing the system's chosen implementation of
      * of ACL interface for the given user
      * 
      * @param <A> ACL class
      * @param user the user
      * @return systems's chosen implementation of ACL interface.
      * @throws UnknownEntityException
      *             if the implementation of ACL interface could not be
      *             determined, or does not exist.
      */
     <A extends AccessControlList> A getACL(User user) throws UnknownEntityException;
 }

1		package org.apache.turbine.services.security;
2
3		/*
4		* Licensed to the Apache Software Foundation (ASF) under one
5		* or more contributor license agreements. See the NOTICE file
6		* distributed with this work for additional information
7		* regarding copyright ownership. The ASF licenses this file
8		* to you under the Apache License, Version 2.0 (the
9		* "License"); you may not use this file except in compliance
10		* with the License. You may obtain a copy of the License at
11		*
12		* http://www.apache.org/licenses/LICENSE-2.0
13		*
14		* Unless required by applicable law or agreed to in writing,
15		* software distributed under the License is distributed on an
16		* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17		* KIND, either express or implied. See the License for the
18		* specific language governing permissions and limitations
19		* under the License.
20		*/
21
22		import java.util.List;
23
24		import org.apache.commons.configuration2.Configuration;
25		import org.apache.fulcrum.security.acl.AccessControlList;
26		import org.apache.fulcrum.security.util.DataBackendException;
27		import org.apache.fulcrum.security.util.EntityExistsException;
28		import org.apache.fulcrum.security.util.PasswordMismatchException;
29		import org.apache.fulcrum.security.util.UnknownEntityException;
30		import org.apache.turbine.om.security.User;
31		import org.apache.turbine.services.InitializationException;
32
33		/**
34		* An UserManager performs {@link org.apache.turbine.om.security.User} objects
35		* related tasks on behalf of the
36		* {@link org.apache.turbine.services.security.DefaultSecurityService}.
37		*
38		* The responsibilities of this class include loading data of an user from the
39		* storage and putting them into the
40		* {@link org.apache.turbine.om.security.User} objects, saving those data
41		* to the permanent storage, and authenticating users.
42		*
43		* @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
44		* @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
45		* @version $Id: UserManager.java 1850675 2019-01-07 18:48:42Z painter $
46		*/
47		public interface UserManager
48		{
49		/**
50		* Initializes the UserManager
51		*
52		* @param conf A Configuration object to init this Manager
53		*
54		* @throws InitializationException When something went wrong.
55		*/
56		void init(Configuration conf)
57		throws InitializationException;
58
59		/**
60		* Check whether a specified user's account exists.
61		*
62		* The login name is used for looking up the account.
63		*
64		* @param user The user to be checked.
65		* @return true if the specified account exists
66		* @throws DataBackendException if there was an error accessing the data
67		* backend.
68		*/
69		boolean accountExists(User user)
70		throws DataBackendException;
71
72		/**
73		* Check whether a specified user's account exists.
74		*
75		* The login name is used for looking up the account.
76		*
77		* @param userName The name of the user to be checked.
78		* @return true if the specified account exists
79		* @throws DataBackendException if there was an error accessing the data
80		* backend.
81		*/
82		boolean accountExists(String userName)
83		throws DataBackendException;
84
85		/**
86		* Retrieve a user from persistent storage using username as the
87		* key.
88		*
89		* @param <U> user class
90		* @param username the name of the user.
91		* @return an User object.
92		* @throws UnknownEntityException if the user's record does not
93		* exist in the database.
94		* @throws DataBackendException if there is a problem accessing the
95		* storage.
96		*/
97		<U extends User> U retrieve(String username)
98		throws UnknownEntityException, DataBackendException;
99
100		/**
101		* Retrieve a list of users that meet the specified criteria.
102		*
103		* As the keys for the criteria, you should use the constants that
104		* are defined in {@link User} interface, plus the names
105		* of the custom attributes you added to your user representation
106		* in the data storage. Use verbatim names of the attributes -
107		* without table name prefix in case of DB implementation.
108		*
109		* @param criteria The criteria of selection.
110		* @return a List of users meeting the criteria.
111		* @throws DataBackendException if there is a problem accessing the
112		* storage.
113		*/
114		List<? extends User> retrieveList(Object criteria)
115		throws DataBackendException;
116
117		/**
118		* Retrieve a user from persistent storage using username as the
119		* key, and authenticate the user. The implementation may chose
120		* to authenticate to the server as the user whose data is being
121		* retrieved.
122		*
123		* @param <U> user class
124		* @param username the name of the user.
125		* @param password the user supplied password.
126		* @return an User object.
127		* @throws PasswordMismatchException if the supplied password was incorrect.
128		* @throws UnknownEntityException if the user's record does not
129		* exist in the database.
130		* @throws DataBackendException if there is a problem accessing the storage.
131		*/
132		<U extends User> U retrieve(String username, String password)
133		throws PasswordMismatchException, UnknownEntityException,
134		DataBackendException;
135
136		/**
137		* Save an User object to persistent storage. User's record is
138		* required to exist in the storage.
139		*
140		* @param user an User object to store.
141		* @throws UnknownEntityException if the user's record does not
142		* exist in the database.
143		* @throws DataBackendException if there is a problem accessing the storage.
144		*/
145		void store(User user)
146		throws UnknownEntityException, DataBackendException;
147
148		/**
149		* Saves User data when the session is unbound. The user account is required
150		* to exist in the storage.
151		*
152		* LastLogin, AccessCounter, persistent pull tools, and any data stored
153		* in the permData hashtable that is not mapped to a column will be saved.
154		*
155		* @param user the user in the session
156		*
157		* @throws UnknownEntityException if the user's account does not
158		* exist in the database.
159		* @throws DataBackendException if there is a problem accessing the
160		* storage.
161		*/
162		void saveOnSessionUnbind(User user)
163		throws UnknownEntityException, DataBackendException;
164
165		/**
166		* Authenticate an User with the specified password. If authentication
167		* is successful the method returns nothing. If there are any problems,
168		* exception was thrown.
169		*
170		* @param user an User object to authenticate.
171		* @param password the user supplied password.
172		* @throws PasswordMismatchException if the supplied password was incorrect.
173		* @throws UnknownEntityException if the user's record does not
174		* exist in the database.
175		* @throws DataBackendException if there is a problem accessing the storage.
176		*/
177		void authenticate(User user, String password)
178		throws PasswordMismatchException, UnknownEntityException,
179		DataBackendException;
180
181		/**
182		* Creates new user account with specified attributes.
183		*
184		* @param user the object describing account to be created.
185		* @param initialPassword password for the new user
186		* @throws UnknownEntityException if the user account cannot be created.
187		* @throws DataBackendException if there was an error accessing the data
188		* backend.
189		* @throws EntityExistsException if the user account already exists.
190		*/
191		void createAccount(User user, String initialPassword)
192		throws UnknownEntityException, EntityExistsException, DataBackendException;
193
194		/**
195		* Removes an user account from the system.
196		*
197		* @param user the object describing the account to be removed.
198		* @throws DataBackendException if there was an error accessing the data
199		* backend.
200		* @throws UnknownEntityException if the user account is not present.
201		*/
202		void removeAccount(User user)
203		throws UnknownEntityException, DataBackendException;
204
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		* @throws PasswordMismatchException if the supplied password was incorrect.
212		* @throws UnknownEntityException if the user's record does not
213		* exist in the database.
214		* @throws DataBackendException if there is a problem accessing the storage.
215		*/
216		void changePassword(User user, String oldPassword,
217		String newPassword)
218		throws PasswordMismatchException, UnknownEntityException,
219		DataBackendException;
220
221		/**
222		* Forcibly sets new password for an User.
223		*
224		* This is supposed by the administrator to change the forgotten or
225		* compromised passwords. Certain implementatations of this feature
226		* would require administrative level access to the authenticating
227		* server / program.
228		*
229		* @param user an User to change password for.
230		* @param password the new password.
231		* @throws UnknownEntityException if the user's record does not
232		* exist in the database.
233		* @throws DataBackendException if there is a problem accessing the storage.
234		*/
235		void forcePassword(User user, String password)
236		throws UnknownEntityException, DataBackendException;
237
238		/**
239		* Constructs an User object to represent an anonymous user of the
240		* application.
241		*
242		* @param <U> user class
243		* @return An anonymous Turbine User.
244		* @throws UnknownEntityException
245		* if the anonymous User object couldn't be constructed.
246		*/
247		<U extends User> U getAnonymousUser() throws UnknownEntityException;
248
249		/**
250		* Checks whether a passed user object matches the anonymous user pattern
251		* according to the configured user manager
252		*
253		* @param u a user object
254		*
255		* @return True if this is an anonymous user
256		*
257		*/
258		boolean isAnonymousUser(User u);
259
260		/**
261		* Construct a blank User object.
262		*
263		* This method calls getUserClass, and then creates a new object using the
264		* default constructor.
265		*
266		* @param <U> user class
267		* @return an object implementing User interface.
268		* @throws DataBackendException
269		* if the object could not be instantiated.
270		*/
271		<U extends User> U getUserInstance() throws DataBackendException;
272
273		/**
274		* Construct a blank User object.
275		*
276		* This method calls getUserClass, and then creates a new object using the
277		* default constructor.
278		*
279		* @param <U> user class
280		* @param userName
281		* The name of the user.
282		*
283		* @return an object implementing User interface.
284		* @throws DataBackendException
285		* if the object could not be instantiated.
286		*/
287		<U extends User> U getUserInstance(String userName) throws DataBackendException;
288
289		/**
290		* Return a Class object representing the system's chosen implementation of
291		* of ACL interface for the given user
292		*
293		* @param <A> ACL class
294		* @param user the user
295		* @return systems's chosen implementation of ACL interface.
296		* @throws UnknownEntityException
297		* if the implementation of ACL interface could not be
298		* determined, or does not exist.
299		*/
300		<A extends AccessControlList> A getACL(User user) throws UnknownEntityException;
301		}