001: package 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:
022: import java.util.List;
023:
024: import org.apache.commons.configuration.Configuration;
025:
026: import org.apache.torque.util.Criteria;
027:
028: import org.apache.turbine.om.security.User;
029: import org.apache.turbine.services.InitializationException;
030: import org.apache.turbine.util.security.DataBackendException;
031: import org.apache.turbine.util.security.EntityExistsException;
032: import org.apache.turbine.util.security.PasswordMismatchException;
033: import org.apache.turbine.util.security.UnknownEntityException;
034:
035: /**
036: * An UserManager performs {@link org.apache.turbine.om.security.User} objects
037: * related tasks on behalf of the
038: * {@link org.apache.turbine.services.security.BaseSecurityService}.
039: *
040: * The responsibilities of this class include loading data of an user from the
041: * storage and putting them into the
042: * {@link org.apache.turbine.om.security.User} objects, saving those data
043: * to the permanent storage, and authenticating users.
044: *
045: * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
046: * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
047: * @version $Id: UserManager.java 534527 2007-05-02 16:10:59Z tv $
048: */
049: public interface UserManager {
050: /**
051: * Initializes the UserManager
052: *
053: * @param conf A Configuration object to init this Manager
054: *
055: * @throws InitializationException When something went wrong.
056: */
057: void init(Configuration conf) 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) throws DataBackendException;
070:
071: /**
072: * Check whether a specified user's account exists.
073: *
074: * The login name is used for looking up the account.
075: *
076: * @param userName The name of the user to be checked.
077: * @return true if the specified account exists
078: * @throws DataBackendException if there was an error accessing the data
079: * backend.
080: */
081: boolean accountExists(String userName) throws DataBackendException;
082:
083: /**
084: * Retrieve a user from persistent storage using username as the
085: * key.
086: *
087: * @param username the name of the user.
088: * @return an User object.
089: * @throws UnknownEntityException if the user's record does not
090: * exist in the database.
091: * @throws DataBackendException if there is a problem accessing the
092: * storage.
093: */
094: User retrieve(String username) throws UnknownEntityException,
095: DataBackendException;
096:
097: /**
098: * Retrieve a user from persistent storage using the primary key
099: *
100: * @param key The primary key object
101: * @return an User object.
102: * @throws UnknownEntityException if the user's record does not
103: * exist in the database.
104: * @throws DataBackendException if there is a problem accessing the
105: * storage.
106: */
107: User retrieveById(Object key) throws UnknownEntityException,
108: DataBackendException;
109:
110: /**
111: * Retrieve a set of users that meet the specified criteria.
112: *
113: * As the keys for the criteria, you should use the constants that
114: * are defined in {@link User} interface, plus the names
115: * of the custom attributes you added to your user representation
116: * in the data storage. Use verbatim names of the attributes -
117: * without table name prefix in case of DB implementation.
118: *
119: * @param criteria The criteria of selection.
120: * @return a List of users meeting the criteria.
121: * @throws DataBackendException if there is a problem accessing the
122: * storage.
123: * @deprecated Use retrieveList(Criteria crit)
124: */
125: User[] retrieve(Criteria criteria) throws DataBackendException;
126:
127: /**
128: * Retrieve a list of users that meet the specified criteria.
129: *
130: * As the keys for the criteria, you should use the constants that
131: * are defined in {@link User} interface, plus the names
132: * of the custom attributes you added to your user representation
133: * in the data storage. Use verbatim names of the attributes -
134: * without table name prefix in case of DB implementation.
135: *
136: * @param criteria The criteria of selection.
137: * @return a List of users meeting the criteria.
138: * @throws DataBackendException if there is a problem accessing the
139: * storage.
140: */
141: List retrieveList(Criteria criteria) throws DataBackendException;
142:
143: /**
144: * Retrieve a user from persistent storage using username as the
145: * key, and authenticate the user. The implementation may chose
146: * to authenticate to the server as the user whose data is being
147: * retrieved.
148: *
149: * @param username the name of the user.
150: * @param password the user supplied password.
151: * @return an User object.
152: * @throws PasswordMismatchException if the supplied password was incorrect.
153: * @throws UnknownEntityException if the user's record does not
154: * exist in the database.
155: * @throws DataBackendException if there is a problem accessing the storage.
156: */
157: User retrieve(String username, String password)
158: throws PasswordMismatchException, UnknownEntityException,
159: DataBackendException;
160:
161: /**
162: * Save an User object to persistent storage. User's record is
163: * required to exist in the storage.
164: *
165: * @param user an User object to store.
166: * @throws UnknownEntityException if the user's record does not
167: * exist in the database.
168: * @throws DataBackendException if there is a problem accessing the storage.
169: */
170: void store(User user) throws UnknownEntityException,
171: DataBackendException;
172:
173: /**
174: * Saves User data when the session is unbound. The user account is required
175: * to exist in the storage.
176: *
177: * LastLogin, AccessCounter, persistent pull tools, and any data stored
178: * in the permData hashtable that is not mapped to a column will be saved.
179: *
180: * @exception UnknownEntityException if the user's account does not
181: * exist in the database.
182: * @exception DataBackendException if there is a problem accessing the
183: * storage.
184: */
185: void saveOnSessionUnbind(User user) throws UnknownEntityException,
186: DataBackendException;
187:
188: /**
189: * Authenticate an User with the specified password. If authentication
190: * is successful the method returns nothing. If there are any problems,
191: * exception was thrown.
192: *
193: * @param user an User object to authenticate.
194: * @param password the user supplied password.
195: * @throws PasswordMismatchException if the supplied password was incorrect.
196: * @throws UnknownEntityException if the user's record does not
197: * exist in the database.
198: * @throws DataBackendException if there is a problem accessing the storage.
199: */
200: void authenticate(User user, String password)
201: throws PasswordMismatchException, UnknownEntityException,
202: DataBackendException;
203:
204: /**
205: * Creates new user account with specified attributes.
206: *
207: * @param user the object describing account to be created.
208: * @param initialPassword password for the new user
209: * @throws DataBackendException if there was an error accessing the data
210: * backend.
211: * @throws EntityExistsException if the user account already exists.
212: */
213: void createAccount(User user, String initialPassword)
214: throws EntityExistsException, DataBackendException;
215:
216: /**
217: * Removes an user account from the system.
218: *
219: * @param user the object describing the account to be removed.
220: * @throws DataBackendException if there was an error accessing the data
221: * backend.
222: * @throws UnknownEntityException if the user account is not present.
223: */
224: void removeAccount(User user) throws UnknownEntityException,
225: DataBackendException;
226:
227: /**
228: * Change the password for an User.
229: *
230: * @param user an User to change password for.
231: * @param oldPassword the current password suplied by the user.
232: * @param newPassword the current password requested by the user.
233: * @throws PasswordMismatchException if the supplied password was incorrect.
234: * @throws UnknownEntityException if the user's record does not
235: * exist in the database.
236: * @throws DataBackendException if there is a problem accessing the storage.
237: */
238: void changePassword(User user, String oldPassword,
239: String newPassword) throws PasswordMismatchException,
240: UnknownEntityException, DataBackendException;
241:
242: /**
243: * Forcibly sets new password for an User.
244: *
245: * This is supposed by the administrator to change the forgotten or
246: * compromised passwords. Certain implementatations of this feature
247: * would require administrative level access to the authenticating
248: * server / program.
249: *
250: * @param user an User to change password for.
251: * @param password the new password.
252: * @throws UnknownEntityException if the user's record does not
253: * exist in the database.
254: * @throws DataBackendException if there is a problem accessing the storage.
255: */
256: void forcePassword(User user, String password)
257: throws UnknownEntityException, DataBackendException;
258: }
|