View Javadoc

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