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.configuration.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 1821129 2018-01-15 08:11:20Z gk $
  */
 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 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 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 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.
      *
      * @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.
      *
      * @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 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 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.configuration.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 1821129 2018-01-15 08:11:20Z gk $
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 username the name of the user.
90		* @return an User object.
91		* @throws UnknownEntityException if the user's record does not
92		* exist in the database.
93		* @throws DataBackendException if there is a problem accessing the
94		* storage.
95		*/
96		<U extends User> U retrieve(String username)
97		throws UnknownEntityException, DataBackendException;
98
99		/**
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		}