1 package com.atlassian.user;
2
3 import com.atlassian.user.search.page.Pager;
4 import com.atlassian.user.impl.DuplicateEntityException;
5
6 import java.util.List;
7
8 /**
9 * A group manager is responsible for all CRUD operations on groups and group
10 * memberships in a given repository.
11 *
12 * Where an operation requires a {@link Group} as an argument, calling the
13 * method with a group from another repository will typically throw an
14 * {@link IllegalArgumentException}.
15 *
16 * The group manager is responsible for ensuring the consistency of the underlying
17 * repository where relevant. For example, if membership information needs to be
18 * updated as part of the {@link #removeGroup(Group)} operation, the group manager
19 * is responsible for ensuring it happens.
20 *
21 * This interface is an extension of the {@link EntityManager} interface which
22 * is common to user and group management. The common functionality includes
23 * initialisation and access to the repository description.
24 */
25 public interface GroupManager extends EntityManager
26 {
27 /**
28 * Retrieves all groups in this repository.
29 *
30 * @return a {@link Pager} containing a {@link Group} for each group managed
31 * by the repository. An empty pager will be returned if the repository does
32 * not contain any groups.
33 */
34 Pager<Group> getGroups() throws EntityException;
35
36 /**
37 * Retrieves the groups to which the given user belongs. Only groups which
38 * are managed by this repository are included.
39 *
40 * @return a {@link Pager} containing a {@link Group} for each group the user
41 * belongs to. An empty pager will be returned if the user does not belong to
42 * any groups that this manager knows about.
43 * @throws IllegalArgumentException if the user provided is <tt>null</tt>
44 */
45 Pager<Group> getGroups(User user) throws EntityException;
46
47 /**
48 * Gets all editable groups. That is, returns any groups that belong to read/write repositories. Groups in readonly
49 * repositories that are ReadOnly are not returned.
50 *
51 * @return list of {@link Group}s that can be edited.
52 */
53 List <Group> getWritableGroups();
54
55 /**
56 * Retrieves the names of all members of the specified group. The names are
57 * ordered by a Collator for the JVM's default locale (as returned by
58 * {@link java.text.Collator#getInstance()}.
59 *
60 * @return a {@link Pager} containing a {@link String} with the name of each
61 * member of the group. An empty pager will be returned if the group has no
62 * members.
63 */
64 Pager<String> getMemberNames(Group group) throws EntityException;
65
66 /**
67 * Retrieves the names of those members of the specified group which are also
68 * stored in this repository. The names are ordered by a Collator for the JVM's
69 * default locale (as returned by {@link java.text.Collator#getInstance()}.
70 * <p/>
71 * If {@link #supportsExternalMembership()} returns <code>false</code>, this
72 * call is equivalent to {@link #getMemberNames(Group)}.
73 *
74 * @return a {@link Pager} containing a {@link String} with the name of each
75 * member of the group which is stored in the same repository. An empty pager
76 * will be returned if the group has no local members.
77 */
78 Pager<String> getLocalMemberNames(Group group) throws EntityException;
79
80 /**
81 * Retrieves the names of those members of the specified group which are
82 * stored in another repository. For example, an LDAP user which is a member
83 * of a Hibernate group is an external member of the Hibernate group.
84 * <p/>
85 * The names are ordered by a Collator for the JVM's default locale (as
86 * returned by {@link java.text.Collator#getInstance()}.
87 * <p/>
88 * If {@link #supportsExternalMembership()} returns <code>false</code>, this
89 * method throws {@link UnsupportedOperationException}.
90 *
91 * @return a {@link Pager} containing a {@link String} with the name of each
92 * member of the group which is stored in a different repository. An empty pager
93 * will be returned if the group has no external members.
94 * @throws UnsupportedOperationException if {@link #supportsExternalMembership()}
95 * returns <code>false</code>.
96 */
97 Pager<String> getExternalMemberNames(Group group) throws EntityException;
98
99 /**
100 * Retrieves the group with the given name. Returns <code>null</code> if the
101 * group does not exist in this repository.
102 *
103 * @return a {@link Group} or null if the group does not exist.
104 */
105 Group getGroup(String groupName) throws EntityException;
106
107 /**
108 * Create a new group with the specified name.
109 *
110 * @throws DuplicateEntityException if a group with the provided name already exists.
111 * @throws EntityException if the {@link Group} could not be created.
112 * @throws UnsupportedOperationException if {@link #isCreative()} returns false
113 */
114 Group createGroup(String groupName) throws EntityException;
115
116 /**
117 * Remove the group specified, if it exists in this repository. If the group does not belong
118 * to this repository, an {@link IllegalArgumentException} will be thrown.
119 *
120 * If required to maintain the consistency of the repository, the group manager
121 * should remove users from the group before removing the group itself.
122 *
123 * @throws EntityException if the {@link Group} could not be removed.
124 * @throws UnsupportedOperationException if {@link #isReadOnly(Group)} returns true.
125 */
126 void removeGroup(Group group) throws EntityException;
127
128 /**
129 * Adds the user to the specified group.
130 * <p/>
131 * If the user is not in this repository, and {@link #supportsExternalMembership()}
132 * returns <code>true</code>, the user will be added as an external user.
133 *
134 * @throws UnsupportedOperationException if {@link #isReadOnly(Group)} returns true.
135 * @throws IllegalArgumentException if the group is not handled by this group manager
136 * or the group is <tt>null</tt>.
137 */
138 void addMembership(Group group, User user) throws EntityException, IllegalArgumentException;
139
140 /**
141 * Returns true if the user is a member of the specified group.
142 * <p/>
143 * If the user is not in this repository, and {@link #supportsExternalMembership()}
144 * returns <code>true</code>, external members will be checked as well.
145 * <p/>
146 * If the group is not handled by this manager, returns false.
147
148 * @return true if the user is a member of the specified group, otherwise false.
149 */
150 boolean hasMembership(Group group, User user) throws EntityException;
151
152 /**
153 * Removes the user from the specified group.
154 *
155 * @throws EntityException if the membership could not be removed.
156 * @throws UnsupportedOperationException if {@link GroupManager#isReadOnly(Group)}
157 * returns true.
158 * @throws IllegalArgumentException if the group is not handled by this manager
159 */
160 void removeMembership(Group group, User user) throws EntityException, IllegalArgumentException;
161
162 /**
163 * Returns <code>true</code> if the repository supports users in other
164 * repositories being members of groups in this repository.
165 * <p/>
166 * Typically this is true of an application-specific Hibernate repository, but
167 * not of a company's LDAP server. It is designed to allow the LDAP users to
168 * be members of the application's groups for flexible application-level
169 * security.
170 *
171 * @return true if users from other repositories can be granted membership
172 * to groups in this repository, otherwise false.
173 */
174 boolean supportsExternalMembership() throws EntityException;
175
176 /**
177 * Returns <code>true</code> if the specified group and membership of the
178 * specified group cannot be modified in the repository.
179 * <p/>
180 * If this returns <code>true</code>, invoking methods which attempt to
181 * modify the group or membership of the group will fail with
182 * {@link UnsupportedOperationException}.
183 *
184 * @return true if the group and membership of the group cannot be modified,
185 * otherwise false.
186 */
187 boolean isReadOnly(Group group) throws EntityException;
188 }