View Javadoc

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