KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sslexplorer > security > UserDatabase


1 /*
2  * SSL-Explorer
3  *
4  * Copyright (C) 2003-2006 3SP LTD. All Rights Reserved
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2 of
9  * the License, or (at your option) any later version.
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public
16  * License along with this program; if not, write to the Free Software
17  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18  */
19             
20 package com.sslexplorer.security;
21
22 import com.sslexplorer.core.CoreServlet;
23 import com.sslexplorer.core.Database;
24 import com.sslexplorer.policyframework.Principal;
25 import com.sslexplorer.realms.Realm;
26
27 /**
28  * <p>Implementations of this interface will provide basic user and role related
29  * services such as retrieving a user account, retrieving a role, authenticating
30  * a user etc.
31  *
32  * <p>Some implementations will now support account creation or password
33  * changing and as such should return appropriate values for {@link #supportsAccountCreation()}
34  * and {@link #supportsPasswordChange()}.
35  *
36  *
37  * @author Lee David Painter
38  */
39 public interface UserDatabase extends Database {
40
41     /**
42      * Get a readable description of the database.
43      *
44      * @return description
45      */
46     public String JavaDoc getDatabaseDescription();
47
48     /**
49      * Get if the database is currently 'open'.
50      *
51      * @return open
52      */
53     public boolean isOpen();
54
55     /**
56      * Authenticates the given username/password pair, returning the user object
57      * on success or <tt>null</tt> on failure.
58      *
59      * @param username
60      * @param password
61      * @return user object
62      * @throws UserDatabaseException
63      * @throws InvalidLoginCredentialsException
64      * @throws AccountLockedException
65      */
66     public User logon(String JavaDoc username, String JavaDoc password) throws UserDatabaseException, InvalidLoginCredentialsException,
67                     AccountLockedException;
68
69     /**
70      * Check the given username/password pair but do not actually logon.
71      * <tt>true</tt> is returned on success and <tt>false</tt> on failure.
72      *
73      * @param username
74      * @param password
75      * @return password ok
76      * @throws UserDatabaseException
77      * @throws InvalidLoginCredentialsException
78      */
79     public boolean checkPassword(String JavaDoc username, String JavaDoc password) throws UserDatabaseException, InvalidLoginCredentialsException;
80
81     /**
82      * Change your password. This method is used by a user to change their own passwords. It
83      * is recommended that implementations verify that the old password is correct.
84      *
85      * @param username username
86      * @param oldPassword
87      * @param password new password
88      * @param forcePasswordChangeAtLogon force password change at next logon
89      * @throws UserDatabaseException
90      * @throws InvalidLoginCredentialsException
91      */
92     public void changePassword(String JavaDoc username, String JavaDoc oldPassword, String JavaDoc password, boolean forcePasswordChangeAtLogon) throws UserDatabaseException,
93                     InvalidLoginCredentialsException;
94
95     /**
96      * Set a users password. This is used from the admin pages and requires admin user and password
97      * to complete.
98      * @param username
99      * @param password
100      * @param forcePasswordChangeAtLogon
101      * @param adminUser
102      * @param adminPassword
103      * @throws UserDatabaseException
104      * @throws InvalidLoginCredentialsException
105      */
106     public void setPassword(String JavaDoc username, String JavaDoc password, boolean forcePasswordChangeAtLogon, User adminUser, String JavaDoc adminPassword) throws UserDatabaseException, InvalidLoginCredentialsException;
107     
108     /**
109      * Get if this implementation supports changine of passwords
110      *
111      * @return password change supported
112      */
113     public boolean supportsPasswordChange();
114
115     /**
116      * Logout a user.
117      *
118      * @param user
119      */
120     public void logout(User user);
121
122     /**
123      * List all the users currently registered with the system. This is the list
124      * of all users rather than those that are granted access
125      *
126      * @param filter filter a filter to apply to the search
127      * @return an array of {@link User}s
128      * @throws Exception
129      */
130     public User[] listAllUsers(String JavaDoc filter) throws Exception JavaDoc;
131
132     /**
133      * List all the principals currently registered with the system
134      *
135      * @return an array of {@link Principal}s
136      * @throws Exception
137      */
138     public Principal[] listAvailablePrincipals() throws Exception JavaDoc;
139
140     /**
141      * Get the account details that belong to the given username.
142      *
143      * @param username
144      * @return user
145      * @throws UserNotFoundException if the user could not be found
146      * @throws Exception on all other errors
147      */
148     public User getAccount(String JavaDoc username) throws UserNotFoundException, Exception JavaDoc;
149
150     /**
151      * Identify whether this implementation supports the creation of user
152      * accounts.
153      *
154      * @return <tt>true</tt> if account creation is supported, otherwise
155      * <tt>false</tt>.
156      */
157     public boolean supportsAccountCreation();
158
159     /**
160      * Create a new {@link User}account. This method is optional and should
161      * only work when {@link #supportsAccountCreation()} returns <tt>true</tt>.
162      *
163      * @param username username
164      * @param password password
165      * @param email email address
166      * @param fullname full name
167      * @param roles array of roles
168      * @return user user object
169      * @throws Exception on any error
170      */
171     public User createAccount(String JavaDoc username, String JavaDoc password, String JavaDoc email, String JavaDoc fullname, Role[] roles) throws Exception JavaDoc;
172
173     /**
174      * Update the details of a {@link User}account. This method is optional and
175      * should only work when {@link #supportsAccountCreation()} returns
176      * <tt>true</tt>.#
177      *
178      * @param user
179      * @param email
180      * @param fullname
181      * @param roles
182      * @throws Exception
183      */
184     public void updateAccount(User user, String JavaDoc email, String JavaDoc fullname, Role[] roles) throws Exception JavaDoc;
185
186     /**
187      * Delete a {@link User} account. This method is optional and should only
188      * work when {@link #supportsAccountCreation()} returns <tt>true</tt>.
189      *
190      * @param user
191      * @throws Exception
192      * @throws UserNotFoundException
193      */
194     public void deleteAccount(User user) throws Exception JavaDoc, UserNotFoundException;
195
196
197     /**
198      * Get a single role given its name
199      *
200      * @param rolename role name
201      * @return role
202      * @throws Exception on any error
203      */
204     public Role getRole(String JavaDoc rolename) throws Exception JavaDoc;
205
206     /**
207      * List all available roles
208      *
209      * @param filter filter
210      * @return array of roles
211      * @throws Exception on any error
212      */
213     public Role[] listAllRoles(String JavaDoc filter) throws Exception JavaDoc;
214
215     /**
216      * Create a new role if the underlying database supports it.
217      *
218      * @param rolename role name
219      * @return role object
220      * @throws Exception on any error
221      */
222     public Role createRole(String JavaDoc rolename) throws Exception JavaDoc;
223
224     /**
225      * Delete a new role
226      *
227      * @param rolename role name
228      * @throws Exception on any error
229      */
230     public void deleteRole(String JavaDoc rolename) throws Exception JavaDoc;
231     
232     /**
233      * Get the a list of {@link com.sslexplorer.security.User}s that are in
234      * a specified role
235      *
236      * @param role role
237      * @return users in role
238      * @throws Exception on any error
239      */
240     public User[] getUsersInRole(Role role) throws Exception JavaDoc;
241     
242     /**
243      * @return Realm
244      */
245     public Realm getRealm();
246
247     /**
248      * @param controllingServlet
249      * @param realm
250      * @throws Exception
251      */
252     public void open(CoreServlet controllingServlet, Realm realm) throws Exception JavaDoc;
253 }
Popular Tags