View Javadoc

1   /*
2    * Copyright 2000-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.apache.jetspeed.services.security;
18  
19  import java.util.Iterator;
20  
21  import org.apache.jetspeed.om.security.Role;
22  import org.apache.turbine.services.TurbineServices;
23  
24  /***
25   * <p> The <code>RoleManagement</code> interface describes contract between
26   * the portal and security provider required for Jetspeed Role Management.
27   * This interface enables an application to be independent of the underlying
28   * role management technology.
29   *
30   * @author <a href="mailto:david@bluesunrise.com">David Sean Taylor</a>
31   * @author <a href="mailto:morciuch@apache.org">Mark Orciuch</a>
32   * @version $Id: JetspeedRoleManagement.java,v 1.5 2004/02/23 03:58:11 jford Exp $
33   */
34  
35  public abstract class JetspeedRoleManagement
36  {
37    public String SERVICE_NAME = "RoleManagement";
38  
39    /*
40     * Utility method for accessing the service
41     * implementation
42     *
43     * @return a RoleService implementation instance
44     */
45    protected static RoleManagement getService()
46    {
47      return (RoleManagement) TurbineServices
48          .getInstance().getService(RoleManagement.SERVICE_NAME);
49    }
50  
51    /***
52     * Retrieves all <code>Role</code>s for a given username principal.
53     *
54     * The security service may optionally check the current user context
55     * to determine if the requestor has permission to perform this action.
56     *
57     * @param username a user principal identity to be retrieved.
58     * @return Iterator over all roles associated to the user principal.
59     * @exception RoleException when the security provider has a general failure.
60     * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
61     */
62    public static Iterator getRoles(String username) throws JetspeedSecurityException
63    {
64      return getService().getRoles(username);
65    }
66  
67    /***
68     * Retrieves all <code>Role</code>s.
69     *
70     * The security service may optionally check the current user context
71     * to determine if the requestor has permission to perform this action.
72     *
73     * @return Iterator over all roles.
74     * @exception RoleException when the security provider has a general failure.
75     * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
76     */
77    public static Iterator getRoles() throws JetspeedSecurityException
78    {
79      return getService().getRoles();
80    }
81  
82    /***
83     * Adds a <code>Role</code> into permanent storage.
84     *
85     *
86     * @exception RoleException when the security provider has a general failure.
87     * @exception NotUniqueEntityException when the public credentials fail to meet
88     *                                   the security provider-specific unique constraints.
89     * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
90     */
91    public static void addRole(Role role) throws JetspeedSecurityException
92    {
93      getService().addRole(role);
94    }
95  
96    /***
97     * Save a <code>Role</code> into permanent storage.
98     *
99     *
100    * @exception RoleException when the security provider has a general failure.
101    * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
102    */
103   public static void saveRole(Role role) throws JetspeedSecurityException
104   {
105     getService().saveRole(role);
106   }
107 
108   /***
109    * Removes a <code>Role</code> from the permanent store.
110    *
111    * The security service may optionally check the current user context
112    * to determine if the requestor has permission to perform this action.
113    *
114    * @param rolename the principal identity of the role to be retrieved.
115    * @exception RoleException when the security provider has a general failure.
116    * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
117    */
118   public static void removeRole(String rolename) throws JetspeedSecurityException
119   {
120     getService().removeRole(rolename);
121   }
122 
123   /***
124    * Grants a role to a user.
125    *
126    * The security service may optionally check the current user context
127    * to determine if the requestor has permission to perform this action.
128    *
129    * @exception RoleException when the security provider has a general failure retrieving users.
130    * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
131    */
132   public static void grantRole(String username, String rolename) throws JetspeedSecurityException
133   {
134     getService().grantRole(username, rolename);
135   }
136 
137   /***
138    * Grants a role to a user for a given group.
139    *
140    * The security service may optionally check the current user context
141    * to determine if the requestor has permission to perform this action.
142    *
143    * @exception RoleException when the security provider has a general failure retrieving users.
144    * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
145    */
146   public static void grantRole(String username, String rolename, String groupname) throws JetspeedSecurityException
147   {
148     getService().grantRole(username, rolename, groupname);
149   }
150 
151   /***
152    * Revokes a role from a user.
153    *
154    * The security service may optionally check the current user context
155    * to determine if the requestor has permission to perform this action.
156    *
157    * @exception RoleException when the security provider has a general failure retrieving users.
158    * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
159    */
160   public static void revokeRole(String username, String rolename) throws JetspeedSecurityException
161   {
162     getService().revokeRole(username, rolename);
163   }
164 
165   /***
166    * Revokes a role from a user for a specific group.
167    *
168    * The security service may optionally check the current user context
169    * to determine if the requestor has permission to perform this action.
170    *
171    * @exception RoleException when the security provider has a general failure retrieving users.
172    * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
173    */
174   public static void revokeRole(String username, String rolename, String groupname) throws JetspeedSecurityException
175   {
176     getService().revokeRole(username, rolename, groupname);
177   }
178 
179 
180   /***
181    * Checks for the relationship of user has a role. Returns true when the user has the given role.
182    *
183    * The security service may optionally check the current user context
184    * to determine if the requestor has permission to perform this action.
185    *
186    * @exception RoleException when the security provider has a general failure retrieving users.
187    * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
188    */
189   public static boolean hasRole(String username, String rolename) throws JetspeedSecurityException
190   {
191     return getService().hasRole(username, rolename);
192   }
193 
194   public static boolean hasRole(String username, String rolename, String groupname) throws JetspeedSecurityException
195   {
196 	return getService().hasRole(username, rolename, groupname);
197   }
198 
199   /***
200    * Retrieves a single <code>Role</code> for a given rolename principal.
201    *
202    * The security service may optionally check the current user context
203    * to determine if the requestor has permission to perform this action.
204    *
205    * @param rolename a role principal identity to be retrieved.
206    * @return Role the role record retrieved.
207    * @exception RoleException when the security provider has a general failure.
208    * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
209    */
210   public static Role getRole(String rolename) throws JetspeedSecurityException
211   {
212     return getService().getRole(rolename);
213   }
214 
215 }