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