001 /**
002 * Copyright 2005-2012 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.kew.api.rule;
017
018 import org.joda.time.DateTime;
019 import org.kuali.rice.core.api.criteria.QueryByCriteria;
020 import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
021 import org.kuali.rice.core.api.exception.RiceIllegalStateException;
022 import org.kuali.rice.core.api.util.jaxb.DateTimeAdapter;
023 import org.kuali.rice.kew.api.KewApiConstants;
024 import org.springframework.cache.annotation.Cacheable;
025
026 import javax.jws.WebMethod;
027 import javax.jws.WebParam;
028 import javax.jws.WebResult;
029 import javax.jws.WebService;
030 import javax.jws.soap.SOAPBinding;
031 import javax.xml.bind.annotation.XmlElement;
032 import javax.xml.bind.annotation.XmlElementWrapper;
033 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
034 import 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)
038 public 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 }