1 /*
2 * Copyright 2007-2009 The Kuali Foundation
3 *
4 * Licensed under the Educational Community 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.opensource.org/licenses/ecl2.php
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 package org.kuali.rice.kim.service;
17
18 import java.util.Collection;
19 import java.util.List;
20 import java.util.Map;
21
22 import javax.jws.WebParam;
23 import javax.jws.WebService;
24 import javax.jws.soap.SOAPBinding;
25 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
26
27 import org.kuali.rice.core.jaxb.MapStringStringAdapter;
28 import org.kuali.rice.kim.bo.Group;
29 import org.kuali.rice.kim.bo.group.dto.GroupInfo;
30 import org.kuali.rice.kim.bo.group.dto.GroupMembershipInfo;
31 import org.kuali.rice.kim.util.KIMWebServiceConstants;
32
33 /**
34 *
35 * This service provides operations for checking group membership and querying for group data.
36 *
37 * <p>A group is a collection of principals. It's membership consists of direct principal
38 * assignment and/or nested group membership. All groups are uniquely identified by a namespace
39 * code plus a name.
40 *
41 * <p>As mentioned previously, groups support nested group membership. A principal or group is
42 * considered to be a "member" of a group if it is either directly assigned to the group or
43 * indirectly assigned (via a nested group membership). A principal or group is said to be a
44 * "direct" member of another group only if it is directly assigned as a member of the group,
45 * and not via a nested group assignment.
46 *
47 * <p>This service provides read-only operations. For write operations, see
48 * {@link GroupUpdateService}.
49 *
50 * @see GroupUpdateService
51 *
52 * @author Kuali Rice Team (rice.collab@kuali.org)
53 *
54 */
55 @WebService(name = KIMWebServiceConstants.GroupService.WEB_SERVICE_NAME, targetNamespace = KIMWebServiceConstants.MODULE_TARGET_NAMESPACE)
56 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
57 public interface GroupService {
58
59 /** Get all the groups for a given principal.
60 *
61 * <p>This will include all groups directly assigned as well as those inferred
62 * by the fact that they are members of higher level groups.
63 */
64 List<GroupInfo> getGroupsForPrincipal(@WebParam(name="principalId") String principalId);
65
66 /**
67 * Get all the groups within a namespace for a given principal.
68 *
69 * <p>This is the same as the {@link #getGroupsForPrincipal(String)} method except that
70 * the results will be filtered by namespace after retrieval.
71 */
72 List<GroupInfo> getGroupsForPrincipalByNamespace(@WebParam(name="principalId") String principalId, @WebParam(name="namespaceCode") String namespaceCode);
73
74 /**
75 * Query for groups based on the given search criteria which is a Map of group field names to values.
76 *
77 * <p>This method returns it's results as a List of group ids that match the given search criteria.
78 */
79 List<String> lookupGroupIds(@WebParam(name="searchCriteria") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> searchCriteria);
80
81 /**
82 * Query for groups based on the given search criteria which is a Map of group field names to values.
83 *
84 * <p>This method returns it's results as a List of GroupInfo objects that match the given search criteria.
85 */
86 List<? extends Group> lookupGroups(@WebParam(name="searchCriteria") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> searchCriteria);
87
88 /**
89 * Get the group by the given id.
90 */
91 GroupInfo getGroupInfo(@WebParam(name="groupId") String groupId);
92
93 /**
94 * Get the group by the given namesapce code and name.
95 */
96 GroupInfo getGroupInfoByName(@WebParam(name="namespaceCode") String namespaceCode, @WebParam(name="groupName") String groupName);
97
98 /**
99 * Gets all groups for the given collection of group ids.
100 *
101 * <p>The result is a Map containing the group id as the key and the group info as the value.
102 */
103 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, GroupInfo> getGroupInfos(@WebParam(name="groupIds") Collection<String> groupIds);
104
105 /**
106 * Check whether the give principal is a member of the group.
107 *
108 * <p>This will also return true if the principal is a member of a groups assigned to this group.
109 */
110 boolean isMemberOfGroup(@WebParam(name="principalId") String principalId, @WebParam(name="groupId") String groupId);
111
112 /**
113 * Check whether the give principal is a member of the group.
114 *
115 * <p>This will not recurse into contained groups.
116 */
117 boolean isDirectMemberOfGroup(@WebParam(name="principalId") String principalId, @WebParam(name="groupId") String groupId);
118
119 /**
120 * Get all the groups for the given principal. Recurses into parent groups
121 * to provide a comprehensive list.
122 */
123 List<String> getGroupIdsForPrincipal(@WebParam(name="principalId") String principalId);
124
125 /**
126 * Get all the groups for the given principal in the given namespace. Recurses into
127 * parent groups to provide a comprehensive list.
128 */
129 List<String> getGroupIdsForPrincipalByNamespace(@WebParam(name="principalId") String principalId, @WebParam(name="namespaceCode") String namespaceCode);
130
131 /**
132 * Get the groupIds in which the principal has direct membership only.
133 */
134 List<String> getDirectGroupIdsForPrincipal(@WebParam(name="principalId") String principalId);
135
136
137 /**
138 * Check whether the group identified by groupMemberId is a member of the group
139 * identified by groupId. This will recurse through all groups.
140 */
141 boolean isGroupMemberOfGroup(@WebParam(name="groupMemberId") String groupMemberId, @WebParam(name="groupId") String groupId);
142
143 /**
144 * Checks if the group with the given id is active. Returns true if it is, false otherwise.
145 */
146 boolean isGroupActive( @WebParam(name="groupId") String groupId );
147
148 /**
149 * Get all the principals of the given group. Recurses into contained groups
150 * to provide a comprehensive list.
151 */
152 List<String> getMemberPrincipalIds(@WebParam(name="groupId") String groupId);
153
154 /**
155 * Get all the principals directly assigned to the given group.
156 */
157 List<String> getDirectMemberPrincipalIds(@WebParam(name="groupId") String groupId);
158
159 /**
160 * Get all the groups contained by the given group. Recurses into contained groups
161 * to provide a comprehensive list.
162 */
163 List<String> getMemberGroupIds( @WebParam(name="groupId") String groupId );
164
165 /**
166 * Get all the groups which are direct members of the given group.
167 */
168 List<String> getDirectMemberGroupIds( @WebParam(name="groupId") String groupId );
169
170 /**
171 * Get the groups which are parents of the given group.
172 *
173 * <p>This will recurse into groups above the given group and build a complete
174 * list of all groups included above this group.
175 */
176 List<String> getParentGroupIds(@WebParam(name="groupId") String groupId);
177
178 /**
179 * Get the groupIds which that are directly above this group.
180 */
181 List<String> getDirectParentGroupIds(@WebParam(name="groupId") String groupId);
182
183 /**
184 * Get all the attributes of the given group.
185 */
186 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String,String> getGroupAttributes( @WebParam(name="groupId") String groupId );
187
188 /**
189 * Get the membership info for the members of all the groups with the given group ids.
190 *
191 * <p>The collection of GroupMembershipInfo will contain members for all the groups in no defined order.
192 * The values returned may or may not be grouped by group id.
193 */
194 Collection<GroupMembershipInfo> getGroupMembers( @WebParam(name="groupIds") List<String> groupIds );
195
196 /**
197 * Get the membership info for the members of the group with the given id.
198 *
199 * <p>Only GroupMembershipInfo for direct group members is returned.
200 */
201 Collection<GroupMembershipInfo> getGroupMembersOfGroup( @WebParam(name="groupId") String groupId );
202 }