001/**
002 * Copyright 2005-2018 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.kew.api.rule;
017
018import org.joda.time.DateTime;
019import org.kuali.rice.core.api.criteria.QueryByCriteria;
020import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
021import org.kuali.rice.core.api.exception.RiceIllegalStateException;
022import org.kuali.rice.core.api.util.jaxb.DateTimeAdapter;
023import org.kuali.rice.kew.api.KewApiConstants;
024import org.springframework.cache.annotation.Cacheable;
025
026import javax.jws.WebMethod;
027import javax.jws.WebParam;
028import javax.jws.WebResult;
029import javax.jws.WebService;
030import javax.jws.soap.SOAPBinding;
031import javax.xml.bind.annotation.XmlElement;
032import javax.xml.bind.annotation.XmlElementWrapper;
033import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
034import java.util.List;
035
036@WebService(name = "ruleService", targetNamespace = KewApiConstants.Namespaces.KEW_NAMESPACE_2_0)
037@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
038public interface RuleService {
039    /**
040     * gets a Rule identified by the passed in id
041     *
042     * @param id unique id for the Rule
043     *
044     * @return Rule with the passed in unique id
045     *
046     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code id} is null
047     * @throws org.kuali.rice.core.api.exception.RiceIllegalStateException if Rule does not exist
048     */
049    @WebMethod(operationName = "getRule")
050    @WebResult(name = "rule")
051    @Cacheable(value=Rule.Cache.NAME, key="'id=' + #p0")
052        Rule getRule(@WebParam(name="id") String id)
053        throws RiceIllegalArgumentException, RiceIllegalStateException;
054
055    /**
056     * gets a Rule identified by the passed in rule name
057     *
058     * @param name name of the Rule
059     *
060     * @return Rule with the passed in unique id
061     *
062     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code name} is null
063     * @throws org.kuali.rice.core.api.exception.RiceIllegalStateException if Rule does not exist
064     */
065    @WebMethod(operationName = "getRuleByName")
066    @WebResult(name = "rule")
067    @Cacheable(value=Rule.Cache.NAME, key="'name=' + #p0")
068        Rule getRuleByName(@WebParam(name="name") String name)
069        throws RiceIllegalArgumentException, RiceIllegalStateException;
070
071    /**
072     * gets a list of Rules with the specified templateId
073     *
074     * @param templateId unique id for the Rule
075     *
076     * @return Rules with the passed in templateId, or an empty list if none exist
077     *
078     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code templateId} is null
079     */
080    @WebMethod(operationName = "getRuleByTemplateId")
081    @WebResult(name = "rules")
082    @XmlElementWrapper(name = "rules", required = true)
083    @XmlElement(name = "rule", required = true)
084    @Cacheable(value=Rule.Cache.NAME, key="'templateId=' + #p0")
085        List<Rule> getRulesByTemplateId(@WebParam(name="templateId") String templateId)
086        throws RiceIllegalArgumentException;
087
088    /**
089     * Gets a list of Rules with the specified templateId and documentTypeName.  Scales up the hierarchy of
090     * documentTypes
091     *
092     * @param templateName unique name for the Rule Template.  Cannot be null or empty
093     * @param documentTypeName documentTypeName for Rule.  Cannot be null or empty
094     *
095     * @return Rules with the passed in templateId, documentTypeName (or parent document type)or an empty list if none exist
096     *
097     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code id} is null
098     */
099    @WebMethod(operationName = "getRulesByTemplateNameAndDocumentTypeName")
100    @WebResult(name = "rules")
101    @XmlElementWrapper(name = "rules", required = true)
102    @XmlElement(name = "rule", required = true)
103    @Cacheable(value=Rule.Cache.NAME, key="'templateName=' + #p0 + '|' + 'documentTypeName=' + #p1")
104        List<Rule> getRulesByTemplateNameAndDocumentTypeName(@WebParam(name = "templateName") String templateName,
105            @WebParam(name = "documentTypeName") String documentTypeName)
106        throws RiceIllegalArgumentException;
107
108    /**
109     * Gets a list of Rules with the specified templateId and documentTypeName.  Scales up the hierarchy of
110     * documentTypes
111     *
112     * @param templateName unique name for the Rule Template.  Cannot be null or empty
113     * @param documentTypeName documentTypeName for Rule.  Cannot be null or empty
114     * @param effectiveDate date for rule effectiveness. Can be null.  If null, current time is used.
115     *
116     * @return Rules with the passed in templateId, documentTypeName (or parent document type)or an empty list if none exist
117     *
118     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code id} is null
119     */
120    @WebMethod(operationName = "getRulesByTemplateNameAndDocumentTypeNameAndEffectiveDate")
121    @WebResult(name = "rules")
122    @XmlElementWrapper(name = "rules", required = true)
123    @XmlElement(name = "rule", required = true)
124        List<Rule> getRulesByTemplateNameAndDocumentTypeNameAndEffectiveDate(@WebParam(name = "templateName") String templateName,
125            @WebParam(name = "documentTypeName") String documentTypeName,
126            @XmlJavaTypeAdapter(value = DateTimeAdapter.class) @WebParam(name = "effectiveDate") DateTime effectiveDate)
127        throws RiceIllegalArgumentException;
128
129    /**
130     * Query for rules based on the given search criteria which is a Map of rule field names to values.
131     *
132     * <p>
133     * This method returns it's results as a List of Rules that match the given search criteria.
134     * </p>
135     *
136     * @param queryByCriteria the criteria.  Cannot be null.
137     * @return a list of Rule objects in which the given criteria match Rule properties.  An empty list is returned if an invalid or
138     *         non-existent criteria is supplied.
139     */
140    @WebMethod(operationName = "findRules")
141    @WebResult(name = "findRules")
142    RuleQueryResults findRules(@WebParam(name = "query") QueryByCriteria queryByCriteria)
143        throws RiceIllegalArgumentException;
144
145    /**
146     * Executes a simulation of a document to get all previous and future route information
147     *
148     * @param reportCriteria criteria for the rule report to follow
149     *
150     * @return list of Rules representing the results of the rule report
151     *
152     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code reportCriteria} is null
153     */
154    @WebMethod(operationName = "ruleReport")
155    @WebResult(name = "rules")
156    @XmlElementWrapper(name = "rules", required = true)
157    @XmlElement(name = "rule", required = true)
158    List<Rule> ruleReport(
159            @WebParam(name = "ruleCriteria") RuleReportCriteria reportCriteria)
160            throws RiceIllegalArgumentException;
161
162
163    /**
164     * gets a RuleTemplate identified by the passed in id
165     *
166     * @param id unique id for the RuleTemplate
167     *
168     * @return RuleTemplate with the passed in unique id
169     *
170     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code id} is null
171     * @throws org.kuali.rice.core.api.exception.RiceIllegalStateException if RuleTemplate does not exist
172     */
173    @WebMethod(operationName = "getRuleTemplate")
174    @WebResult(name = "ruleTemplate")
175    @Cacheable(value=RuleTemplate.Cache.NAME, key="'id=' + #p0")
176    RuleTemplate getRuleTemplate(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
177
178    /**
179     * gets a RuleTemplate identified by the passed in name
180     *
181     * @param name unique name for the RuleTemplate
182     *
183     * @return RuleTemplate with the passed in unique name
184     *
185     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code name} is null
186     * @throws org.kuali.rice.core.api.exception.RiceIllegalStateException if RuleTemplate does not exist
187     */
188    @WebMethod(operationName = "getRuleTemplateByName")
189    @WebResult(name = "ruleTemplate")
190    @Cacheable(value=RuleTemplate.Cache.NAME, key="'name=' + #p0")
191    RuleTemplate getRuleTemplateByName(@WebParam(name = "name") String name) throws RiceIllegalArgumentException;
192
193    /**
194     * Query for rules based on the given search criteria which is a Map of ruleTemplate field names to values.
195     *
196     * <p>
197     * This method returns it's results as a List of RuleTemplates that match the given search criteria.
198     * </p>
199     *
200     * @param queryByCriteria the criteria.  Cannot be null.
201     * @return a list of RuleTemplate objects in which the given criteria match RuleTemplate properties.
202     * An empty list is returned if an invalid or non-existent criteria is supplied.
203     */
204    @WebMethod(operationName = "findRuleTemplates")
205    @WebResult(name = "findRuleTemplates")
206    RuleTemplateQueryResults findRuleTemplates(@WebParam(name = "query") QueryByCriteria queryByCriteria)
207        throws RiceIllegalArgumentException;
208
209    /**
210     * gets a RuleResponsibility identified by the passed in responsibilityId
211     *
212     * @param responsibilityId unique id for the RuleResponsibility
213     *
214     * @return RuleResponsibility with the passed in unique responsibilityId
215     *
216     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code id} is null
217     * @throws org.kuali.rice.core.api.exception.RiceIllegalStateException if RuleResponsibility does not exist
218     */
219    @WebMethod(operationName = "getRuleResponsibility")
220    @WebResult(name = "ruleResponsibility")
221    @Cacheable(value=RuleResponsibility.Cache.NAME, key="'responsibilityId=' + #p0")
222    RuleResponsibility getRuleResponsibility(@WebParam(name = "responsibilityId") String responsibilityId) throws RiceIllegalArgumentException;
223
224    /**
225     * gets a RuleDelegations identified by the passed in id for responsibility
226     *
227     * @param id unique id for the RuleDelegation's Responsibility
228     *
229     * @return List of RuleDelegations with the provided ReponsibilityId.  Returns an empty list if none exist.
230     *
231     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code id} is null
232     */
233    @WebMethod(operationName = "getRuleDelegationsByResponsiblityId")
234    @XmlElementWrapper(name = "ruleDelegations", required = true)
235    @XmlElement(name = "ruleDelegation", required = false)
236    @WebResult(name = "ruleDelegations")
237    @Cacheable(value=RuleDelegation.Cache.NAME, key="'id=' + #p0")
238        List<RuleDelegation> getRuleDelegationsByResponsibiltityId(@WebParam(name="id") String id)
239        throws RiceIllegalArgumentException;
240}