SecurityService


1   package org.apache.turbine.services.security;
2   
3   /*
4    * Copyright 2001-2004 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.util.List  ;
20  import java.util.Map  ;
21  
22  import org.apache.torque.util.Criteria;
23  
24  import org.apache.turbine.om.security.Group;
25  import org.apache.turbine.om.security.Permission;
26  import org.apache.turbine.om.security.Role;
27  import org.apache.turbine.om.security.TurbineGroup;
28  import org.apache.turbine.om.security.TurbinePermission;
29  import org.apache.turbine.om.security.TurbineRole;
30  import org.apache.turbine.om.security.TurbineUser;
31  import org.apache.turbine.om.security.User;
32  import org.apache.turbine.services.Service;
33  import org.apache.turbine.services.security.db.DBUserManager;
34  import org.apache.turbine.util.security.AccessControlList;
35  import org.apache.turbine.util.security.DataBackendException;
36  import org.apache.turbine.util.security.EntityExistsException;
37  import org.apache.turbine.util.security.GroupSet;
38  import org.apache.turbine.util.security.PasswordMismatchException;
39  import org.apache.turbine.util.security.PermissionSet;
40  import org.apache.turbine.util.security.RoleSet;
41  import org.apache.turbine.util.security.TurbineAccessControlList;
42  import org.apache.turbine.util.security.UnknownEntityException;
43  
44  /**
45   * The Security Service manages Users, Groups Roles and Permissions in the
46   * system.
47   *
48   * The task performed by the security service include creation and removal of
49   * accounts, groups, roles, and permissions; assigning users roles in groups;
50   * assigning roles specific permissions and construction of objects
51   * representing these logical entities.
52   *
53   * <p> Because of pluggable nature of the Services, it is possible to create
54   * multiple implementations of SecurityService, for example employing database
55   * and directory server as the data backend.<br>
56   *
57   * @author <a HREF="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
58   * @author <a HREF="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
59   * @author <a HREF="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
60   * @version $Id: SecurityService.java,v 1.21.2.2 2004/05/20 03:06:47 seade Exp $
61   */
62  public interface SecurityService
63          extends Service
64  {
65      /** The name of the service */
66      static final String   SERVICE_NAME = "SecurityService";
67  
68      /**
69       * the key within services's properties for user implementation
70       * classname (user.class)
71       */
72      static final String   USER_CLASS_KEY = "user.class";
73  
74      /**
75       * the default implementation of User interface
76       * (org.apache.turbine.om.security.TurbineUser)
77       */
78      static final String   USER_CLASS_DEFAULT
79              = TurbineUser.class.getName();
80  
81      /**
82       * The key within services' properties for the GROUP
83       * implementation classname (group.class)
84       */
85      static final String   GROUP_CLASS_KEY = "group.class";
86  
87      /**
88       * The default implementation of the Group interface
89       * (org.apache.turbine.om.security.TurbineGroup)
90       */
91      static final String   GROUP_CLASS_DEFAULT
92              = TurbineGroup.class.getName();
93  
94      /**
95       * The key within services' properties for the PERMISSION
96       * implementation classname (permission.class)
97       */
98      static final String   PERMISSION_CLASS_KEY = "permission.class";
99  
100     /**
101      * The default implementation of the Permissions interface
102      * (org.apache.turbine.om.security.TurbinePermission)
103      */
104     static final String   PERMISSION_CLASS_DEFAULT
105             = TurbinePermission.class.getName();
106 
107     /**
108      * The key within services' properties for the ROLE
109      * implementation classname (role.class)
110      */
111     static final String   ROLE_CLASS_KEY = "role.class";
112 
113     /**
114      * The default implementation of the Role Interface
115      * (org.apache.turbine.om.security.TurbineRole)
116      */
117     static final String   ROLE_CLASS_DEFAULT
118             = TurbineRole.class.getName();
119 
120     /**
121      * The key within services' properties for the
122      * ACL implementation classname (acl.class)
123      */
124     static final String   ACL_CLASS_KEY = "acl.class";
125 
126     /**
127      * The default implementation of the Acl Interface
128      * (org.apache.turbine.util.security.TurbineAccessControlList)
129      */
130     static final String   ACL_CLASS_DEFAULT
131             = TurbineAccessControlList.class.getName();
132 
133     /**
134      * the key within services's properties for user implementation
135      * classname (user.manager)
136      */
137     static final String   USER_MANAGER_KEY = "user.manager";
138 
139     /**
140      * the default implementation of UserManager interface
141      * (org.apache.turbine.services.security.DBUserManager)
142      */
143     static final String   USER_MANAGER_DEFAULT
144             = DBUserManager.class.getName();
145 
146     /**
147      * the key within services's properties for secure passwords flag
148      * (secure.passwords)
149      */
150     static final String   SECURE_PASSWORDS_KEY = "secure.passwords";
151 
152     /** the value of secure passwords flag (false) */
153     static final String   SECURE_PASSWORDS_DEFAULT = "false";
154 
155     /**
156      * the key within services's properties for secure passwords algorithm
157      * (secure.passwords.algorithm)
158      */
159     static final String   SECURE_PASSWORDS_ALGORITHM_KEY
160             = "secure.passwords.algorithm";
161 
162     /** the default algorithm for password encryption (SHA) */
163     static final String   SECURE_PASSWORDS_ALGORITHM_DEFAULT = "SHA";
164 
165     /*-----------------------------------------------------------------------
166       Management of User objects
167       -----------------------------------------------------------------------*/
168 
169     /**
170      * Returns the Class object for the implementation of User interface
171      * used by the system.
172      *
173      * @return the implementation of User interface used by the system.
174      * @throws UnknownEntityException if the system's implementation of User
175      *         interface could not be determined.
176      */
177     Class   getUserClass()
178             throws UnknownEntityException;
179 
180     /**
181      * Construct a blank User object.
182      *
183      * This method calls getUserClass, and then creates a new object using
184      * the default constructor.
185      *
186      * @return an object implementing User interface.
187      * @throws UnknownEntityException if the object could not be instantiated.
188      */
189     User getUserInstance()
190             throws UnknownEntityException;
191 
192     /**
193      * Construct a blank User object.
194      *
195      * This method calls getUserClass, and then creates a new object using
196      * the default constructor.
197      *
198      * @param userName The name of the user.
199      *
200      * @return an object implementing User interface.
201      * @throws UnknownEntityException if the object could not be instantiated.
202      */
203     User getUserInstance(String   userName)
204             throws UnknownEntityException;
205 
206     /**
207      * Returns the Class object for the implementation of Group interface
208      * used by the system.
209      *
210      * @return the implementation of Group interface used by the system.
211      * @throws UnknownEntityException if the system's implementation of Group
212      *         interface could not be determined.
213      */
214     Class   getGroupClass()
215             throws UnknownEntityException;
216 
217     /**
218      * Construct a blank Group object.
219      *
220      * This method calls getGroupClass, and then creates a new object using
221      * the default constructor.
222      *
223      * @return an object implementing Group interface.
224      * @throws UnknownEntityException if the object could not be instantiated.
225      */
226     Group getGroupInstance()
227             throws UnknownEntityException;
228 
229     /**
230      * Construct a blank Group object.
231      *
232      * This method calls getGroupClass, and then creates a new object using
233      * the default constructor.
234      *
235      * @param groupName The name of the Group
236      *
237      * @return an object implementing Group interface.
238      * @throws UnknownEntityException if the object could not be instantiated.
239      */
240     Group getGroupInstance(String   groupName)
241             throws UnknownEntityException;
242 
243     /**
244      * Returns the Class object for the implementation of Permission interface
245      * used by the system.
246      *
247      * @return the implementation of Permission interface used by the system.
248      * @throws UnknownEntityException if the system's implementation of Permission
249      *         interface could not be determined.
250      */
251     Class   getPermissionClass()
252             throws UnknownEntityException;
253 
254     /**
255      * Construct a blank Permission object.
256      *
257      * This method calls getPermissionClass, and then creates a new object using
258      * the default constructor.
259      *
260      * @return an object implementing Permission interface.
261      * @throws UnknownEntityException if the object could not be instantiated.
262      */
263     Permission getPermissionInstance()
264             throws UnknownEntityException;
265 
266     /**
267      * Construct a blank Permission object.
268      *
269      * This method calls getPermissionClass, and then creates a new object using
270      * the default constructor.
271      *
272      * @param permName The name of the Permission
273      *
274      * @return an object implementing Permission interface.
275      * @throws UnknownEntityException if the object could not be instantiated.
276      */
277     Permission getPermissionInstance(String   permName)
278             throws UnknownEntityException;
279 
280     /**
281      * Returns the Class object for the implementation of Role interface
282      * used by the system.
283      *
284      * @return the implementation of Role interface used by the system.
285      * @throws UnknownEntityException if the system's implementation of Role
286      *         interface could not be determined.
287      */
288     Class   getRoleClass()
289             throws UnknownEntityException;
290 
291     /**
292      * Construct a blank Role object.
293      *
294      * This method calls getRoleClass, and then creates a new object using
295      * the default constructor.
296      *
297      * @return an object implementing Role interface.
298      * @throws UnknownEntityException if the object could not be instantiated.
299      */
300     Role getRoleInstance()
301             throws UnknownEntityException;
302 
303     /**
304      * Construct a blank Role object.
305      *
306      * This method calls getRoleClass, and then creates a new object using
307      * the default constructor.
308      *
309      * @param roleName The name of the Role
310      *
311      * @return an object implementing Role interface.
312      * @throws UnknownEntityException if the object could not be instantiated.
313      */
314     Role getRoleInstance(String   roleName)
315             throws UnknownEntityException;
316 
317     /**
318      * Returns the Class object for the implementation of AccessControlList interface
319      * used by the system.
320      *
321      * @return the implementation of AccessControlList interface used by the system.
322      * @throws UnknownEntityException if the system's implementation of AccessControlList
323      *         interface could not be determined.
324      */
325     Class   getAclClass()
326             throws UnknownEntityException;
327 
328     /**
329      * Construct a new ACL object.
330      *
331      * This constructs a new ACL object from the configured class and
332      * initializes it with the supplied roles and permissions.
333      *
334      * @param roles The roles that this ACL should contain
335      * @param permissions The permissions for this ACL
336      *
337      * @return an object implementing ACL interface.
338      * @throws UnknownEntityException if the object could not be instantiated.
339      */
340     AccessControlList getAclInstance(Map   roles, Map   permissions)
341             throws UnknownEntityException;
342 
343     /**
344      * Returns the configured UserManager.
345      *
346      * @return An UserManager object
347      */
348     UserManager getUserManager();
349 
350     /**
351      * Configure a new user Manager.
352      *
353      * @param userManager An UserManager object
354      */
355     void setUserManager(UserManager userManager);
356 
357     /**
358      * Check whether a specified user's account exists.
359      *
360      * The login name is used for looking up the account.
361      *
362      * @param userName The user to be checked.
363      * @return true if the specified account exists
364      * @throws DataBackendException if there was an error accessing the data
365      *         backend.
366      */
367     boolean accountExists(String   userName)
368             throws DataBackendException;
369 
370     /**
371      * Check whether a specified user's account exists.
372      * An User object is used for looking up the account.
373      *
374      * @param user The user object to be checked.
375      * @return true if the specified account exists
376      * @throws DataBackendException if there was an error accessing the data
377      *         backend.
378      */
379     boolean accountExists(User user)
380             throws DataBackendException;
381 
382     /**
383      * Authenticates an user, and constructs an User object to represent
384      * him/her.
385      *
386      * @param username The user name.
387      * @param password The user password.
388      * @return An authenticated Turbine User.
389      * @throws DataBackendException if there was an error accessing the data
390      *         backend.
391      * @throws UnknownEntityException if user account is not present.
392      * @throws PasswordMismatchException if the supplied password was incorrect.
393      */
394     User getAuthenticatedUser(String   username, String   password)
395             throws DataBackendException, UnknownEntityException,
396             PasswordMismatchException;
397 
398     /**
399      * Constructs an User object to represent a registered user of the
400      * application.
401      *
402      * @param username The user name.
403      * @return A Turbine User.
404      * @throws DataBackendException if there was an error accessing the data
405      *         backend.
406      * @throws UnknownEntityException if user account is not present.
407      */
408     User getUser(String   username)
409             throws DataBackendException, UnknownEntityException;
410 
411     /**
412      * Retrieve a set of users that meet the specified criteria.
413      *
414      * As the keys for the criteria, you should use the constants that
415      * are defined in {@link User} interface, plus the names
416      * of the custom attributes you added to your user representation
417      * in the data storage. Use verbatim names of the attributes -
418      * without table name prefix in case of DB implementation.
419      *
420      * @param criteria The criteria of selection.
421      * @return a List of users meeting the criteria.
422      * @throws DataBackendException if there is a problem accessing the
423      *         storage.
424      * @deprecated Use <a HREF="#retrieveList">retrieveList</a> instead.
425      */
426     User[] getUsers(Criteria criteria)
427             throws DataBackendException;
428 
429     /**
430      * Retrieve a set of users that meet the specified criteria.
431      *
432      * As the keys for the criteria, you should use the constants that
433      * are defined in {@link User} interface, plus the names
434      * of the custom attributes you added to your user representation
435      * in the data storage. Use verbatim names of the attributes -
436      * without table name prefix in case of Torque implementation.
437      *
438      * @param criteria The criteria of selection.
439      * @return a List of users meeting the criteria.
440      * @throws DataBackendException if there is a problem accessing the
441      *         storage.
442      */
443     List   getUserList(Criteria criteria)
444             throws DataBackendException;
445 
446     /**
447      * Constructs an User object to represent an anonymous user of the
448      * application.
449      *
450      * @return An anonymous Turbine User.
451      * @throws UnknownEntityException if the anonymous User object couldn't be
452      *         constructed.
453      */
454     User getAnonymousUser()
455             throws UnknownEntityException;
456 
457     /**
458      * Checks whether a passed user object matches the anonymous user pattern
459      * according to the configured user manager
460      *
461      * @param An user object
462      *
463      * @return True if this is an anonymous user
464      *
465      */
466     boolean isAnonymousUser(User u);
467 
468     /**
469      * Saves User's data in the permanent storage. The user account is required
470      * to exist in the storage.
471      *
472      * @param user the user object to save
473      * @throws UnknownEntityException if the user's account does not
474      *         exist in the database.
475      * @throws DataBackendException if there is a problem accessing the storage.
476      */
477     void saveUser(User user)
478             throws UnknownEntityException, DataBackendException;
479 
480     /**
481      * Saves User data when the session is unbound. The user account is required
482      * to exist in the storage.
483      *
484      * LastLogin, AccessCounter, persistent pull tools, and any data stored
485      * in the permData hashtable that is not mapped to a column will be saved.
486      *
487      * @exception UnknownEntityException if the user's account does not
488      *            exist in the database.
489      * @exception DataBackendException if there is a problem accessing the
490      *            storage.
491      */
492     void saveOnSessionUnbind(User user)
493             throws UnknownEntityException, DataBackendException;
494 
495     /*-----------------------------------------------------------------------
496       Account management
497       -----------------------------------------------------------------------*/
498 
499     /**
500      * Creates new user account with specified attributes.
501      *
502      * @param user the object describing account to be created.
503      * @param password The password to use.
504      * @throws DataBackendException if there was an error accessing the data
505      *         backend.
506      * @throws EntityExistsException if the user account already exists.
507      */
508     void addUser(User user, String   password)
509             throws DataBackendException, EntityExistsException;
510 
511     /**
512      * Removes an user account from the system.
513      *
514      * @param user the object describing the account to be removed.
515      * @throws DataBackendException if there was an error accessing the data
516      *         backend.
517      * @throws UnknownEntityException if the user account is not present.
518      */
519     void removeUser(User user)
520             throws DataBackendException, UnknownEntityException;
521 
522     /*-----------------------------------------------------------------------
523       Management of passwords
524       -----------------------------------------------------------------------*/
525 
526     /**
527      * This method provides client-side encryption mechanism for passwords.
528      *
529      * This is an utility method that is used by other classes to maintain
530      * a consistent approach to encrypting password. The behavior of the
531      * method can be configured in service's properties.
532      *
533      * @param password the password to process
534      * @return processed password
535      */
536     String   encryptPassword(String   password);
537 
538     /**
539      * This method provides client-side encryption mechanism for passwords.
540      *
541      * This is an utility method that is used by other classes to maintain
542      * a consistent approach to encrypting password. The behavior of the
543      * method can be configured in service's properties.
544      *
545      * Algorithms that must supply a salt for encryption
546      * can use this method to provide it.
547      *
548      * @param password the password to process
549      * @param salt Salt parameter for some crypto algorithms
550      *
551      * @return processed password
552      */
553     String   encryptPassword(String   password, String   salt);
554 
555     /**
556      * Checks if a supplied password matches the encrypted password
557      * when using the current encryption algorithm
558      *
559      * @param checkpw      The clear text password supplied by the user
560      * @param encpw        The current, encrypted password
561      *
562      * @return true if the password matches, else false
563      *
564      */
565     boolean checkPassword(String   checkpw, String   encpw);
566 
567     /**
568      * Change the password for an User.
569      *
570      * @param user an User to change password for.
571      * @param oldPassword the current password supplied by the user.
572      * @param newPassword the current password requested by the user.
573      * @exception PasswordMismatchException if the supplied password was
574      *            incorrect.
575      * @exception UnknownEntityException if the user's record does not
576      *            exist in the database.
577      * @exception DataBackendException if there is a problem accessing the
578      *            storage.
579      */
580     void changePassword(User user, String   oldPassword,
581                         String   newPassword)
582             throws PasswordMismatchException, UnknownEntityException,
583             DataBackendException;
584 
585     /**
586      * Forcibly sets new password for an User.
587      *
588      * This is supposed by the administrator to change the forgotten or
589      * compromised passwords. Certain implementatations of this feature
590      * would require administrative level access to the authenticating
591      * server / program.
592      *
593      * @param user an User to change password for.
594      * @param password the new password.
595      * @exception UnknownEntityException if the user's record does not
596      *            exist in the database.
597      * @exception DataBackendException if there is a problem accessing the
598      *            storage.
599      */
600     void forcePassword(User user, String   password)
601             throws UnknownEntityException, DataBackendException;
602 
603     /*-----------------------------------------------------------------------
604       Retrieval of security information
605       -----------------------------------------------------------------------*/
606 
607     /**
608      * Constructs an AccessControlList for a specific user.
609      *
610      * @param user the user for whom the AccessControlList are to be retrieved
611      * @return A new AccessControlList object.
612      * @throws DataBackendException if there was an error accessing the data backend.
613      * @throws UnknownEntityException if user account is not present.
614      */
615     AccessControlList getACL(User user)
616             throws DataBackendException, UnknownEntityException;
617 
618     /**
619      * Retrieves all permissions associated with a role.
620      *
621      * @param role the role name, for which the permissions are to be retrieved.
622      * @return the permissions associated with the role
623      * @throws DataBackendException if there was an error accessing the data
624      *         backend.
625      * @throws UnknownEntityException if the role is not present.
626      */
627     PermissionSet getPermissions(Role role)
628             throws DataBackendException, UnknownEntityException;
629 
630     /*-----------------------------------------------------------------------
631       Manipulation of security information
632       -----------------------------------------------------------------------*/
633 
634     /**
635      * Grant an User a Role in a Group.
636      *
637      * @param user the user.
638      * @param group the group.
639      * @param role the role.
640      * @throws DataBackendException if there was an error accessing the data
641      *         backend.
642      * @throws UnknownEntityException if user account, group or role is not
643      *         present.
644      */
645     void grant(User user, Group group, Role role)
646             throws DataBackendException, UnknownEntityException;
647 
648     /**
649      * Revoke a Role in a Group from an User.
650      *
651      * @param user the user.
652      * @param group the group.
653      * @param role the role.
654      * @throws DataBackendException if there was an error accessing the data
655      *         backend.
656      * @throws UnknownEntityException if user account, group or role is not
657      *         present.
658      */
659     void revoke(User user, Group group, Role role)
660             throws DataBackendException, UnknownEntityException;
661 
662     /**
663      * Revokes all roles from an User.
664      *
665      * This method is used when deleting an account.
666      *
667      * @param user the User.
668      * @throws DataBackendException if there was an error accessing the data
669      *         backend.
670      * @throws UnknownEntityException if the account is not present.
671      */
672     void revokeAll(User user)
673             throws DataBackendException, UnknownEntityException;
674 
675     /**
676      * Grants a Role a Permission
677      *
678      * @param role the Role.
679      * @param permission the Permission.
680      * @throws DataBackendException if there was an error accessing the data
681      *         backend.
682      * @throws UnknownEntityException if role or permission is not present.
683      */
684     void grant(Role role, Permission permission)
685             throws DataBackendException, UnknownEntityException;
686 
687     /**
688      * Revokes a Permission from a Role.
689      *
690      * @param role the Role.
691      * @param permission the Permission.
692      * @throws DataBackendException if there was an error accessing the data
693      *         backend.
694      * @throws UnknownEntityException if role or permission is not present.
695      */
696     void revoke(Role role, Permission permission)
697             throws DataBackendException, UnknownEntityException;
698 
699     /**
700      * Revokes all permissions from a Role.
701      *
702      * This method is user when deleting a Role.
703      *
704      * @param role the Role
705      * @throws DataBackendException if there was an error accessing the data
706      *         backend.
707      * @throws  UnknownEntityException if the Role is not present.
708      */
709     void revokeAll(Role role)
710             throws DataBackendException, UnknownEntityException;
711 
712     /*-----------------------------------------------------------------------
713       Retrieval & storage of SecurityObjects
714       -----------------------------------------------------------------------*/
715 
716     /**
717      * Provides a reference to the Group object that represents the
718      * <a HREF="#global">global group</a>.
719      *
720      * @return A Group object that represents the global group.
721      */
722     Group getGlobalGroup();
723 
724     /**
725      * @deprecated Use getGroupInstance(String name) instead.
726      */
727     Group getNewGroup(String   groupName);
728 
729     /**
730      * @deprecated Use getRoleInstance(String name) instead.
731      */
732     Role getNewRole(String   roleName);
733 
734     /**
735      * @deprecated Use getPermissionInstance(String name) instead.
736      */
737     Permission getNewPermission(String   permissionName);
738 
739     /**
740      * Retrieve a Group object with specified name.
741      *
742      * @param name the name of the Group.
743      * @return an object representing the Group with specified name.
744      * @throws DataBackendException if there was an error accessing the data
745      *         backend.
746      * @throws UnknownEntityException if the group does not exist.
747      * @deprecated Use <a HREF="#getGroupByName">getGroupByName</a> instead.
748      */
749     Group getGroup(String   name)
750             throws DataBackendException, UnknownEntityException;
751 
752     /**
753      * Retrieve a Group object with specified name.
754      *
755      * @param name the name of the Group.
756      * @return an object representing the Group with specified name.
757      * @throws DataBackendException if there was an error accessing the data
758      *         backend.
759      * @throws UnknownEntityException if the group does not exist.
760      */
761     Group getGroupByName(String   name)
762             throws DataBackendException, UnknownEntityException;
763 
764     /**
765      * Retrieve a Group object with specified Id.
766      *
767      * @param name the name of the Group.
768      *
769      * @return an object representing the Group with specified name.
770      *
771      * @exception UnknownEntityException if the permission does not
772      *            exist in the database.
773      * @exception DataBackendException if there is a problem accessing the
774      *            storage.
775      */
776     Group getGroupById(int id)
777             throws DataBackendException,
778                    UnknownEntityException;
779 
780     /**
781      * Retrieve a Role object with specified name.
782      *
783      * @param name the name of the Role.
784      * @return an object representing the Role with specified name.
785      * @throws DataBackendException if there was an error accessing the data
786      *         backend.
787      * @throws UnknownEntityException if the role does not exist.
788      * @deprecated Use <a HREF="#getRoleByName">getRoleByName</a> instead.
789      */
790     Role getRole(String   name)
791             throws DataBackendException, UnknownEntityException;
792 
793     /**
794      * Retrieve a Role object with specified name.
795      *
796      * @param name the name of the Role.
797      * @return an object representing the Role with specified name.
798      * @throws DataBackendException if there was an error accessing the data
799      *         backend.
800      * @throws UnknownEntityException if the role does not exist.
801      */
802     Role getRoleByName(String   name)
803             throws DataBackendException, UnknownEntityException;
804 
805     /**
806      * Retrieve a Role object with specified Id.
807      *
808      * @param name the name of the Role.
809      *
810      * @return an object representing the Role with specified name.
811      *
812      * @exception UnknownEntityException if the permission does not
813      *            exist in the database.
814      * @exception DataBackendException if there is a problem accessing the
815      *            storage.
816      */
817     Role getRoleById(int id)
818             throws DataBackendException,
819                    UnknownEntityException;
820 
821     /**
822      * Retrieve a Permission object with specified name.
823      *
824      * @param name the name of the Permission.
825      * @return an object representing the Permission with specified name.
826      * @throws DataBackendException if there was an error accessing the data
827      *         backend.
828      * @throws UnknownEntityException if the permission does not exist.
829      * @deprecated Use <a HREF="#getPermissionByName">getPermissionByName</a> instead.
830      */
831     Permission getPermission(String   name)
832             throws DataBackendException, UnknownEntityException;
833 
834     /**
835      * Retrieve a Permission object with specified name.
836      *
837      * @param name the name of the Permission.
838      * @return an object representing the Permission with specified name.
839      * @throws DataBackendException if there was an error accessing the data
840      *         backend.
841      * @throws UnknownEntityException if the permission does not exist.
842      */
843     Permission getPermissionByName(String   name)
844             throws DataBackendException, UnknownEntityException;
845 
846     /**
847      * Retrieve a Permission object with specified Id.
848      *
849      * @param name the name of the Permission.
850      *
851      * @return an object representing the Permission with specified name.
852      *
853      * @exception UnknownEntityException if the permission does not
854      *            exist in the database.
855      * @exception DataBackendException if there is a problem accessing the
856      *            storage.
857      */
858     Permission getPermissionById(int id)
859             throws DataBackendException,
860                    UnknownEntityException;
861 
862     /**
863      * Retrieve a set of Groups that meet the specified Criteria.
864      *
865      * @param criteria a Criteria of Group selection.
866      * @return a set of Groups that meet the specified Criteria.
867      * @throws DataBackendException if there was an error accessing the data
868      *         backend.
869      */
870     GroupSet getGroups(Criteria criteria)
871             throws DataBackendException;
872 
873     /**
874      * Retrieve a set of Roles that meet the specified Criteria.
875      *
876      * @param criteria a Criteria of Roles selection.
877      * @return a set of Roles that meet the specified Criteria.
878      * @throws DataBackendException if there was an error accessing the data
879      *         backend.
880      */
881     RoleSet getRoles(Criteria criteria)
882             throws DataBackendException;
883 
884     /**
885      * Retrieve a set of Permissions that meet the specified Criteria.
886      *
887      * @param criteria a Criteria of Permissions selection.
888      * @return a set of Permissions that meet the specified Criteria.
889      * @throws DataBackendException if there was an error accessing the data
890      *         backend.
891      */
892     PermissionSet getPermissions(Criteria criteria)
893             throws DataBackendException;
894 
895     /**
896      * Retrieves all groups defined in the system.
897      *
898      * @return the names of all groups defined in the system.
899      * @throws DataBackendException if there was an error accessing the data
900      *         backend.
901      */
902     GroupSet getAllGroups()
903             throws DataBackendException;
904 
905     /**
906      * Retrieves all roles defined in the system.
907      *
908      * @return the names of all roles defined in the system.
909      * @throws DataBackendException if there was an error accessing the data
910      *         backend.
911      */
912     RoleSet getAllRoles()
913             throws DataBackendException;
914 
915     /**
916      * Retrieves all permissions defined in the system.
917      *
918      * @return the names of all roles defined in the system.
919      * @throws DataBackendException if there was an error accessing the data
920      *         backend.
921      */
922     PermissionSet getAllPermissions()
923             throws DataBackendException;
924 
925     /**
926      * Stores Group's attributes. The Groups is required to exist in the system.
927      *
928      * @param group The Group to be stored.
929      * @throws DataBackendException if there was an error accessing the data
930      *         backend.
931      * @throws UnknownEntityException if the group does not exist.
932      */
933     void saveGroup(Group group)
934             throws DataBackendException, UnknownEntityException;
935 
936     /**
937      * Stores Role's attributes. The Roles is required to exist in the system.
938      *
939      * @param role The Role to be stored.
940      * @throws DataBackendException if there was an error accessing the data
941      *         backend.
942      * @throws UnknownEntityException if the role does not exist.
943      */
944     void saveRole(Role role)
945             throws DataBackendException, UnknownEntityException;
946 
947     /**
948      * Stores Permission's attributes. The Permission is required to exist in
949      * the system.
950      *
951      * @param permission The Permission to be stored.
952      * @throws DataBackendException if there was an error accessing the data
953      *         backend.
954      * @throws UnknownEntityException if the permission does not exist.
955      */
956     void savePermission(Permission permission)
957             throws DataBackendException, UnknownEntityException;
958 
959     /*-----------------------------------------------------------------------
960       Group/Role/Permission management
961       -----------------------------------------------------------------------*/
962 
963     /**
964      * Creates a new group with specified attributes.
965      *
966      * @param group the object describing the group to be created.
967      * @return the new Group object.
968      * @throws DataBackendException if there was an error accessing the data
969      *         backend.
970      * @throws EntityExistsException if the group already exists.
971      */
972     Group addGroup(Group group)
973             throws DataBackendException, EntityExistsException;
974 
975     /**
976      * Creates a new role with specified attributes.
977      *
978      * @param role The object describing the role to be created.
979      * @return the new Role object.
980      * @throws DataBackendException if there was an error accessing the data
981      *         backend.
982      * @throws EntityExistsException if the role already exists.
983      */
984     Role addRole(Role role)
985             throws DataBackendException, EntityExistsException;
986 
987     /**
988      * Creates a new permission with specified attributes.
989      *
990      * @param permission The object describing the permission to be created.
991      * @return the new Permission object.
992      * @throws DataBackendException if there was an error accessing the data
993      *         backend.
994      * @throws EntityExistsException if the permission already exists.
995      */
996     Permission addPermission(Permission permission)
997             throws DataBackendException, EntityExistsException;
998 
999     /**
1000     * Removes a Group from the system.
1001     *
1002     * @param group The object describing the group to be removed.
1003     * @throws DataBackendException if there was an error accessing the data
1004     *         backend.
1005     * @throws UnknownEntityException if the group does not exist.
1006     */
1007    void removeGroup(Group group)
1008            throws DataBackendException, UnknownEntityException;
1009
1010    /**
1011     * Removes a Role from the system.
1012     *
1013     * @param role The object describing the role to be removed.
1014     * @throws DataBackendException if there was an error accessing the data
1015     *         backend.
1016     * @throws UnknownEntityException if the role does not exist.
1017     */
1018    void removeRole(Role role)
1019            throws DataBackendException, UnknownEntityException;
1020
1021    /**
1022     * Removes a Permission from the system.
1023     *
1024     * @param permission The object describing the permission to be removed.
1025     * @throws DataBackendException if there was an error accessing the data
1026     *         backend.
1027     * @throws UnknownEntityException if the permission does not exist.
1028     */
1029    void removePermission(Permission permission)
1030            throws DataBackendException, UnknownEntityException;
1031
1032    /**
1033     * Renames an existing Group.
1034     *
1035     * @param group The object describing the group to be renamed.
1036     * @param name the new name for the group.
1037     * @throws DataBackendException if there was an error accessing the data
1038     *         backend.
1039     * @throws UnknownEntityException if the group does not exist.
1040     */
1041    void renameGroup(Group group, String   name)
1042            throws DataBackendException, UnknownEntityException;
1043
1044    /**
1045     * Renames an existing Role.
1046     *
1047     * @param role The object describing the role to be renamed.
1048     * @param name the new name for the role.
1049     * @throws DataBackendException if there was an error accessing the data
1050     *         backend.
1051     * @throws UnknownEntityException if the role does not exist.
1052     */
1053    void renameRole(Role role, String   name)
1054            throws DataBackendException, UnknownEntityException;
1055
1056    /**
1057     * Renames an existing Permission.
1058     *
1059     * @param permission The object describing the permission to be renamed.
1060     * @param name the new name for the permission.
1061     * @throws DataBackendException if there was an error accessing the data
1062     *         backend.
1063     * @throws UnknownEntityException if the permission does not exist.
1064     */
1065    void renamePermission(Permission permission, String   name)
1066            throws DataBackendException, UnknownEntityException;
1067}
1068
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags