View Javadoc

1   /* 
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.jetspeed.security;
18  
19  import java.sql.Date;
20  import java.util.Collection;
21  import java.util.Iterator;
22  
23  /***
24   * <p>
25   * Describes the interface for managing users and provides access to the
26   * {@link User}.
27   * </p>
28   * 
29   * @author <a href="mailto:dlestrat@apache.org">David Le Strat </a>
30   */
31  public interface UserManager
32  {
33      /***
34       * @return the name of the anonymous user
35       */
36      String getAnonymousUser();
37      
38      /***
39       * <p>
40       * Authenticate a user.
41       * </p>
42       * 
43       * @param username The user name.
44       * @param password The user password.
45       * @return Whether or not a user is authenticated.
46       */
47      boolean authenticate(String username, String password);
48  
49      /***
50       * <p>
51       * Add a new user provided a username and password.
52       * </p>
53       * 
54       * @param username The user name.
55       * @param password The password.
56       * @throws Throws a security exception.
57       */
58      void addUser(String username, String password) throws SecurityException;
59  
60      /***
61       * <p>
62       * Add a new user provided a username and password in the specified authentication
63       * provider store.
64       * </p>
65       * 
66       * @param username The user name.
67       * @param password The password.
68       * @param atnProviderName The authentication provider name.
69       * @throws Throws a security exception.
70       */
71      void addUser(String username, String password, String atnProviderName) throws SecurityException;
72  
73      
74      /***
75       * <p>
76       * Import a new user with username and password and allow to bypass the enconding algorithm
77       * </p>
78       * 
79       * @param username The user name.
80       * @param password The password.
81       * @param passThrough If true the provided password will not be validated/encoded
82       * @throws Throws a security exception.
83       */
84      void importUser(String username, String password, boolean passThrough) throws SecurityException;
85  
86      /***
87       * <p>
88       * Import a new user with username and password in the specified authentication
89       * provider store and allow to bypass the enconding algorithm
90       * </p>
91       * 
92       * @param username The user name.
93       * @param password The password.
94       * @param atnProviderName The authentication provider name.
95       * @param passThrough If true the provided password will not be validated/encoded
96       * @throws Throws a security exception.
97       */
98      void importUser(String username, String password, String atnProviderName, boolean passThrough) throws SecurityException;
99  
100     
101     /***
102      * <p>
103      * Remove a user. If there is a {@link java.util.prefs.Preferences}node for
104      * profile properties associated to this user, it will be removed as well.
105      * </p>
106      * <p>
107      * {@link java.security.Permission}for this user will be removed as well.
108      * </p>
109      * 
110      * @param username The user name.
111      * @throws Throws a security exception.
112      */
113     void removeUser(String username) throws SecurityException;
114 
115     /***
116      * <p>
117      * Whether or not a user exists.
118      * </p>
119      * 
120      * @param username The user name.
121      * @return Whether or not a user exists.
122      */
123     boolean userExists(String username);
124 
125     /***
126      * <p>
127      * Get a {@link User}for a given username.
128      * </p>
129      * 
130      * @param username The username.
131      * @return The {@link User}.
132      * @throws Throws a security exception if the user cannot be found.
133      */
134     User getUser(String username) throws SecurityException;
135 
136     /***
137      * <p>
138      * An iterator of {@link User}finding users matching the corresponding
139      * filter criteria.
140      * </p>
141      * TODO Complete filter implementation.
142      * 
143      * @param filter The filter used to retrieve matching users.
144      * @return The Iterator of {@link User}.
145      */
146     Iterator getUsers(String filter) throws SecurityException;
147 
148     /***
149      * <p>
150      * An iterator of user names, finding users matching the corresponding
151      * filter criteria.
152      * </p>
153      * TODO Complete filter implementation.
154      * 
155      * @param filter The filter used to retrieve matching users.
156      * @return The Iterator of {@link User}.
157      */
158     Iterator getUserNames(String filter) throws SecurityException;
159 
160     /***
161      * <p>
162      * A collection of {@link User}for all the users in a specific role.
163      * </p>
164      * 
165      * @param roleFullPathName The role name full path (e.g.
166      *            theRoleName.theRoleNameChild).
167      * @return A Collection of {@link User}.
168      * @throws Throws a security exception if the role does not exist.
169      */
170     Collection getUsersInRole(String roleFullPathName) throws SecurityException;
171     
172     /***
173      * <p>A collection of {@link User} for a specific group.</p>
174      * @param groupFullPathName The group name full path
175      *                          (e.g. theGroupName.theGroupChildName).
176      * @return A collection of {@link User}.
177      * @throws Throws security exception if the group does not exist.
178      */
179     Collection getUsersInGroup(String groupFullPathName) throws SecurityException;
180     
181     /***
182      * <p>
183      * Set the user password.
184      * </p>
185      * 
186      * @param username The user name.
187      * @param oldPassword The old password.
188      * @param newPassword The new password.
189      * @throws Throws a security exception.
190      */
191     void setPassword(String username, String oldPassword, String newPassword) throws SecurityException;
192 
193     /***
194      * <p>
195      * Set the update required state of the user password credential.
196      * </p>
197      * 
198      * @param userName The user name.
199      * @param updateRequired The update required state.
200      * @throws Throws a security exception.
201      */
202     void setPasswordUpdateRequired(String userName, boolean updateRequired) throws SecurityException;
203 
204     /***
205      * <p>
206      * Set the enabled state of the user password credential.
207      * </p>
208      * 
209      * @param userName The user name.
210      * @param enabled The enabled state.
211      * @throws Throws a security exception.
212      */
213     void setPasswordEnabled(String userName, boolean enabled) throws SecurityException;
214 
215     /***
216      * Enable or disable a user.
217      * @param userName The user name
218      * @param enabled enabled flag for the user
219      */
220     void setUserEnabled(String userName, boolean enabled) throws SecurityException;
221 
222     /***
223      * <p>
224      * Set the expiration date and the expired flag of the password credential.</p>
225      * <p>
226      * If a date equal or before the current date is provided, the expired flag will be set to true,
227      * otherwise to false.</p>
228      * 
229      * @param userName The user name.
230      * @param expirationDate The expiration date to set.
231      * @throws Throws a security exception.
232      */
233     void setPasswordExpiration(String userName, Date expirationDate) throws SecurityException;
234 }