KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > turbine > services > security > TurbineSecurity


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 JavaDoc;
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,v 1.19.2.2 2004/05/20 03:06:47 seade Exp $
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 JavaDoc encryptPassword(String JavaDoc 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 JavaDoc encryptPassword(String JavaDoc password, String JavaDoc 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 JavaDoc checkpw, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc username, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc oldPassword,
396                                       String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc name)
1156            throws DataBackendException, UnknownEntityException
1157    {
1158        getService().renamePermission(permission, name);
1159    }
1160}
1161
Popular Tags