1 /**
2 * This file Copyright (c) 2003-2018 Magnolia International
3 * Ltd. (http://www.magnolia-cms.com). All rights reserved.
4 *
5 *
6 * This file is dual-licensed under both the Magnolia
7 * Network Agreement and the GNU General Public License.
8 * You may elect to use one or the other of these licenses.
9 *
10 * This file is distributed in the hope that it will be
11 * useful, but AS-IS and WITHOUT ANY WARRANTY; without even the
12 * implied warranty of MERCHANTABILITY or FITNESS FOR A
13 * PARTICULAR PURPOSE, TITLE, or NONINFRINGEMENT.
14 * Redistribution, except as permitted by whichever of the GPL
15 * or MNA you select, is prohibited.
16 *
17 * 1. For the GPL license (GPL), you can redistribute and/or
18 * modify this file under the terms of the GNU General
19 * Public License, Version 3, as published by the Free Software
20 * Foundation. You should have received a copy of the GNU
21 * General Public License, Version 3 along with this program;
22 * if not, write to the Free Software Foundation, Inc., 51
23 * Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
24 *
25 * 2. For the Magnolia Network Agreement (MNA), this file
26 * and the accompanying materials are made available under the
27 * terms of the MNA which accompanies this distribution, and
28 * is available at http://www.magnolia-cms.com/mna.html
29 *
30 * Any modifications to this file must keep this entire header
31 * intact.
32 *
33 */
34 package info.magnolia.cms.security;
35
36 import info.magnolia.cms.security.auth.ACL;
37
38 import java.util.Collection;
39 import java.util.Map;
40
41 /**
42 * Manages groups, groups are identified by name and can be organized in folders. The name is globally unique regardless
43 * of their organisation in folders.
44 *
45 * @see Group
46 */
47 public interface GroupManager {
48
49 /**
50 * Creates a new group in the root folder.
51 *
52 * @throws IllegalArgumentException if the name is not valid or if a group with this name already exists
53 * @throws UnsupportedOperationException if the implementation does not support writing
54 */
55 Group createGroup(String name) throws UnsupportedOperationException, AccessDeniedException;
56
57 /**
58 * Get a group by name.
59 *
60 * @throws UnsupportedOperationException if the implementation does not support writing
61 */
62 Group getGroup(String name) throws UnsupportedOperationException, AccessDeniedException;
63
64 /**
65 * Get all groups defined in the system.
66 */
67 Collection<Group> getAllGroups() throws UnsupportedOperationException;
68
69 /**
70 * Returns all super-groups of the given group, i.e. both directly assigned and transitively assigned super-groups.
71 *
72 * @see #getAllSuperGroups(String)
73 *
74 * @deprecated since 5.5, use {@link #getAllSuperGroups(String)} instead.
75 */
76 @Deprecated
77 Collection<String> getAllGroups(String groupName) throws UnsupportedOperationException;
78
79 /**
80 * Returns all super-groups of the given group, i.e. both directly assigned and transitively assigned super-groups.
81 * <p>Given the following groups:</p>
82 * <pre>
83 * /
84 * ├── people
85 * │ └──employees ("employees" is directly assigned to the "people" super-group)
86 * │ └──developers ("developers" is directly assigned to the "employees" super-group; and is thus transitively assigned to the "people" super-group)
87 *
88 * #getAllSuperGroups("people") = []
89 * #getAllSuperGroups("employees") = ["people"]
90 * #getAllSuperGroups("developers") = ["employees","people"]
91 * </pre>
92 */
93 Collection<String> getAllSuperGroups(final String groupName) throws UnsupportedOperationException;
94
95 /**
96 * Returns all sub-groups of the given group.
97 * <p>Given the following groups:</p>
98 * <pre>
99 * /
100 * ├── people
101 * │ └──employees ("employees" is directly assigned to the "people" super-group)
102 * │ └──developers ("developers" is directly assigned to the "employees" super-group; and is thus transitively assigned to the "people" super-group)
103 *
104 * #getAllSubGroups("people") = ["employees","developers"]
105 * #getAllSubGroups("employees") = ["developers"]
106 * #getAllSubGroups("developers") = []
107 * </pre>
108 */
109 Collection<String> getAllSubGroups(final String groupName) throws UnsupportedOperationException;
110
111 Map<String, ACL> getACLs(String group);
112
113 /**
114 * Grants a role to a group.
115 *
116 * @return Group object with the role already granted.
117 */
118 Groupf="../../../../info/magnolia/cms/security/Group.html#Group">Group addRole(Group group, String roleName) throws AccessDeniedException;
119
120 /**
121 * Adds a group to a group.
122 *
123 * @return group object with the group already assigned.
124 */
125 Group="../../../../info/magnolia/cms/security/Group.html#Group">Group addGroup(Group group, String groupName) throws AccessDeniedException;
126
127 /**
128 * Returns sub-groups directly assigned to the given group.
129 *
130 * @see #getDirectSubGroups(String)
131 *
132 * @deprecated since 5.5, use {@link #getDirectSubGroups(String)} instead.
133 */
134 @Deprecated
135 Collection<String> getGroupsWithGroup(String groupName);
136
137 /**
138 * Returns sub-groups directly assigned to the given group.
139 * <p>Given the following groups:</p>
140 * <pre>
141 * /
142 * ├── people
143 * │ └──employees ("employees" is directly assigned to the "people" super-group)
144 * │ └──developers ("developers" is directly assigned to the "employees" super-group; and is thus transitively assigned to the "people" super-group)
145 *
146 * #getDirectSubGroups("people") = ["employees"]
147 * #getDirectSubGroups("employees") = ["developers"]
148 * #getDirectSubGroups("developers") = []
149 * </pre>
150 */
151 Collection<String> getDirectSubGroups(String groupName);
152
153 /**
154 * Returns direct super-groups of the given group.
155 * <p>Given the following groups:</p>
156 * <pre>
157 * /
158 * ├── people
159 * │ └──employees ("employees" is directly assigned to the "people" super-group)
160 * │ └──developers ("developers" is directly assigned to the "employees" super-group; and is thus transitively assigned to the "people" super-group)
161 *
162 * #getDirectSuperGroups("people") = []
163 * #getDirectSuperGroups("employees") = ["people"]
164 * #getDirectSuperGroups("developers") = ["employees"]
165 * </pre>
166 */
167 Collection<String> getDirectSuperGroups(String groupName);
168
169 /**
170 * Returns all groups having assigned the provided role.
171 */
172 Collection<String> getGroupsWithRole(String roleName);
173
174 /**
175 * Removes group from a group.
176 *
177 * @return group object with the group assignment removed.
178 */
179 Group./../../../info/magnolia/cms/security/Group.html#Group">Group removeGroup(Group group, String groupName) throws AccessDeniedException;
180
181 /**
182 * Removes role from a group.
183 *
184 * @return group object without removed role.
185 */
186 Group../../../../info/magnolia/cms/security/Group.html#Group">Group removeRole(Group group, String roleName) throws AccessDeniedException;
187 }