1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.jetspeed.security;
18
19 import java.util.Iterator;
20 import java.util.Collection;
21
22 /***
23 * <p>Describes the service interface for managing roles.</p>
24 * <p>Role hierarchy elements are being returned as a {@link Role}
25 * collection. The backing implementation must appropriately map
26 * the role hierarchy to a preferences sub-tree.</p>
27 * <p>The convention {principal}.{subprincipal} has been chosen to name
28 * roles hierachies in order to support declarative security. Implementation
29 * follow the conventions enforced by the preferences API.</p>
30 * @author <a href="mailto:dlestrat@apache.org">David Le Strat</a>
31 */
32 public interface RoleManager
33 {
34
35 /***
36 * <p>Add a new role.</p>
37 * <p>Role principal names are expressed as {principal}.{subprincipal} where
38 * "." is the separator expressing the hierarchical nature of a role.</p>
39 * <p>Role principal path names are stored leveraging the {@link Preferences}
40 * api. Roles will be stored under /role/theGroupName/theGroupNameChild
41 * when given the full path name theRoleName.theRoleNameChild.
42 * @param roleFullPathName The role name full path
43 * (e.g. theRoleName.theRoleNameChild).
44 * @throws Throws a security exception if the role already exists.
45 */
46 void addRole(String roleFullPathName) throws SecurityException;
47
48 /***
49 * <p>Remove a given role and all the children of that role.</p>
50 * <p>Role principal names are expressed as {principal}.{subprincipal} where
51 * "." is the separator expressing the hierarchical nature of a role.</p>
52 * <p>Role principal path names are stored leveraging the {@link Preferences}
53 * api. Roles will be stored under /role/theGroupName/theGroupNameChild
54 * when given the full path name theRoleName.theRoleNameChild.
55 * @param roleFullPathName The role name full path
56 * (e.g. theRoleName.theRoleNameChild).
57 * @throws Throws a security exception.
58 */
59 void removeRole(String roleFullPathName) throws SecurityException;
60
61 /***
62 * <p>Whether or not a role exists.</p>
63 * @param roleFullPathName The role name full path
64 * (e.g. theRoleName.theRoleNameChild).
65 * @return Whether or not a role exists.
66 */
67 boolean roleExists(String roleFullPathName);
68
69 /***
70 * <p>Get a role {@link Role} for a given role full path name.
71 * @param roleFullPathName The role name full path
72 * (e.g. theRoleName.theRoleNameChild).
73 * @return The {@link Preferences} node.
74 * @throws Throws a security exception if the role does not exist.
75 */
76 Role getRole(String roleFullPathName) throws SecurityException;
77
78 /***
79 * <p>A collection of {@link Role} for all the roles
80 * associated to a specific user.</p>
81 * @param username The user name.
82 * @return A Collection of {@link Role}.
83 * @throws Throws a security exception if the user does not exist.
84 */
85 Collection getRolesForUser(String username) throws SecurityException;
86
87 /***
88 * <p>A collection of {@link Role} for all the roles
89 * associated to a specific group.</p>
90 * @param groupFullPathName The group full path
91 * (e.g. theGroupName.theGroupChildName).
92 * @return A Collection of {@link Role}.
93 * @throws Throws a security exception if the group does not exist.
94 */
95 Collection getRolesInGroup(String groupFullPathName) throws SecurityException;
96
97 /***
98 * <p>Add a role to a user.</p>
99 * @param username The user name.
100 * @param roleFullPathName The role name full path
101 * (e.g. theRoleName.theRoleChildName).
102 * @throws Throws a security exception if the role or the user do not exist.
103 */
104 void addRoleToUser(String username, String roleFullPathName) throws SecurityException;
105
106 /***
107 * <p>Remove a user from a role.</p>
108 * @param username The user name.
109 * @param roleFullPathName The role name full path relative to the
110 * /role node (e.g. /theRoleName/theRoleChildName).
111 * @throws Throws a security exception.
112 */
113 void removeRoleFromUser(String username, String roleFullPathName) throws SecurityException;
114
115 /***
116 * <p>Whether or not a user is in a role.</p>
117 * @param username The user name.
118 * @param roleFullPathName The role name full path
119 * (e.g. theRoleName.theRoleChildName).
120 * @return Whether or not a user is in a role.
121 * @throws Throws a security exception if the role or the user does not exist.
122 */
123 boolean isUserInRole(String username, String roleFullPathName) throws SecurityException;
124
125 /***
126 * <p>Add a role to a group.</p>
127 * @param roleFullPathName The role name full path
128 * (e.g. theRoleName.theRoleChildName).
129 * @param groupFullPathName The group name full path
130 * (e.g. theGroupName.theGroupChildName).
131 * @throws Throws a security exception.
132 */
133 void addRoleToGroup(String roleFullPathName, String groupFullPathName) throws SecurityException;
134
135 /***
136 * <p>Remove a role from a group.</p>
137 * @param roleFullPathName The role name full path
138 * (e.g. theRoleName.theRoleChildName).
139 * @param groupFullPathName The group name full path
140 * (e.g. theGroupName.theGroupChildName).
141 * @throws Throws a security exception.
142 */
143 void removeRoleFromGroup(String roleFullPathName, String groupFullPathName) throws SecurityException;
144
145 /***
146 * <p>Whether or not a role is in a group.</p>
147 * @param groupFullPathName The group name full path
148 * (e.g. theGroupName.theGroupChildName).
149 * @param roleFullPathName The role name full path
150 * (e.g. theRoleName.theRoleChildName).
151 * @return Whether or not a role is in a group.
152 * @throws Throws a security exception if the role or the group does not exist.
153 */
154 boolean isGroupInRole(String groupFullPathName, String roleFullPathName) throws SecurityException;
155
156 /***
157 * Get all roles available from all role handlers
158 *
159 * @param filter The filter used to retrieve matching roles.
160 * @return all roles available as {@link Principal}
161 */
162 Iterator getRoles(String filter) throws SecurityException;
163
164 /***
165 * Enable or disable a role.
166 * @param roleFullPathName The role name full path
167 * (e.g. theRoleName.theRoleChildName).
168 * @param enabled enabled flag for the role
169 */
170 void setRoleEnabled(String roleFullPathName, boolean enabled) throws SecurityException;
171 }