UserManager


1   /*
2    * The contents of this file are subject to the Sapient Public License
3    * Version 1.0 (the "License"); you may not use this file except in compliance
4    * with the License. You may obtain a copy of the License at
5    * http://carbon.sf.net/License.html.
6    *
7    * Software distributed under the License is distributed on an "AS IS" basis,
8    * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
9    * the specific language governing rights and limitations under the License.
10   *
11   * The Original Code is The Carbon Component Framework.
12   *
13   * The Initial Developer of the Original Code is Sapient Corporation
14   *
15   * Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
16   */
17  
18  package org.sape.carbon.services.security.management;
19  
20  import java.security.Principal  ;
21  import java.security.acl.Group  ;
22  import java.util.Map  ;
23  import java.util.Set  ;
24  
25  import org.sape.carbon.core.component.FunctionalInterface;
26  
27  /**
28   * Service to provide managing of a user store for an application.
29   *
30   * <p>
31   * This service sits on top of the objects used in the java.security
32   * packages that are used to represent users, group and access
33   * permissions.  It is not meant to provide authentication or
34   * authorization services which are defined as a part of J2EE and JAAS.
35   * </p>
36   *
37   * <p>
38   * This service provides an abstract view into a store of users and
39   * groups.  It provides a means add/remove/locate the various types of
40   * objects.
41   * </p>
42   *
43   * @author $Author: dvoet $ $Date: 2003/10/28 19:02:00 $
44   * @version $Revision: 1.7 $
45   *
46   * @stereotype interface
47   * @since carbon 1.2
48   */
49  public interface UserManager extends FunctionalInterface {
50      /**
51       * Creates a user and adds it to the store.
52       *
53       * <p>
54       * The user is specificied by the given name and will be validated by
55       * auth services using the given credential. The specific
56       * implementation of the credential may differ depending on the user
57       * store.
58       * </p>
59       *
60       * <p>
61       * Note that the credential is accepted as an object.  The most common
62       * credential type will be a String or other password object, but in
63       * some cases user stores may use a Certificate for the user's
64       * credential.
65       * </p>
66       *
67       * @param userName The username identifying the user inside the user
68       *        store.
69       * @param credential The credential object a user needs to prove they
70       *        can be referenced by the principal.
71       *
72       * @return A principal object representing the user just added to the
73       *         user store.
74       *
75       * @throws DuplicatePrincipalException indicates a user with the given
76       *         principal already exists in this user store.
77       */
78      Principal   createUser(String   userName, Map   userInfo)
79          throws DuplicatePrincipalException, SecurityManagementDataStoreException;
80  
81      /**
82       * Authenticates a user against a given credential.
83       *
84       * <p>
85       * This method will check the validity of a credential for a given
86       * user and return if the user is valid to log in of if some other
87       * status prevents them.
88       * </p>
89       *
90       * <p>
91       * This method does not provide business specific reasons why a user
92       * may be unable to log in (user does not exist, incorrect password,
93       * locked out, etc.). Projects must write project specific checks for
94       * business conditions preventing a user from logging in.
95       * </p>
96       *
97       * @param userName The username identifying the user inside the user
98       *        store.
99       * @param credential The credential object a user needs to prove they
100      *        can be referenced by the principal.
101      *
102      * @return if this is the valid credential for the given user
103      *
104      * @throws UnsupportedOperationException indicates this user manager
105      *         does not handle authentication of the credentials.
106      */
107     boolean authenticate(String   userName, Object   credential)
108         throws SecurityManagementDataStoreException;
109 
110     /**
111      * Removes a user from the store.  The user is specified by the given
112      * principal.
113      *
114      * @param user The principal identifying the user inside the user
115      *        store.
116      *
117      * @throws UnknownPrincipalException indicates the principal does not
118      *         exist in the user store.
119      */
120     void removeUser(Principal   user)
121         throws UnknownPrincipalException, SecurityManagementDataStoreException;
122 
123     /**
124      * Assigns a new credential to the principal in the user store.
125      *
126      * @param user The principal identifying the user inside the user
127      *        store.
128      * @param credential The credential object a user needs to prove they
129      *        can be referenced by the principal.
130      *
131      * @throws UnknownPrincipalException indicates the principal does not
132      *         exist in the user store.
133      */
134     void updateCredential(Principal   user, Object   credential)
135         throws UnknownPrincipalException, SecurityManagementDataStoreException;
136 
137     /**
138      * Adds a new group to the user store.
139      *
140      * @param groupName the name of the new group to add to the user store.
141      *
142      * @return A Group object representing the newly created group.
143      *
144      * @throws DuplicateGroupException indicates a group with the
145      *         given principal already exists in this user store.
146      */
147     Group   createGroup(String   groupName)
148         throws DuplicateGroupException, SecurityManagementDataStoreException;
149 
150     /**
151      * Removes a group from the store..
152      *
153      * @param group The group to remove from the user store.
154      *
155      * @throws UnknownGroupException indicates the group does not exist in
156      *         the user store.
157      */
158     void removeGroup(Group   group)
159         throws UnknownGroupException, SecurityManagementDataStoreException;
160 
161     /**
162      * Retreives a Principal object indentified the by the given name.
163      *
164      * @param userName the name of the principal held in the Principal
165      *        object.
166      *
167      * @return the principal object uniquely identified by the give name.
168      *         <code>null</code> is returned if there is no Principal
169      *         matching the name given.
170      */
171     Principal   retreiveUser(String   userName)
172         throws SecurityManagementDataStoreException;
173 
174     /**
175      * Retreives a Group object indentified the by the given name.
176      *
177      * @param groupName the name of the group held in the Group object.
178      *
179      * @return the Group object uniquely identified by the give name.
180      *         <code>null</code> is returned if there is no Group
181      *         matching the name given.
182      */
183     Group   retreiveGroup(String   groupName)
184         throws SecurityManagementDataStoreException;
185 
186     /**
187      * Retreives the groups contain this particular principal.
188      * <p>
189      * This method is not required to return all levels of
190      * the group heirarchy the principal belongs to.  At least the
191      * first level of containing groups will be returned and
192      * subgroups may be returned.  Check the documentation on
193      * the specific implementation to determine what will be returned.
194      * </p>
195      *
196      * @param principal principal to retrieve the groups for
197      * @return groups which the principals is a member of
198      * @throws UnknownPrincipalException indicates the user does not
199      *         exist in the datastore
200      */
201     Set   retreiveGroups(Principal   principal)
202         throws UnknownPrincipalException, SecurityManagementDataStoreException;
203 
204     /**
205      * Adds a principal to a group.  This method can be used on any object
206      * implementing principal.  THis includes a user or group object.
207      *
208      * <p>
209      * It should be noted that the group object also contains a method on
210      * it to add a user to the group.  In a client-server environment
211      * Group objects are often considered Value Objects that have an
212      * empty or non-functional implementation of maintanence methods.
213      * Therefore it is prefered for a J2EE application to makeuse of this
214      * method passing in the group object.
215      * </p>
216      *
217      * @param principal the principal to add to a group
218      * @param group the group to add the principal to
219      *
220      * @return <code>true</code> if the user store changed as a result of
221      *         the call
222      *
223      * @throws UnknownPrincipalException indicates the principalName given
224      *         does not represent a user
225      * @throws UnknownGroupException indicates the groupName given does
226      *         not represent a group
227      */
228     boolean addPrincipalToGroup(Principal   principal, Group   group)
229         throws
230             UnknownPrincipalException,
231             UnknownGroupException,
232             SecurityManagementDataStoreException;
233 
234     /**
235      * Removes a principal from a group.  This method can be used on any
236      * object implementing principal.  THis includes a user or group
237      * object.
238      *
239      * <p>
240      * It should be noted that the group object also contains a method to
241      * remove a user to the group.  In a client-server environment Group
242      * objects are often considered Value Objects that have an empty or
243      * non-functional implementation of maintanence methods. Therefore it
244      * is prefered for a J2EE application to makeuse of this method
245      * passing in the group object.
246      * </p>
247      *
248      * @param principal the principal to remove from a group
249      * @param group the group to remove the principal from
250      *
251      * @return <code>true</code> if the user store changed as a result of
252      *         the call
253      *
254      * @throws UnknownPrincipalException indicates the principalName given
255      *         does not represent a user
256      * @throws UnknownGroupException indicates the groupName given does
257      *         not represent a group
258      */
259     boolean removePrincipalFromGroup(Principal   principal, Group   group)
260         throws
261             UnknownPrincipalException,
262             UnknownGroupException,
263             SecurityManagementDataStoreException;
264 
265     /**
266      * Retreives all unique names of users from the store as a Set of
267      * Strings.
268      *
269      * @return All unique user names as a Set of Strings.  If there are no
270      *         users in the system and empty Set will be returned.
271      */
272     Set   retreiveAllUserNames() throws SecurityManagementDataStoreException;
273 
274     /**
275      * Retreives all unique names of groups from the store as a Set of
276      * Strings.
277      *
278      * @return All unique group names as a Set of Strings.  If there are
279      *         no group in the system and empty Set will be returned.
280      */
281     Set   retreiveAllGroupNames() throws SecurityManagementDataStoreException;
282 }
283
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags