View Javadoc
1   /**
2    * Copyright 2005-2015 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.krms.api.repository;
17  
18  import org.kuali.rice.core.api.criteria.QueryByCriteria;
19  import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
20  import org.kuali.rice.krms.api.KrmsConstants;
21  import org.kuali.rice.krms.api.repository.agenda.AgendaDefinition;
22  import org.kuali.rice.krms.api.repository.agenda.AgendaItemDefinition;
23  import org.kuali.rice.krms.api.repository.context.ContextDefinition;
24  import org.kuali.rice.krms.api.repository.language.NaturalLanguageUsage;
25  import org.kuali.rice.krms.api.repository.proposition.PropositionDefinition;
26  import org.kuali.rice.krms.api.repository.reference.ReferenceObjectBinding;
27  import org.kuali.rice.krms.api.repository.rule.RuleDefinition;
28  import org.springframework.cache.annotation.CacheEvict;
29  import org.springframework.cache.annotation.Cacheable;
30  
31  import javax.jws.WebMethod;
32  import javax.jws.WebParam;
33  import javax.jws.WebResult;
34  import javax.jws.WebService;
35  import javax.jws.soap.SOAPBinding;
36  import javax.xml.bind.annotation.XmlElement;
37  import javax.xml.bind.annotation.XmlElementWrapper;
38  import java.util.List;
39  import java.util.Set;
40  import org.kuali.rice.krms.api.repository.action.ActionDefinition;
41  import org.kuali.rice.krms.api.repository.agenda.AgendaTreeDefinition;
42  import org.kuali.rice.krms.api.repository.context.ContextSelectionCriteria;
43  import org.kuali.rice.krms.api.repository.language.NaturalLanguageTemplate;
44  
45  /**
46   * The rule maintenance service operations facilitate management of rules and
47   * associated information.
48   *
49   * @author Kuali Rice Team (rice.collab@kuali.org)
50   */
51  @WebService(name = "ruleManagementService", targetNamespace = KrmsConstants.Namespaces.KRMS_NAMESPACE_2_0)
52  @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL,
53          parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
54  public interface RuleManagementService extends TranslateBusinessMethods {
55  
56      /**
57       * Create RefObject-KRMS object binding
58       *
59       * @param referenceObjectDefinition  data for the new ReferenceObjectBinding to be created
60       * @return newly created ReferenceObjectBinding
61       * @throws RiceIllegalArgumentException if the given referenceObjectDefinition
62       *                                      is null or invalid
63       */
64      @WebMethod(operationName = "createReferenceObjectBinding")
65      @WebResult(name = "referenceObjectBinding")
66      @CacheEvict(value={ReferenceObjectBinding.Cache.NAME}, allEntries = true)
67      public ReferenceObjectBinding createReferenceObjectBinding(@WebParam(
68              name = "referenceObjectDefinition") ReferenceObjectBinding referenceObjectDefinition) throws RiceIllegalArgumentException;
69  
70      /**
71       * Retrieve referenceObjectBinding  given a specific id
72       *
73       * @param id identifier of the ReferenceObjectBinding to be retrieved
74       * @return a ReferenceObjectBinding with the given id value
75       * @throws RiceIllegalArgumentException if the given  id is blank or
76       *                                      invalid
77       */
78      @WebMethod(operationName = "getReferenceObjectBinding")
79      @WebResult(name = "referenceObjectBinding")
80      @Cacheable(value= ReferenceObjectBinding.Cache.NAME, key="'id=' + #p0")
81      public ReferenceObjectBinding getReferenceObjectBinding(@WebParam(
82              name = "id") String id) throws RiceIllegalArgumentException;
83  
84      /**
85       * Retrieve list of ReferenceObjectBinding objects given ids
86       *
87       * @param ids identifiers of the ReferenceObjectBinding to be retrieved
88       * @return list of ReferenceObjectBinding objects for the given ids
89       * @throws RiceIllegalArgumentException if one or more ids in the give list
90       *                                      is blank or invalid
91       */
92      @WebMethod(operationName = "getReferenceObjectBindings")
93      @XmlElementWrapper(name = "referenceObjectBindings", required = true)
94      @XmlElement(name = "referenceObjectBinding", required = false)
95      @WebResult(name = "referenceObjectBindings")
96      @Cacheable(value= ReferenceObjectBinding.Cache.NAME, key="'ids=' + #p0")
97      List<ReferenceObjectBinding> getReferenceObjectBindings(@WebParam(
98              name = "ids") List<String> ids) throws RiceIllegalArgumentException;
99  
100     /**
101      * Retrieves list of ReferenceObjectBinding objects for the given ref obj
102      * discriminator type
103      *
104      * @param referenceObjectReferenceDiscriminatorType  reference object type
105      * @return list of ReferenceObjectBinding objects for the given discriminator
106      *         type
107      * @throws RiceIllegalArgumentException if the given  referenceObjectReferenceDiscriminatorType is
108      *                                      blank or invalid
109      */
110     @WebMethod(operationName = "findReferenceObjectBindingsByReferenceDiscriminatorType")
111     @XmlElementWrapper(name = "referenceObjectBindings", required = true)
112     @XmlElement(name = "referenceObjectBinding", required = false)
113     @WebResult(name = "referenceObjectBindings")
114     @Cacheable(value= ReferenceObjectBinding.Cache.NAME, key="'referenceObjectReferenceDiscriminatorType=' + #p0")
115     public List<ReferenceObjectBinding> findReferenceObjectBindingsByReferenceDiscriminatorType(
116             @WebParam(name = "referenceObjectReferenceDiscriminatorType") String referenceObjectReferenceDiscriminatorType) throws RiceIllegalArgumentException;
117 
118     /**
119      * Retrieves list of ReferenceObjectBinding objects for the given krms obj
120      * discriminator type
121      *
122      * @param referenceObjectKrmsDiscriminatorType  reference object type
123      * @return list of ReferenceObjectBinding objects for the given discriminator
124      *         type
125      * @throws RiceIllegalArgumentException if the given  referenceObjectKrmsDiscriminatorType is
126      *                                      blank or invalid
127      */
128     @WebMethod(operationName = "findReferenceObjectBindingsByKrmsDiscriminatorType")
129     @XmlElementWrapper(name = "referenceObjectBindings", required = true)
130     @XmlElement(name = "referenceObjectBinding", required = false)
131     @WebResult(name = "referenceObjectBindings")
132     @Cacheable(value= ReferenceObjectBinding.Cache.NAME, key="'referenceObjectKrmsDiscriminatorType=' + #p0")
133     public List<ReferenceObjectBinding> findReferenceObjectBindingsByKrmsDiscriminatorType(
134             @WebParam(name = "referenceObjectKrmsDiscriminatorType") String referenceObjectKrmsDiscriminatorType) throws RiceIllegalArgumentException;
135 
136 
137     /**
138      * Retrieves list of ReferenceObjectBinding objects for the given obj
139      * discriminator type and reference object id
140      *
141      * @param referenceObjectReferenceDiscriminatorType  reference object type
142      * @param referenceObjectId reference object id
143      * @return list of ReferenceObjectBinding objects for the given discriminator
144      *         type
145      * @throws RiceIllegalArgumentException if the given  referenceObjectKrmsDiscriminatorType or id is
146      *                                      blank or invalid
147      */
148     @WebMethod(operationName = "findReferenceObjectBindingsByReferenceObject")
149     @XmlElementWrapper(name = "referenceObjectBindings", required = true)
150     @XmlElement(name = "referenceObjectBinding", required = false)
151     @WebResult(name = "referenceObjectBindings")
152     @Cacheable(value= ReferenceObjectBinding.Cache.NAME, key="'referenceObjectReferenceDiscriminatorType=' + #p0 + '|' + 'referenceObjectId=' + #p1")
153     public List<ReferenceObjectBinding> findReferenceObjectBindingsByReferenceObject (
154             @WebParam(name = "referenceObjectReferenceDiscriminatorType") String referenceObjectReferenceDiscriminatorType,
155             @WebParam(name = "referenceObjectId") String referenceObjectId)
156             throws RiceIllegalArgumentException;
157 
158     /**
159      * Retrieves list of ReferenceObjectBinding objects for the given KRMS obj
160      * id.
161      *
162      * @param krmsObjectId identifier of the KRMS obj
163      * @return list of ReferenceObjectBinding objects for the given KRMS obj
164      * @throws RiceIllegalArgumentException if the given krmsObjectId is blank or
165      *                                      invalid
166      */
167     @WebMethod(operationName = "findReferenceObjectBindingsByKrmsObjectId")
168     @XmlElementWrapper(name = "referenceObjectBindings", required = true)
169     @XmlElement(name = "referenceObjectBinding", required = false)
170     @WebResult(name = "referenceObjectBindings")
171     @Cacheable(value= ReferenceObjectBinding.Cache.NAME, key="'krmsObjectId=' + #p0")
172     public List<ReferenceObjectBinding> findReferenceObjectBindingsByKrmsObject(
173             @WebParam(name = "krmsObjectId") String krmsObjectId) throws RiceIllegalArgumentException;
174 
175     /**
176      * Update the ReferenceObjectBinding object specified by the identifier in the
177      * given DTO
178      *
179      * @param referenceObjectBindingDefinition DTO with updated info and id of the object to be updated
180      * @throws RiceIllegalArgumentException if the given  referenceObjectBindingDefinition
181      *                                      is null or invalid
182      */
183     @WebMethod(operationName = "updateReferenceObjectBinding")
184     @CacheEvict(value={ReferenceObjectBinding.Cache.NAME}, allEntries = true)
185     public void updateReferenceObjectBinding(ReferenceObjectBinding referenceObjectBindingDefinition) throws RiceIllegalArgumentException;
186 
187     /**
188      * Delete the specified ReferenceObjectBinding object
189      *
190      * @param id identifier of the object to be deleted
191      * @throws RiceIllegalArgumentException if the given  id is null or invalid
192      */
193     @WebMethod(operationName = "deleteReferenceObjectBinding")
194     @CacheEvict(value={ReferenceObjectBinding.Cache.NAME}, allEntries = true)
195     public void deleteReferenceObjectBinding(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
196 
197 
198     /**
199      * Query for ReferenceObjectBinding ids based on the given search criteria
200      * which is a Map of ReferenceObjectBinding field names to values. <p/> <p>
201      * This method returns it's results as a List of ReferenceObjectBinding ids
202      * that match the given search criteria. </p>
203      *
204      * @param queryByCriteria the criteria.  Cannot be null.
205      * @return a list of ids matching the given criteria properties.  An empty
206      *         list is returned if an invalid or non-existent criteria is
207      *         supplied.
208      * @throws RiceIllegalArgumentException if the queryByCriteria is null
209      */
210     @WebMethod(operationName = "findReferenceObjectBindingIds")
211     @XmlElementWrapper(name = "referenceObjectBindingIds", required = true)
212     @XmlElement(name = "referenceObjectBindingId", required = false)
213     @WebResult(name = "referenceObjectBindingIds")
214     List<String> findReferenceObjectBindingIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
215 
216     ////
217     //// agenda methods
218     ////
219     /**
220      * Create Agenda and an empty first item
221      *
222      * @param agendaDefinition data for the new Agenda to be created
223      * @return newly created Agenda
224      * @throws RiceIllegalArgumentException if the given agendaDefinition is
225      *                                      null or invalid
226      */
227     @WebMethod(operationName = "createAgenda")
228     @WebResult(name = "agenda")
229     @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
230     public AgendaDefinition createAgenda(@WebParam(name = "AgendaDefinition") AgendaDefinition agendaDefinition) throws RiceIllegalArgumentException;
231 
232     /**
233      * Create Agenda if not found by contextId and name
234      *
235      * @param agendaDefinition data for the new Agenda to be created
236      * @return newly created or found Agenda
237      * @throws RiceIllegalArgumentException if the given agendaDefinition is
238      *                                      null or invalid
239      */
240     @WebMethod(operationName = "findCreateAgenda")
241     @WebResult(name = "agenda")
242     @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
243     public AgendaDefinition findCreateAgenda(@WebParam(name = "AgendaDefinition") AgendaDefinition agendaDefinition) throws RiceIllegalArgumentException;
244 
245     /**
246      * Retrieve Agenda for the specified id
247      *
248      * @param id identifier for the Agenda
249      * @return specified Agenda
250      * @throws RiceIllegalArgumentException if the given id is null or invalid
251      */
252     @WebMethod(operationName = "getAgenda")
253     @WebResult(name = "agenda")
254     @Cacheable(value= AgendaDefinition.Cache.NAME, key="'id=' + #p0")
255     public AgendaDefinition getAgenda(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
256 
257     /**
258      * Retrieves an Agenda from the repository based on the provided agenda name
259      * and context id.
260      *
261      * @param name the name of the Agenda to retrieve.
262      * @param contextId the id of the context that the agenda belongs to.
263      * @return an {@link AgendaDefinition} identified by the given name and namespace.  
264      * A null reference is returned if an invalid or non-existent name and
265      * namespace combination is supplied.
266      */
267     @WebMethod(operationName = "getAgendaByNameAndContextId")
268     @WebResult(name = "agenda")
269     @Cacheable(value= AgendaDefinition.Cache.NAME, key="'name=' + #p0 + '|' + 'contextId=' + #p1")
270     public AgendaDefinition getAgendaByNameAndContextId (@WebParam(name = "name") String name,
271             @WebParam(name = "contextId") String contextId);
272 
273     /**
274      * Retrieve Agendas of the specified type
275      *
276      * @param typeId type of the Agenda
277      * @return list of Agendas of the specified type
278      * @throws RiceIllegalArgumentException if the given typeId is null or
279      *                                      invalid
280      */
281     @WebMethod(operationName = "getAgendasByType")
282     @XmlElementWrapper(name = "agendas", required = true)
283     @XmlElement(name = "agenda", required = false)
284     @WebResult(name = "agendas")
285     @Cacheable(value= AgendaDefinition.Cache.NAME, key="'typeId=' + #p0")
286     public List<AgendaDefinition> getAgendasByType(@WebParam(name = "typeId") String typeId) throws RiceIllegalArgumentException;
287 
288     /**
289      * Retrieve Agendas associated with the specified context
290      *
291      * @param contextId  context of interest
292      * @return list of Agendas associated with the context
293      * @throws RiceIllegalArgumentException if the given contextId is null or
294      *                                      invalid
295      */
296     @WebMethod(operationName = "getAgendasByContext")
297     @XmlElementWrapper(name = "agendas", required = true)
298     @XmlElement(name = "agenda", required = false)
299     @WebResult(name = "agendas")
300     @Cacheable(value= AgendaDefinition.Cache.NAME, key="'contextId=' + #p0")
301     public List<AgendaDefinition> getAgendasByContext(@WebParam(name = "contextId") String contextId) throws RiceIllegalArgumentException;
302 
303     /**
304      * Retrieve Agendas of the specified type and context
305      *
306      * @param typeId  type of the Agenda
307      * @param contextId  context of interest
308      * @return list of Agendas associated with the specified type and context
309      * @throws RiceIllegalArgumentException if the given typeId or contextId
310      *                                      null or invalid
311      */
312     @WebMethod(operationName = "getAgendasByTypeAndContext")
313     @XmlElementWrapper(name = "agendas", required = true)
314     @XmlElement(name = "agenda", required = false)
315     @WebResult(name = "agendas")
316     @Cacheable(value= AgendaDefinition.Cache.NAME, key="'typeId=' + #p0 + '|' + 'contextId=' + #p1")
317     public List<AgendaDefinition> getAgendasByTypeAndContext(@WebParam(name = "typeId") String typeId,
318             @WebParam(name = "contextId") String contextId) throws RiceIllegalArgumentException;
319 
320     /**
321      * Update the Agenda specified by the identifier in the input DTO
322      *
323      * @param agendaDefinition DTO with updated info and identifier of the object to be updated
324      * @throws RiceIllegalArgumentException if the given agendaDefinition is
325      *                                      null or invalid
326      */
327     @WebMethod(operationName = "updateAgenda")
328     @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
329     public void updateAgenda(@WebParam(name = "agendaDefinition") AgendaDefinition agendaDefinition) throws RiceIllegalArgumentException;
330 
331     /**
332      * Delete the specified Agenda
333      *
334      * @param id identifier of the object to be deleted
335      * @throws RiceIllegalArgumentException if the given id is null or invalid
336      */
337     @WebMethod(operationName = "deleteAgenda")
338     @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
339     public void deleteAgenda(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
340 
341     ////
342     //// agenda item methods
343     ////
344     /**
345      * Create AgendaItem
346      *
347      * @param agendaItemDefinition  data for the new AgendaItem to be created
348      * @return newly created AgendaItem
349      * @throws RiceIllegalArgumentException if the given agendaItemDefinition is
350      *                                      null or invalid
351      */
352     @WebMethod(operationName = "createAgendaItem")
353     @WebResult(name = "agendaItem")
354     @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
355     public AgendaItemDefinition createAgendaItem(@WebParam(name = "AgendaItemDefinition") AgendaItemDefinition agendaItemDefinition) throws RiceIllegalArgumentException;
356 
357     /**
358      * Retrieve AgendaItem by the specified identifier
359      *
360      * @param id identifier of the AgendaItem
361      * @return AgendaItem specified by the identifier
362      * @throws RiceIllegalArgumentException if the given id is null or invalid
363      */
364     @WebMethod(operationName = "getAgendaItem")
365     @WebResult(name = "agendaItem")
366     @Cacheable(value= AgendaItemDefinition.Cache.NAME, key="'id=' + #p0")
367     public AgendaItemDefinition getAgendaItem(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
368 
369     /**
370      * Retrieve AgendaItems by specified type
371      *
372      * @param typeId type of the AgendaItems
373      * @return list of AgendaItems of the specified type
374      * @throws RiceIllegalArgumentException if the given typeId is null or
375      *                                      invalid
376      */
377     @WebMethod(operationName = "getAgendaItemsByType")
378     @XmlElementWrapper(name = "agendaItems", required = true)
379     @XmlElement(name = "agendaItem", required = false)
380     @WebResult(name = "agendaItems")
381     @Cacheable(value= AgendaItemDefinition.Cache.NAME, key="'typeId=' + #p0")
382     public List<AgendaItemDefinition> getAgendaItemsByType(@WebParam(name = "typeId") String typeId) throws RiceIllegalArgumentException;
383 
384     /**
385      * Retrieve AgendaItems associated with a context
386      *
387      * @param contextId context identifier
388      * @return list of AgendaItems associated with a context
389      * @throws RiceIllegalArgumentException if the given  contextId is null or
390      *                                      invalid
391      */
392     @WebMethod(operationName = "getAgendaItemsByContext")
393     @XmlElementWrapper(name = "agendaItems", required = true)
394     @XmlElement(name = "agendaItem", required = false)
395     @WebResult(name = "agendaItems")
396     @Cacheable(value= AgendaItemDefinition.Cache.NAME, key="'contextId=' + #p0")
397     public List<AgendaItemDefinition> getAgendaItemsByContext(@WebParam(name = "contextId") String contextId) throws RiceIllegalArgumentException;
398 
399     /**
400      * Retrieve AgendaItems by type and context
401      *
402      * @param typeId type of the Agendas
403      * @param contextId context with which the Agendas are associated
404      * @return list of AgendaItems of the specified type and context
405      * @throws RiceIllegalArgumentException if the given  typeId or contextId
406      *                                      null or invalid
407      */
408     @WebMethod(operationName = "getAgendaItemsByTypeAndContext")
409     @XmlElementWrapper(name = "agendaItems", required = true)
410     @XmlElement(name = "agendaItem", required = false)
411     @WebResult(name = "agendaItems")
412     @Cacheable(value= AgendaItemDefinition.Cache.NAME, key="'typeId=' + #p0 + '|' + 'contextId=' + #p1")
413     public List<AgendaItemDefinition> getAgendaItemsByTypeAndContext(@WebParam(name = "typeId") String typeId,
414             @WebParam(name = "contextId") String contextId) throws RiceIllegalArgumentException;
415 
416     /**
417      * Update an AgendaItem
418      *
419      * @param agendaItemDefinition  updated data for the AgendaItem, with id of the object to be updated
420      * @throws RiceIllegalArgumentException if the given  agendaItemDefinition
421      *                                      is null or invalid
422      */
423     @WebMethod(operationName = "updateAgendaItem")
424     @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
425     public void updateAgendaItem(@WebParam(name = "agendaItemDefinition") AgendaItemDefinition agendaItemDefinition) throws RiceIllegalArgumentException;
426 
427     /**
428      * Delete the specified AgendaItem
429      *
430      * @param id identifier of the AgendaItem to be deleted
431      * @throws RiceIllegalArgumentException if the given id is null or invalid
432      */
433     @WebMethod(operationName = "deleteAgendaItem")
434     @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
435     public void deleteAgendaItem(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
436 
437     ////
438     //// rule methods
439     ////
440     /**
441      * Create Rule
442      *
443      * @param ruleDefinition data for the new Rule to be created
444      * @return newly created Rule
445      * @throws RiceIllegalArgumentException if the given ruleDefinition is null
446      *                                      or invalid
447      */
448     @WebMethod(operationName = "createRule")
449     @WebResult(name = "rule")
450     @CacheEvict(value={RuleDefinition.Cache.NAME, PropositionDefinition.Cache.NAME, ActionDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME}, allEntries = true)
451     public RuleDefinition createRule(@WebParam(name = "ruleDefinition") RuleDefinition ruleDefinition) throws RiceIllegalArgumentException;
452 
453     /**
454      * Retrieves the rule for the given ruleId.  The rule includes the
455      * propositions which define the condition that is to be evaluated on the
456      * rule.  It also defines a collection of actions which will be invoked if
457      * the rule succeeds.
458      *
459      * @param ruleId the id of the rule to retrieve
460      * @return the rule definition, or null if no rule could be located for the
461      *         given ruleId
462      * @throws IllegalArgumentException if the given ruleId is null
463      */
464     @WebMethod(operationName = "getRule")
465     @WebResult(name = "rule")
466     @Cacheable(value= RuleDefinition.Cache.NAME, key="'ruleId=' + #p0")
467     public RuleDefinition getRule(@WebParam(name = "ruleId") String ruleId);
468 
469     /**
470      * Retrieves an Rule from the repository based on the provided rule name
471      * and namespace.
472      *
473      * @param name the name of the Rule to retrieve.
474      * @param namespace the namespace that the rule is under.
475      * @return an {@link RuleDefinition} identified by the given name and namespace.
476      * A null reference is returned if an invalid or non-existent name and
477      * namespace combination is supplied.
478      * @throws IllegalArgumentException if the either the name or the namespace
479      * is null or blank.
480      */
481     @WebMethod(operationName = "getRuleByNameAndNamespace")
482     @WebResult(name = "rule")
483     @Cacheable(value= RuleDefinition.Cache.NAME, key="'name=' + #p0 + '|' + 'namespace=' + #p1")
484     public RuleDefinition getRuleByNameAndNamespace(@WebParam(name = "name") String name,
485             @WebParam(name = "namespace") String namespace);
486 
487     /**
488      * Retrieves all of the rules for the given list of ruleIds.  The rule
489      * includes the propositions which define the condition that is to be
490      * evaluated on the rule.  It also defines a collection of actions which
491      * will be invoked if the rule succeeds.
492      * <p/>
493      * <p>The list which is returned from this operation may not be the same
494      * size as the list which is passed to this method.  If a rule doesn't exist
495      * for a given rule id then no result for that id will be returned in the
496      * list.  As a result of this, the returned list can be empty, but it will
497      * never be null.
498      *
499      * @param ruleIds the list of rule ids for which to retrieve the rules
500      * @return the list of rules for the given ids, this list will only contain
501      *         rules for the ids that were resolved successfully, it will never
502      *         return null but could return an empty list if no rules could be
503      *         loaded for the given set of ids
504      * @throws IllegalArgumentException if the given list of ruleIds is null
505      */
506     @WebMethod(operationName = "getRules")
507     @XmlElementWrapper(name = "rules", required = true)
508     @XmlElement(name = "rule", required = false)
509     @WebResult(name = "rules")
510     @Cacheable(value= RuleDefinition.Cache.NAME, key="'ruleIds=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p0)")
511     public List<RuleDefinition> getRules(@WebParam(name = "ruleIds") List<String> ruleIds);
512 
513     /**
514      * Update the Rule specified by the identifier in the DTO
515      *
516      * @param ruleDefinition updated Rule information, object specified by the id
517      * @throws RiceIllegalArgumentException if the given ruleDefinition is null
518      *                                      or invalid
519      */
520     @WebMethod(operationName = "updateRule")
521     @CacheEvict(value={RuleDefinition.Cache.NAME, PropositionDefinition.Cache.NAME, ActionDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME}, allEntries = true)
522     public void updateRule(@WebParam(name = "ruleDefinition") RuleDefinition ruleDefinition) throws RiceIllegalArgumentException;
523 
524     /**
525      * Delete the specified Rule
526      *
527      * @param id identifier of the Rule to be deleted
528      * @throws RiceIllegalArgumentException if the given id is null or invalid
529      */
530     @WebMethod(operationName = "deleteRule")
531     @CacheEvict(value={RuleDefinition.Cache.NAME, PropositionDefinition.Cache.NAME, ActionDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME}, allEntries = true)
532     public void deleteRule(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
533 
534     ////
535     //// action methods
536     ////
537     /**
538      * Create Action
539      *
540      * @param actionDefinition data for the new Action to be created
541      * @return newly created Action
542      * @throws RiceIllegalArgumentException if the given actionDefinition is null
543      * or invalid
544      */
545     @WebMethod(operationName = "createAction")
546     @WebResult(name = "action")
547     @CacheEvict(value={ActionDefinition.Cache.NAME, RuleDefinition.Cache.NAME}, allEntries = true)
548     public ActionDefinition createAction(@WebParam(name = "actionDefinition") ActionDefinition actionDefinition) throws RiceIllegalArgumentException;
549 
550     /**
551      * Retrieves the action for the given actionId. The action includes the
552      * propositions which define the condition that is to be evaluated on the
553      * action. It also defines a collection of actions which will be invoked if
554      * the action succeeds.
555      *
556      * @param actionId the id of the action to retrieve
557      * @return the action definition, or null if no action could be located for the
558      * given actionId
559      * @throws IllegalArgumentException if the given actionId is null
560      */
561     @WebMethod(operationName = "getAction")
562     @WebResult(name = "action")
563     @Cacheable(value= ActionDefinition.Cache.NAME, key="'actionId=' + #p0")
564     public ActionDefinition getAction(@WebParam(name = "actionId") String actionId) throws RiceIllegalArgumentException;
565 
566     /**
567      * Retrieves all of the actions for the given list of actionIds.
568      * <p/>
569      * <p>The list which is returned from this operation may not be the same
570      * size as the list which is passed to this method. If a action doesn't exist
571      * for a given action id then no result for that id will be returned in the
572      * list. As a result of this, the returned list can be empty, but it will
573      * never be null.
574      *
575      * @param actionIds the list of action ids for which to retrieve the actions
576      * @return the list of actions for the given ids, this list will only contain
577      * actions for the ids that were resolved successfully, it will never return
578      * null but could return an empty list if no actions could be loaded for the
579      * given set of ids
580      * @throws IllegalArgumentException if the given list of actionIds is null
581      */
582     @WebMethod(operationName = "getActions")
583     @XmlElementWrapper(name = "actions", required = true)
584     @XmlElement(name = "action", required = false)
585     @WebResult(name = "actions")
586     @Cacheable(value= ActionDefinition.Cache.NAME, key="'actionIds=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p0)")
587     public List<ActionDefinition> getActions(@WebParam(name = "actionIds") List<String> actionIds)  throws RiceIllegalArgumentException;
588 
589     /**
590      * Update the Action specified by the identifier in the DTO
591      *
592      * @param actionDefinition updated Action information, object specified by the
593      * id
594      * @throws RiceIllegalArgumentException if the given actionDefinition is null
595      * or invalid
596      */
597     @WebMethod(operationName = "updateAction")
598     @CacheEvict(value={ActionDefinition.Cache.NAME, RuleDefinition.Cache.NAME}, allEntries = true)
599     public void updateAction(@WebParam(name = "actionDefinition") ActionDefinition actionDefinition) throws RiceIllegalArgumentException;
600 
601     /**
602      * Delete the specified Action
603      *
604      * @param id identifier of the Action to be deleted
605      * @throws RiceIllegalArgumentException if the given id is null or invalid
606      */
607     @WebMethod(operationName = "deleteAction")
608     @CacheEvict(value={ActionDefinition.Cache.NAME, RuleDefinition.Cache.NAME}, allEntries = true)
609     public void deleteAction(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
610 
611 
612     ////
613     //// proposition methods
614     ////
615     /**
616      * Create a Proposition
617      *
618      * @param propositionDefinition data for the new Proposition to be created
619      * @return newly created Proposition
620      * @throws RiceIllegalArgumentException if the given propositionDefinition
621      *                                      is null or invalid
622      */
623     @WebMethod(operationName = "createProposition")
624     @WebResult(name = "proposition")
625     @CacheEvict(value={PropositionDefinition.Cache.NAME, RuleDefinition.Cache.NAME}, allEntries = true)
626     public PropositionDefinition createProposition(@WebParam(name = "propositionDefinition") PropositionDefinition propositionDefinition) throws RiceIllegalArgumentException;
627 
628     /**
629      * Retrieve Proposition specified by the identifier
630      *
631      * @param id identifier of the Proposition to be retrieved
632      * @return specified Proposition
633      * @throws RiceIllegalArgumentException if the given id is null or invalid
634      */
635     @WebMethod(operationName = "getProposition")
636     @WebResult(name = "proposition")
637     @Cacheable(value= PropositionDefinition.Cache.NAME, key="'id=' + #p0")
638     public PropositionDefinition getProposition(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
639 
640     /**
641      * Retrieve Propositions of the specified type
642      *
643      * @param typeId type of the Propositions to be retrieved
644      * @return list of Propositions of the specified type
645      * @throws RiceIllegalArgumentException if the given typeId is null or
646      *                                      invalid
647      */
648     @WebMethod(operationName = "getPropositionsByType")
649     @XmlElementWrapper(name = "propositions", required = true)
650     @XmlElement(name = "proposition", required = false)
651     @WebResult(name = "propositions")
652     @Cacheable(value= PropositionDefinition.Cache.NAME, key="'typeId=' + #p0")
653     public Set<PropositionDefinition> getPropositionsByType(@WebParam(name = "typeId") String typeId) throws RiceIllegalArgumentException;
654 
655     /**
656      * Retrieve Propositions associated with the specified Rule
657      *
658      * @param ruleId identifier of the Rule to which the Propositions are associated with
659      * @return list of Propositions associated with the Rule
660      * @throws RiceIllegalArgumentException if the given ruleId is null or
661      *                                      invalid
662      */
663     @WebMethod(operationName = "getPropositionsByRule")
664     @XmlElementWrapper(name = "propositions", required = true)
665     @XmlElement(name = "proposition", required = false)
666     @WebResult(name = "propositions")
667     @Cacheable(value= PropositionDefinition.Cache.NAME, key="'ruleId=' + #p0")
668     public Set<PropositionDefinition> getPropositionsByRule(@WebParam(name = "ruleId") String ruleId) throws RiceIllegalArgumentException;
669 
670     /**
671      * Update the Proposition
672      *
673      * @param propositionDefinition updated data for the Proposition, id specifies the object to be updated
674      * @throws RiceIllegalArgumentException if the given propositionDefinition
675      *                                      is null or invalid
676      */
677     @WebMethod(operationName = "updateProposition")
678     @CacheEvict(value={PropositionDefinition.Cache.NAME, RuleDefinition.Cache.NAME}, allEntries = true)
679     public void updateProposition(
680             @WebParam(name = "propositionDefinition") PropositionDefinition propositionDefinition) throws RiceIllegalArgumentException;
681 
682     /**
683      * Delete the Proposition
684      *
685      * @param id identifier of the Proposition to be deleted
686      * @throws RiceIllegalArgumentException if the given id is null or invalid
687      */
688     @WebMethod(operationName = "deleteProposition")
689     @CacheEvict(value={PropositionDefinition.Cache.NAME, RuleDefinition.Cache.NAME}, allEntries = true)
690     public void deleteProposition(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
691 
692     ////
693     //// natural language usages
694     ////
695     /**
696      * Create NaturalLanguageUsage
697      *
698      * @param naturalLanguageUsage data for the new NaturalLanguageUsage to be created
699      * @return newly created NaturalLanguageUsage
700      * @throws RiceIllegalArgumentException if the given naturalLanguageUsage is
701      *                                      null or invalid
702      */
703     @WebMethod(operationName = "createNaturalLanguageUsage")
704     @WebResult(name = "naturalLanguageUsage")
705     @CacheEvict(value={NaturalLanguageUsage.Cache.NAME, NaturalLanguageTemplate.Cache.NAME}, allEntries = true)
706     public NaturalLanguageUsage createNaturalLanguageUsage(@WebParam(name = "naturalLanguageUsage") NaturalLanguageUsage naturalLanguageUsage) throws RiceIllegalArgumentException;
707 
708     /**
709      * Retrieve NaturalLanguageUsage specified by the identifier
710      *
711      * @param id identifier of the NaturalLanguageUsage to be retrieved
712      * @return NaturalLanguageUsage specified by the identifier
713      * @throws RiceIllegalArgumentException if the given id is null or invalid
714      */
715     @WebMethod(operationName = "getNaturalLanguageUsage")
716     @WebResult(name = "naturalLanguageUsage")
717     @Cacheable(value= NaturalLanguageUsage.Cache.NAME, key="'id=' + #p0")
718     public NaturalLanguageUsage getNaturalLanguageUsage(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
719 
720     /**
721      * Retrieve NaturalLanguageUsage specified by name and namespace
722      *
723      * @param name the name of the natural language usage to retrieve.
724      * @param namespace the namespace that the natural language usage is under.
725      * @return an {@link NaturalLanguageUsage} identified by the given name and
726      * namespace. A null reference is returned if an invalid or non-existent
727      * name and namespace combination is supplied.
728      * @throws RiceIllegalArgumentException if the either the name or the
729      * namespace is null or blank.
730      */
731     @WebMethod(operationName = "getNaturalLanguageUsageByNameAndNamespace")
732     @WebResult(name = "naturalLanguageUsage")
733     @Cacheable(value= NaturalLanguageUsage.Cache.NAME, key="'name=' + #p0 + '|' + 'namespace=' + #p1")
734     public NaturalLanguageUsage getNaturalLanguageUsageByNameAndNamespace(@WebParam(name = "name") String name,
735             @WebParam(name = "namespace") String namespace)
736             throws RiceIllegalArgumentException;
737 
738     /**
739      * Update NaturalLanguageUsage
740      *
741      * @param naturalLanguageUsage updated data for the NaturalLanguageUsage object specified by the id
742      * @throws RiceIllegalArgumentException if the given naturalLanguageUsage is
743      *                                      null or invalid
744      */
745     @WebMethod(operationName = "updateNaturalLanguageUsage")
746     @CacheEvict(value={NaturalLanguageUsage.Cache.NAME, NaturalLanguageTemplate.Cache.NAME}, allEntries = true)
747     public void updateNaturalLanguageUsage(@WebParam(name = "naturalLanguageUsage") NaturalLanguageUsage naturalLanguageUsage) throws RiceIllegalArgumentException;
748 
749     /**
750      * Delete NaturalLanguageUsage
751      *
752      * @param naturalLanguageUsageId  identifier of the NaturalLanguageUsage to be deleted
753      * @throws RiceIllegalArgumentException  if the given naturalLanguageUsageId is null or invalid
754      */
755     @WebMethod(operationName = "deleteNaturalLanguageUsage")
756     @CacheEvict(value={NaturalLanguageUsage.Cache.NAME, NaturalLanguageTemplate.Cache.NAME}, allEntries = true)
757     public void deleteNaturalLanguageUsage(@WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId) throws RiceIllegalArgumentException;
758 
759     /**
760      * Translates and retrieves a NaturalLanguage for a given KRMS object (e.g, proposition
761      * or agenda), NaturalLanguage usage type (context) and language into natural language
762      *
763      * @param namespace namespace to search on.
764      * @return list of NaturalLanguageUsages in a particular namespace
765      */
766     @WebMethod(operationName = "getNaturalLanguageUsagesByNamespace")
767     @XmlElementWrapper(name = "naturalLanguageUsages", required = true)
768     @XmlElement(name = "naturalLanguageUsage", required = false)
769     @WebResult(name = "naturalLanguageUsages")
770     @Cacheable(value= NaturalLanguageUsage.Cache.NAME, key="'namespace=' + #p0")
771     public List<NaturalLanguageUsage> getNaturalLanguageUsagesByNamespace(@WebParam(name = "namespace") String namespace)
772             throws RiceIllegalArgumentException;
773 
774     ////
775     //// context methods
776     ////
777     /**
778      * Create Context
779      *
780      * @param contextDefinition data for the new Context to be created
781      * @return newly created Context
782      * @throws RiceIllegalArgumentException if the given contextDefinition is
783      * null or invalid or already in use.
784      */
785     @WebMethod(operationName = "createContext")
786     @WebResult(name = "context")
787     @CacheEvict(value={ContextDefinition.Cache.NAME}, allEntries = true)
788     public ContextDefinition createContext(@WebParam(name = "contextDefinition") ContextDefinition contextDefinition) throws RiceIllegalArgumentException;
789 
790 
791     /**
792      * find Create Context
793      *
794      * Searches for an existing context with the same name and namespace and returns it
795      * otherwise it creates the context.
796      *
797      * @param contextDefinition data for the new Context to be created
798      * @return newly created Context
799      * @throws RiceIllegalArgumentException if the given contextDefinition is
800      * null or invalid
801      */
802     @WebMethod(operationName = "findCreateContext")
803     @WebResult(name = "context")
804     @CacheEvict(value={ContextDefinition.Cache.NAME}, allEntries = true)
805     public ContextDefinition findCreateContext(@WebParam(name = "contextDefinition") ContextDefinition contextDefinition) throws RiceIllegalArgumentException;
806 
807 
808     /**
809      * Update the Context specified by the identifier in the input DTO
810      *
811      * @param contextDefinition DTO with updated info and identifier of the
812      * object to be updated
813      * @throws RiceIllegalArgumentException if the given contextDefinition is
814      * null or invalid
815      */
816     @WebMethod(operationName = "updateContext")
817     @CacheEvict(value={ContextDefinition.Cache.NAME}, allEntries = true)
818     public void updateContext(@WebParam(name = "contextDefinition") ContextDefinition contextDefinition) throws RiceIllegalArgumentException;
819 
820     /**
821      * Delete the specified Context
822      *
823      * @param id identifier of the object to be deleted
824      * @throws RiceIllegalArgumentException if the given id is null or invalid
825      */
826     @WebMethod(operationName = "deleteContext")
827     @CacheEvict(value={ContextDefinition.Cache.NAME}, allEntries = true)
828     public void deleteContext(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
829 
830     /**
831      * Retrieve Context for the specified id
832      *
833      * @param id identifier for the Context
834      * @return specified Context
835      * @throws RiceIllegalArgumentException if the given id is null or invalid
836      */
837     @WebMethod(operationName = "getContext")
838     @WebResult(name = "context")
839     @Cacheable(value= ContextDefinition.Cache.NAME, key="'id=' + #p0")
840     public ContextDefinition getContext(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
841 
842     /**
843      * Retrieves an Context from the repository based on the provided context
844      * name and namespace.
845      *
846      * @param name the name of the Context to retrieve.
847      * @param namespace the namespace that the context is under.
848      * @return an {@link ContextDefinition} identified by the given name and
849      * namespace. A null reference is returned if an invalid or non-existent
850      * name and namespace combination is supplied.
851      * @throws RiceIllegalArgumentException if the either the name or the
852      * namespace is null or blank.
853      */
854     @WebMethod(operationName = "getContextByNameAndNamespace")
855     @WebResult(name = "context")
856     @Cacheable(value= ContextDefinition.Cache.NAME, key="'name=' + #p0 + '|' + 'namespace=' + #p1")
857     public ContextDefinition getContextByNameAndNamespace(@WebParam(name = "name") String name,
858             @WebParam(name = "namespace") String namespace)
859             throws RiceIllegalArgumentException;
860 
861     //// natural languatge template methods
862     /**
863      * This will create a {@link NaturalLanguageTemplate} exactly like the
864      * parameter passed in except the id will be assigned and create date/user 
865      * will be set.
866      *
867      * @param naturalLanguageTemplate The NaturalLanguageTemplate to create.
868      * @throws RiceIllegalArgumentException if the NaturalLanguageTemplate is null.
869      * @throws IllegalStateException if the NaturalLanguageTemplate already
870      * exists in the system.
871      * @return a {@link NaturalLanguageTemplate} exactly like the parameter
872      * passed in.
873      *
874      */
875     @WebMethod(operationName = "createNaturalLanguageTemplate")
876     @WebResult(name = "naturalLanguageTemplate")
877     @CacheEvict(value={NaturalLanguageTemplate.Cache.NAME}, allEntries = true)
878     public NaturalLanguageTemplate createNaturalLanguageTemplate(@WebParam(name = "naturalLanguageTemplate") NaturalLanguageTemplate naturalLanguageTemplate)
879             throws RiceIllegalArgumentException;
880 
881     /**
882      * Retrieves a NaturalLanguageTemplate from the repository based on the
883      * given id.
884      *
885      * @param naturalLanguageTemplateId to retrieve.
886      * @return a {@link NaturalLanguageTemplate} identified by the given id. 
887      * @throws IllegalArgumentException if the given actionId is null     *
888      */
889     @WebMethod(operationName = "getNaturalLanguageTemplate")
890     @WebResult(name = "naturalLanguageTemplate")
891     @Cacheable(value= NaturalLanguageTemplate.Cache.NAME, key="'naturalLanguageTemplateId=' + #p0")
892     public NaturalLanguageTemplate getNaturalLanguageTemplate(@WebParam(name = "naturalLanguageTemplateId") String naturalLanguageTemplateId)
893             throws RiceIllegalArgumentException;
894 
895     /**
896      * This will update an existing {@link NaturalLanguageTemplate}.
897      *
898      * @param naturalLanguageTemplate The NaturalLanguageTemplate to update.
899      * @throws RiceIllegalArgumentException if the NaturalLanguageTemplate is null.
900      * exists in the system.
901      *
902      */
903     @WebMethod(operationName = "updateNaturalLanguageTemplate")
904     @CacheEvict(value={NaturalLanguageTemplate.Cache.NAME}, allEntries = true)
905     public void updateNaturalLanguageTemplate(@WebParam(name = "naturalLanguageTemplate") NaturalLanguageTemplate naturalLanguageTemplate)
906             throws RiceIllegalArgumentException;
907 
908     /**
909      * Delete the {@link NaturalLanguageTemplate} with the given id.
910      *
911      * @param naturalLanguageTemplateId to delete.
912      * @throws RiceIllegalArgumentException if the NaturalLanguageTemplate is null.
913      *
914      */
915     @WebMethod(operationName = "deleteNaturalLanguageTemplate")
916     @CacheEvict(value={NaturalLanguageTemplate.Cache.NAME}, allEntries = true)
917     public void deleteNaturalLanguageTemplate(@WebParam(name = "naturalLanguageTemplateId") String naturalLanguageTemplateId)
918             throws RiceIllegalArgumentException;
919 
920     /**
921      * Finds all the natural language templates for a particular language
922      *
923      * @param languageCode language on which to search
924      * @return list of templates for that language
925      */
926     @WebMethod(operationName = "findNaturalLanguageTemplatesByLanguageCode")
927     @XmlElementWrapper(name = "naturalLangaugeTemplates", required = true)
928     @XmlElement(name = "naturalLangaugeTemplate", required = false)
929     @WebResult(name = "naturalLangaugeTemplates")
930     @Cacheable(value= NaturalLanguageTemplate.Cache.NAME, key="'languageCode=' + #p0")
931     public List<NaturalLanguageTemplate> findNaturalLanguageTemplatesByLanguageCode(@WebParam(name = "languageCode") String languageCode)
932             throws RiceIllegalArgumentException;
933 
934     @WebMethod(operationName = "findNaturalLanguageTemplateByLanguageCodeTypeIdAndNluId")
935     @WebResult(name = "naturalLangaugeTemplate")
936     @Cacheable(value= NaturalLanguageTemplate.Cache.NAME, key="'languageCode=' + #p0 + '|' + 'typeId=' + #p1 + '|' + 'naturalLanguageUsageId=' + #p2")
937     public NaturalLanguageTemplate findNaturalLanguageTemplateByLanguageCodeTypeIdAndNluId(@WebParam(name = "languageCode") String languageCode,
938             @WebParam(name = "typeId") String typeId,
939             @WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId)
940             throws RiceIllegalArgumentException;
941 
942     /**
943      * Find all the natural language templates for a particular usage
944      *
945      * @param naturalLanguageUsageId the usage on which to search
946      * @return list of templates that match the usage
947      */
948     @WebMethod(operationName = "findNaturalLanguageTemplatesByNaturalLanguageUsage")
949     @XmlElementWrapper(name = "naturalLangaugeTemplates", required = true)
950     @XmlElement(name = "naturalLangaugeTemplate", required = false)
951     @WebResult(name = "naturalLangaugeTemplates")
952     @Cacheable(value= NaturalLanguageTemplate.Cache.NAME, key="'naturalLanguageUsageId=' + #p0")
953     public List<NaturalLanguageTemplate> findNaturalLanguageTemplatesByNaturalLanguageUsage(@WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId)
954             throws RiceIllegalArgumentException;
955 
956     /**
957      * Find all the natural language templates of a particular type
958      *
959      * Template types are keys that identify the message that is to be expressed
960      * in different languages and in different usage scenarios
961      *
962      * @param typeId on which to search
963      * @return list of templates matching that type
964      */
965     @WebMethod(operationName = "findNaturalLanguageTemplatesByType")
966     @XmlElementWrapper(name = "naturalLangaugeTemplates", required = true)
967     @XmlElement(name = "naturalLangaugeTemplate", required = false)
968     @WebResult(name = "naturalLangaugeTemplates")
969     @Cacheable(value= NaturalLanguageTemplate.Cache.NAME, key="'typeId=' + #p0")
970     public List<NaturalLanguageTemplate> findNaturalLanguageTemplatesByType(@WebParam(name = "typeId") String typeId)
971             throws RiceIllegalArgumentException;
972 
973     /**
974      * Find the natural language template using the actual text of the template.
975      *
976      * @param template text to match exactly
977      * @return list of matching templates
978      */
979     @WebMethod(operationName = "findNaturalLanguageTemplatesByTemplate")
980     @XmlElementWrapper(name = "naturalLangaugeTemplates", required = true)
981     @XmlElement(name = "naturalLangaugeTemplate", required = false)
982     @WebResult(name = "naturalLangaugeTemplates")
983     @Cacheable(value= NaturalLanguageTemplate.Cache.NAME, key="'template=' + #p0")
984     public List<NaturalLanguageTemplate> findNaturalLanguageTemplatesByTemplate(@WebParam(name = "template") String template)
985             throws RiceIllegalArgumentException;
986 
987     ////
988     //// translation methods
989     ////
990     /**
991      * Translates and retrieves a NaturalLanguage for a given KRMS object (e.g,
992      * proposition or agenda), NaturalLanguage usage type (context) and language
993      * into natural language
994      *
995      * @param naturalLanguageUsageId Natural language usage information
996      * @param typeId    KRMS object type id (for example, could refer to agenda
997      *                  or proposition)
998      * @param krmsObjectId KRMS object identifier
999      * @param languageCode  desired
1000      * @return natural language corresponding to the NaturalLanguage usage, KRMS object id, KRMS object type and desired language
1001      * @throws RiceIllegalArgumentException if the given naturalLanguageUsageId, typeId,
1002      *                                      krmsObjectId or language is null or
1003      *                                      invalid
1004      */
1005     @WebMethod(operationName = "translateNaturalLanguageForObject")
1006     @WebResult(name = "naturalLanguage")
1007     @Override
1008     public String translateNaturalLanguageForObject(@WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId,
1009             @WebParam(name = "typeId") String typeId, @WebParam(name = "krmsObjectId") String krmsObjectId,
1010             @WebParam(name = "languageCode") String languageCode) throws RiceIllegalArgumentException;
1011 
1012     /**
1013      * Retrieve all the NaturalLanguageUsages
1014      *
1015      * @return list of NaturalLanguageUsages
1016      */
1017     @WebMethod(operationName = "translateNaturalLanguageForProposition")
1018     @WebResult(name = "naturalLanguage")
1019     @Override
1020     public String translateNaturalLanguageForProposition(@WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId,
1021             @WebParam(name = "propositionDefinintion") PropositionDefinition propositionDefinintion,
1022             @WebParam(name = "languageCode") String languageCode)
1023             throws RiceIllegalArgumentException;
1024 
1025     /**
1026      * Translates NaturalLanguage for a given proposition, returning a tree of
1027      * the NaturalLanguage.
1028      *
1029      * This method is used to "preview" the proposition in a tree structure
1030      * before saving.
1031      *
1032      * @param naturalLanguageUsageId Natural language usage information
1033      * @param propositionDefinintion proposition to be translated
1034      * @param languageCode desired
1035      * @return natural language tree corresponding to the NaturalLanguage usage,
1036      * proposition and desired language
1037      * @throws RiceIllegalArgumentException if the given naturalLanguageUsageId,
1038      * proposition, or language is null or invalid
1039      */
1040     @WebMethod(operationName = "translateNaturalLanguageTreeForProposition")
1041     @WebResult(name = "naturalLanguageTree")
1042     @Override
1043     public NaturalLanguageTree translateNaturalLanguageTreeForProposition(@WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId,
1044             @WebParam(name = "propositionDefinintion") PropositionDefinition propositionDefinintion,
1045             @WebParam(name = "languageCode") String languageCode)
1046             throws RiceIllegalArgumentException;
1047 
1048 
1049     /**
1050      * Query for Context ids based on the given search criteria which is a Map
1051      * of Context field names to values.
1052      * <p/>
1053      * <p> This method returns it's results as a List of Context ids that match
1054      * the given search criteria. </p>
1055      *
1056      * @param queryByCriteria the criteria. Cannot be null.
1057      * @return a list of ids matching the given criteria properties. An empty
1058      * list is returned if an invalid or non-existent criteria is supplied.
1059      * @throws RiceIllegalArgumentException if the queryByCriteria is null
1060      */
1061     @WebMethod(operationName = "findContextIds")
1062     @XmlElementWrapper(name = "contextIds", required = true)
1063     @XmlElement(name = "context", required = false)
1064     @WebResult(name = "contextIds")
1065     List<String> findContextIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
1066 
1067     /**
1068      * Query for Agenda ids based on the given search criteria which is a Map of
1069      * Agenda field names to values.
1070      * <p/>
1071      * <p> This method returns it's results as a List of Agenda ids that match
1072      * the given search criteria. </p>
1073      *
1074      * @param queryByCriteria the criteria. Cannot be null.
1075      * @return a list of ids matching the given criteria properties. An empty
1076      * list is returned if an invalid or non-existent criteria is supplied.
1077      * @throws RiceIllegalArgumentException if the queryByCriteria is null
1078      */
1079     @WebMethod(operationName = "findAgendaIds")
1080     @XmlElementWrapper(name = "contextIds", required = true)
1081     @XmlElement(name = "agenda", required = false)
1082     @WebResult(name = "agendaIds")
1083     List<String> findAgendaIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
1084 
1085     /**
1086      * Query for Rule ids based on the given search criteria which is a Map of
1087      * Rule field names to values.
1088      * <p/>
1089      * <p> This method returns it's results as a List of Rule ids that match the
1090      * given search criteria. </p>
1091      *
1092      * @param queryByCriteria the criteria. Cannot be null.
1093      * @return a list of ids matching the given criteria properties. An empty
1094      * list is returned if an invalid or non-existent criteria is supplied.
1095      * @throws RiceIllegalArgumentException if the queryByCriteria is null
1096      */
1097     @WebMethod(operationName = "findRuleIds")
1098     @XmlElementWrapper(name = "ruleIds", required = true)
1099     @XmlElement(name = "rule", required = false)
1100     @WebResult(name = "ruleIds")
1101     List<String> findRuleIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
1102 
1103     /**
1104      * Query for Proposition ids based on the given search criteria which is a
1105      * Map of Proposition field names to values.
1106      * <p/>
1107      * <p> This method returns it's results as a List of Proposition ids that
1108      * match the given search criteria. </p>
1109      *
1110      * @param queryByCriteria the criteria. Cannot be null.
1111      * @return a list of ids matching the given criteria properties. An empty
1112      * list is returned if an invalid or non-existent criteria is supplied.
1113      * @throws RiceIllegalArgumentException if the queryByCriteria is null
1114      */
1115     @WebMethod(operationName = "findPropositionIds")
1116     @XmlElementWrapper(name = "propositionIds", required = true)
1117     @XmlElement(name = "proposition", required = false)
1118     @WebResult(name = "propositionIds")
1119     List<String> findPropositionIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
1120 
1121     /**
1122      * Query for Action ids based on the given search criteria which is a Map
1123      * of Action field names to values.
1124      * <p/>
1125      * <p> This method returns it's results as a List of Action ids that match
1126      * the given search criteria. </p>
1127      *
1128      * @param queryByCriteria the criteria. Cannot be null.
1129      * @return a list of ids matching the given criteria properties. An empty
1130      * list is returned if an invalid or non-existent criteria is supplied.
1131      * @throws RiceIllegalArgumentException if the queryByCriteria is null
1132      */
1133     @WebMethod(operationName = "findActionIds")
1134     @XmlElementWrapper(name = "actionIds", required = true)
1135     @XmlElement(name = "action", required = false)
1136     @WebResult(name = "actionIds")
1137     List<String> findActionIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
1138 
1139     ////
1140     //// extra methods from RuleRepositoryService copied here so I can break the dependence on that service
1141     //// and then implement different caching schemes for each 
1142     ////
1143 
1144 
1145     /**
1146      * Locates a ContextDefinition based on the given map of context qualifiers.
1147      * The requirements for valid selection criteria are implementation
1148      * dependent. An IllegalArgumentException may be thrown if the
1149      * implementation can't operate with the given criteria.
1150      *
1151      * @param contextSelectionCriteria
1152      * @return
1153      * @see ContextSelectionCriteria
1154      * @throws RiceIllegalArgumentException if the implementation can't handle
1155      * the given ContextSelectionCriteria
1156      */
1157     @WebMethod(operationName = "selectContext")
1158     @WebResult(name = "contextDefinition")
1159     public ContextDefinition selectContext(@WebParam(name = "contextSelectionCriteria") ContextSelectionCriteria contextSelectionCriteria)
1160             throws RiceIllegalArgumentException;
1161 
1162     /**
1163      * Retrieves the agenda tree for the given agendaId. The agenda tree
1164      * includes the entire agenda definition in the appropriate order and with
1165      * the defined agenda branching.
1166      *
1167      * @param agendaId the id of the agenda for which to retrieve the agenda
1168      * tree
1169      * @return the agenda tree, or null if no agenda could be located for the
1170      * given agendaId
1171      *
1172      * @throws RiceIllegalArgumentException if the given agendaId is null
1173      */
1174     @WebMethod(operationName = "getAgendaTree")
1175     @WebResult(name = "agendaTree")
1176     @Cacheable(value= AgendaTreeDefinition.Cache.NAME, key="'agendaId=' + #p0")
1177     public AgendaTreeDefinition getAgendaTree(@WebParam(name = "agendaId") String agendaId)
1178             throws RiceIllegalArgumentException;
1179 
1180     /**
1181      * Retrieves all of the agendas trees for the given list of agendaIds. The
1182      * agenda tree includes the entire agenda definition in the appropriate
1183      * order and with the defined agenda branching.
1184      *
1185      * <p>The list which is returned from this operation may not be the same
1186      * size as the list which is passed to this method. If an agenda doesn't
1187      * exist for a given agenda id then no result for that id will be returned
1188      * in the list. As a result of this, the returned list can be empty, but it
1189      * will never be null.
1190      *
1191      * @param agendaIds the list of agenda ids for which to retrieve the agenda
1192      * trees
1193      * @return the list of agenda trees for the given ids, this list will only
1194      * contain agenda trees for the ids that were resolved successfully, it will
1195      * never return null but could return an empty list if no agenda trees could
1196      * be loaded for the given set of ids
1197      *
1198      * @throws RiceIllegalArgumentException if the given list of agendaIds is
1199      * null
1200      */
1201     @WebMethod(operationName = "getAgendaTrees")
1202     @XmlElementWrapper(name = "agendaTrees", required = true)
1203     @XmlElement(name = "agendaTree", required = false)
1204     @WebResult(name = "agendaTrees")
1205     @Cacheable(value= AgendaTreeDefinition.Cache.NAME, key="'agendaIds=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p0)")
1206     public List<AgendaTreeDefinition> getAgendaTrees(@WebParam(name = "agendaIds") List<String> agendaIds)
1207             throws RiceIllegalArgumentException;
1208 
1209 
1210 }