001 /**
002 * Copyright 2005-2014 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.kuali.rice.kim.api.responsibility;
017
018 import org.kuali.rice.core.api.criteria.QueryByCriteria;
019 import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
020 import org.kuali.rice.core.api.exception.RiceIllegalStateException;
021 import org.kuali.rice.core.api.util.jaxb.MapStringStringAdapter;
022 import org.kuali.rice.kim.api.KimConstants;
023 import org.kuali.rice.kim.api.common.template.Template;
024 import org.kuali.rice.kim.api.common.template.TemplateQueryResults;
025 import org.springframework.cache.annotation.CacheEvict;
026 import org.springframework.cache.annotation.Cacheable;
027
028 import javax.jws.WebMethod;
029 import javax.jws.WebParam;
030 import javax.jws.WebResult;
031 import javax.jws.WebService;
032 import javax.jws.soap.SOAPBinding;
033 import javax.xml.bind.annotation.XmlElement;
034 import javax.xml.bind.annotation.XmlElementWrapper;
035 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
036 import java.util.List;
037 import java.util.Map;
038
039 /**
040 * This service provides operations for determining what responsibility actions
041 * a principal has and for querying about responsibility data. It also provides several
042 * write operations.
043 *
044 * <p>
045 * A responsibility represents an action that a principal is requested to
046 * take. This is used for defining workflow actions (such as approve,
047 * acknowledge, fyi) that the principal has the responsibility to take. The
048 * workflow engine integrates with this service to provide responsibility-driven routing.
049 * <p/>
050 *
051 * <p>
052 * A responsibility is very similar to a permission in a couple of ways.
053 * First of all, responsibilities are always granted to a role, never assigned
054 * directly to a principal or group. Furthermore, in a similar fashion to
055 * permissions, a role has the concept of a responsibility template. The
056 * responsibility template specifies what additional responsibility details
057 * need to be defined when the responsibility is created.
058 * <p/>
059 *
060 * @author Kuali Rice Team (rice.collab@kuali.org)
061 */
062 @WebService(name = "responsibilityService", targetNamespace = KimConstants.Namespaces.KIM_NAMESPACE_2_0)
063 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
064 public interface ResponsibilityService {
065
066 /**
067 * This will create a {@link Responsibility} exactly like the responsibility passed in.
068 *
069 * @param responsibility the responsibility to create
070 * @return the id of the newly created object. will never be null.
071 * @throws RiceIllegalArgumentException if the responsibility is null
072 * @throws RiceIllegalStateException if the responsibility is already existing in the system
073 */
074 @WebMethod(operationName="createResponsibility")
075 @WebResult(name = "responsibility")
076 @CacheEvict(value={Responsibility.Cache.NAME, Template.Cache.NAME + "{Responsibility}"}, allEntries = true)
077 Responsibility createResponsibility(@WebParam(name = "responsibility") Responsibility responsibility)
078 throws RiceIllegalArgumentException, RiceIllegalStateException;
079
080 /**
081 * This will up ev a {@link Responsibility}.
082 *
083 * @param responsibility the responsibility to update
084 * @throws RiceIllegalArgumentException if the responsibility is null
085 * @throws RiceIllegalStateException if the responsibility does not exist in the system
086 */
087 @WebMethod(operationName="updateResponsibility")
088 @WebResult(name = "responsibility")
089 @CacheEvict(value={Responsibility.Cache.NAME, Template.Cache.NAME + "{Responsibility}"}, allEntries = true)
090 Responsibility updateResponsibility(@WebParam(name = "responsibility") Responsibility responsibility)
091 throws RiceIllegalArgumentException, RiceIllegalStateException;
092
093 /**
094 * Gets a {@link Responsibility} from an id.
095 *
096 * <p>
097 * This method will return null if the responsibility does not exist.
098 * </p>
099 *
100 * @param id the unique id to retrieve the responsibility by. cannot be null or blank.
101 * @return a {@link Responsibility} or null
102 * @throws RiceIllegalArgumentException if the id is null or blank
103 */
104 @WebMethod(operationName = "getResponsibility")
105 @WebResult(name = "responsibility")
106 @Cacheable(value=Responsibility.Cache.NAME, key="'id=' + #p0")
107 Responsibility getResponsibility(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
108
109 /**
110 * Finds a {@link Responsibility} for namespaceCode and name.
111 *
112 * @param namespaceCode the namespace code. cannot be null or blank.
113 * @param name the responsibility name. cannot be null or blank.
114 * @return a {@link Responsibility} or null
115 * @throws RiceIllegalArgumentException if the id or namespaceCode is null or blank
116 */
117 @WebMethod(operationName = "findRespByNamespaceCodeAndName")
118 @WebResult(name = "responsibility")
119 @Cacheable(value=Responsibility.Cache.NAME, key="'namespaceCode=' + #p0 + '|' + 'name=' + #p1")
120 Responsibility findRespByNamespaceCodeAndName(@WebParam(name = "namespaceCode") String namespaceCode,
121 @WebParam(name = "name") String name) throws RiceIllegalArgumentException;
122 /**
123 * Gets a {@link Template} from an id.
124 *
125 * <p>
126 * This method will return null if the template does not exist.
127 * </p>
128 *
129 * @param id the unique id to retrieve the template by. cannot be null or blank.
130 * @return a {@link Template} or null
131 * @throws RiceIllegalArgumentException if the id is null or blank
132 */
133 @WebMethod(operationName = "getResponsibilityTemplate")
134 @WebResult(name = "template")
135 @Cacheable(value=Template.Cache.NAME + "{Responsibility}", key="'id=' + #p0")
136 Template getResponsibilityTemplate(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
137
138 /**
139 * Finds a {@link Template} for namespaceCode and name.
140 *
141 * @param namespaceCode the namespace code. cannot be null or blank.
142 * @param name the template name. cannot be null or blank.
143 * @return a {@link Template} or null
144 * @throws RiceIllegalArgumentException if the id or namespaceCode is null or blank
145 */
146 @WebMethod(operationName = "findRespTemplateByNamespaceCodeAndName")
147 @WebResult(name = "template")
148 @Cacheable(value=Template.Cache.NAME + "{Responsibility}", key="'namespaceCode=' + #p0 + '|' + 'name=' + #p1")
149 Template findRespTemplateByNamespaceCodeAndName(@WebParam(name = "namespaceCode") String namespaceCode,
150 @WebParam(name = "name") String name) throws RiceIllegalArgumentException;
151 /**
152 * Checks in a given principal id has a responsibility using the passed in responsibility information.
153 *
154 * @param principalId the principal id to check. cannot be null or blank.
155 * @param namespaceCode the namespace code. cannot be null or blank.
156 * @param respName the responsibility name. cannot be null or blank.
157 * @param qualification the qualification for the responsibility. cannot be null.
158 * @return true is principal has responsibility
159 * @throws RiceIllegalArgumentException if the principalId, namespaceCode, respName is null or blank
160 * @throws RiceIllegalArgumentException if the qualification is null
161 */
162 @WebMethod(operationName = "hasResponsibility")
163 @WebResult(name = "result")
164 @Cacheable(value= Responsibility.Cache.NAME,
165 key="'{hasResponsibility}' + 'principalId=' + #p0 + '|' + 'namespaceCode=' + #p1 + '|' + 'respName=' + #p2 + '|' + 'qualification=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).mapKey(#p3)",
166 condition="!T(org.kuali.rice.kim.api.cache.KimCacheUtils).isResponsibilityAssignedToDynamicRole(#p1, #p2)")
167 boolean hasResponsibility(@WebParam(name = "principalId") String principalId,
168 @WebParam(name = "namespaceCode") String namespaceCode,
169 @WebParam(name = "respName") String respName,
170 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
171 @WebParam(name = "qualification") Map<String, String> qualification) throws RiceIllegalArgumentException;
172
173 /**
174 * Checks in a given principal id has a responsibility using the passed in responsibility <b>template</b> information.
175 *
176 * @param principalId the principal id to check. cannot be null or blank.
177 * @param namespaceCode the namespace code. cannot be null or blank.
178 * @param respTemplateName the responsibility template name. cannot be null or blank.
179 * @param qualification the qualification for the responsibility. cannot be null.
180 * @param respDetails the responsibility details. cannot be null.
181 * @return true is principal has responsibility
182 * @throws RiceIllegalArgumentException if the principalId, namespaceCode, respName is null or blank
183 * @throws RiceIllegalArgumentException if the qualification or responsibilityDetails is null
184 */
185 @WebMethod(operationName = "hasResponsibilityByTemplate")
186 @WebResult(name = "result")
187 @Cacheable(value= Responsibility.Cache.NAME,
188 key="'{hasResponsibilityByTemplate}' + 'principalId=' + #p0 + '|' + 'namespaceCode=' + #p1 + '|' + 'respTemplateName=' + #p2 + '|' + 'qualification=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).mapKey(#p3) + '|' + 'respDetails=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).mapKey(#p4)",
189 condition="!T(org.kuali.rice.kim.api.cache.KimCacheUtils).isResponsibilityTemplateAssignedToDynamicRole(#p1, #p2)")
190 boolean hasResponsibilityByTemplate(@WebParam(name = "principalId") String principalId,
191 @WebParam(name = "namespaceCode") String namespaceCode,
192 @WebParam(name = "respTemplateName") String respTemplateName,
193 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) @WebParam(
194 name = "qualification") Map<String, String> qualification,
195 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) @WebParam(
196 name = "respDetails") Map<String, String> respDetails) throws RiceIllegalArgumentException;
197
198 /**
199 * Gets a List of {@link ResponsibilityAction} based on passed in responsibility information.
200 *
201 * @param namespaceCode the namespace code. cannot be null or blank.
202 * @param respName the responsibility name. cannot be null or blank.
203 * @param qualification the qualification for the responsibility. cannot be null.
204 * @return an immutable list of ResponsibilityAction. Will not return null.
205 * @throws RiceIllegalArgumentException if the namespaceCode, respName is null or blank
206 * @throws RiceIllegalArgumentException if the qualification or respDetails is null
207 */
208 @WebMethod(operationName = "getResponsibilityActions")
209 @XmlElementWrapper(name = "responsibilityActions", required = true)
210 @XmlElement(name = "responsibilityAction", required = false)
211 @WebResult(name = "responsibilityActions")
212 List<ResponsibilityAction> getResponsibilityActions(@WebParam(name = "namespaceCode") String namespaceCode,
213 @WebParam(name = "respName") String respName,
214 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
215 @WebParam(name = "qualification") Map<String, String> qualification) throws RiceIllegalArgumentException;
216
217 /**
218 * Gets a List of {@link ResponsibilityAction} based on passed in responsibility template information.
219 *
220 * @param namespaceCode the namespace code. cannot be null or blank.
221 * @param respTemplateName the responsibility name. cannot be null or blank.
222 * @param qualification the qualification for the responsibility. cannot be null.
223 * @param respDetails the responsibility details. can be null.
224 * @return an immutable list of ResponsibilityAction. Will not return null.
225 * @throws RiceIllegalArgumentException if the namespaceCode, respName is null or blank
226 * @throws RiceIllegalArgumentException if the qualification or respDetails is null
227 */
228 @WebMethod(operationName = "getResponsibilityActionsByTemplate")
229 @XmlElementWrapper(name = "responsibilityActions", required = true)
230 @XmlElement(name = "responsibilityAction", required = false)
231 @WebResult(name = "responsibilityActions")
232 List<ResponsibilityAction> getResponsibilityActionsByTemplate(
233 @WebParam(name = "namespaceCode") String namespaceCode,
234 @WebParam(name = "responsibilityTemplateName") String respTemplateName,
235 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) @WebParam(
236 name = "qualification") Map<String, String> qualification,
237 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) @WebParam(
238 name = "respDetails") Map<String, String> respDetails) throws RiceIllegalArgumentException;
239
240 /**
241 * Gets a List of roleIds that the responsibility is associated with.
242 *
243 * @param id the unique id to retrieve the roleIds for. cannot be null or blank.
244 * @return an immutable list of roleIds. Will not return null.
245 * @throws RiceIllegalArgumentException if the id is null or blank or if the qualification is null
246 */
247 @WebMethod(operationName = "getRoleIdsForResponsibility")
248 @XmlElementWrapper(name = "roleIds", required = true)
249 @XmlElement(name = "roleId", required = false)
250 @WebResult(name = "roleIds")
251 @Cacheable(value=Responsibility.Cache.NAME, key="'{getRoleIdsForResponsibility}' + 'id=' + #p0")
252 List<String> getRoleIdsForResponsibility(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
253
254 /**
255 * This method find Responsibilities based on a query criteria. The criteria cannot be null.
256 *
257 * @param queryByCriteria the criteria. Cannot be null.
258 * @return query results. will never return null.
259 * @throws RiceIllegalArgumentException if the queryByCriteria is null
260 */
261 @WebMethod(operationName = "findResponsibilities")
262 @WebResult(name = "results")
263 ResponsibilityQueryResults findResponsibilities(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
264
265
266 /**
267 * This method find Responsibility Templates based on a query criteria. The criteria cannot be null.
268 *
269 * @param queryByCriteria the criteria. Cannot be null.
270 * @return query results. will never return null.
271 * @throws RiceIllegalArgumentException if the queryByCriteria is null
272 */
273 @WebMethod(operationName = "findResponsibilityTemplates")
274 @WebResult(name = "results")
275 TemplateQueryResults findResponsibilityTemplates(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
276
277 /**
278 * Return the responsibilities for the given unique combination of namespace,
279 * and responsibility template name.
280 *
281 * @since 2.1.1
282 * @param namespaceCode namespace code for permission. cannot be null or blank.
283 * @param templateName name of permission template. cannot be null or blank.
284 * @return a list of {@link org.kuali.rice.kim.api.permission.Permission} or null
285 * @throws RiceIllegalArgumentException if the namespaceCode or name is null or blank
286 */
287 @WebMethod(operationName = "findResponsibilitiesByTemplate")
288 @XmlElementWrapper(name = "responsibilities", required = true)
289 @XmlElement(name = "responsibility", required = false)
290 @WebResult(name = "responsibilities")
291 @Cacheable(value=Responsibility.Cache.NAME, key="'namespaceCode=' + #p1 + '|' + 'templateName=' + #p2")
292 List<Responsibility> findResponsibilitiesByTemplate(
293 @WebParam(name = "namespaceCode") String namespaceCode,
294 @WebParam(name = "templateName") String templateName)
295 throws RiceIllegalArgumentException;
296 }