001/**
002 * Copyright 2005-2015 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 */
016package org.kuali.rice.kim.api.responsibility;
017
018import org.kuali.rice.core.api.criteria.QueryByCriteria;
019import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
020import org.kuali.rice.core.api.exception.RiceIllegalStateException;
021import org.kuali.rice.core.api.util.jaxb.MapStringStringAdapter;
022import org.kuali.rice.kim.api.KimConstants;
023import org.kuali.rice.kim.api.common.template.Template;
024import org.kuali.rice.kim.api.common.template.TemplateQueryResults;
025import org.springframework.cache.annotation.CacheEvict;
026import org.springframework.cache.annotation.Cacheable;
027
028import javax.jws.WebMethod;
029import javax.jws.WebParam;
030import javax.jws.WebResult;
031import javax.jws.WebService;
032import javax.jws.soap.SOAPBinding;
033import javax.xml.bind.annotation.XmlElement;
034import javax.xml.bind.annotation.XmlElementWrapper;
035import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
036import java.util.List;
037import 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)
064public 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}