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 */
016package org.kuali.rice.krms.api.repository;
017
018import org.kuali.rice.core.api.criteria.QueryByCriteria;
019import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
020import org.kuali.rice.krms.api.KrmsConstants;
021import org.kuali.rice.krms.api.repository.agenda.AgendaDefinition;
022import org.kuali.rice.krms.api.repository.agenda.AgendaItemDefinition;
023import org.kuali.rice.krms.api.repository.language.NaturalLanguageUsage;
024import org.kuali.rice.krms.api.repository.proposition.PropositionDefinition;
025import org.kuali.rice.krms.api.repository.reference.ReferenceObjectBinding;
026import org.kuali.rice.krms.api.repository.rule.RuleDefinition;
027import org.springframework.cache.annotation.Cacheable;
028
029import javax.jws.WebMethod;
030import javax.jws.WebParam;
031import javax.jws.WebResult;
032import javax.jws.WebService;
033import javax.jws.soap.SOAPBinding;
034import javax.xml.bind.annotation.XmlElement;
035import javax.xml.bind.annotation.XmlElementWrapper;
036import java.util.List;
037import java.util.Set;
038import org.kuali.rice.krms.api.repository.action.ActionDefinition;
039import org.kuali.rice.krms.api.repository.context.ContextDefinition;
040import org.kuali.rice.krms.api.repository.language.NaturalLanguageTemplate;
041
042/**
043 * The rule maintenance service operations facilitate management of rules and
044 * associated information.
045 *
046 * @author Kuali Rice Team (rice.collab@kuali.org)
047 */
048@WebService(name = "ruleManagementService", targetNamespace = KrmsConstants.Namespaces.KRMS_NAMESPACE_2_0)
049@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL,
050parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
051public interface RuleManagementService extends RuleRepositoryService, TranslateBusinessMethods {
052
053    /**
054     * Create RefObject-KRMS object binding
055     *
056     * @param referenceObjectDefinition  data for the new ReferenceObjectBinding to be created
057     * @return newly created ReferenceObjectBinding
058     * @throws RiceIllegalArgumentException if the given referenceObjectDefinition
059     *                                      is null or invalid
060     */
061    @WebMethod(operationName = "createReferenceObjectBinding")
062    @WebResult(name = "referenceObjectBinding")
063    public ReferenceObjectBinding createReferenceObjectBinding(@WebParam(
064            name = "referenceObjectDefinition") ReferenceObjectBinding referenceObjectDefinition) throws RiceIllegalArgumentException;
065
066    /**
067     * Retrieve referenceObjectBinding  given a specific id
068     *
069     * @param id identifier of the ReferenceObjectBinding to be retrieved
070     * @return a ReferenceObjectBinding with the given id value
071     * @throws RiceIllegalArgumentException if the given  id is blank or
072     *                                      invalid
073     */
074    @WebMethod(operationName = "getReferenceObjectBinding")
075    @WebResult(name = "referenceObjectBinding")
076    public ReferenceObjectBinding getReferenceObjectBinding(@WebParam(
077            name = "id") String id) throws RiceIllegalArgumentException;
078
079    /**
080     * Retrieve list of ReferenceObjectBinding objects given ids
081     *
082     * @param ids identifiers of the ReferenceObjectBinding to be retrieved
083     * @return list of ReferenceObjectBinding objects for the given ids
084     * @throws RiceIllegalArgumentException if one or more ids in the give list
085     *                                      is blank or invalid
086     */
087    @WebMethod(operationName = "getReferenceObjectBindings")
088    @XmlElementWrapper(name = "referenceObjectBindings", required = true)
089    @XmlElement(name = "referenceObjectBinding", required = false)
090    @WebResult(name = "referenceObjectBindings")
091    List<ReferenceObjectBinding> getReferenceObjectBindings(@WebParam(
092            name = "ids") List<String> ids) throws RiceIllegalArgumentException;
093
094    /**
095     * Retrieves list of ReferenceObjectBinding objects for the given ref obj
096     * discriminator type
097     *
098     * @param referenceObjectReferenceDiscriminatorType  reference object type
099     * @return list of ReferenceObjectBinding objects for the given discriminator
100     *         type
101     * @throws RiceIllegalArgumentException if the given  referenceObjectReferenceDiscriminatorType is
102     *                                      blank or invalid
103     */
104    @WebMethod(operationName = "findReferenceObjectBindingsByReferenceDiscriminatorType")
105    @XmlElementWrapper(name = "referenceObjectBindings", required = true)
106    @XmlElement(name = "referenceObjectBinding", required = false)
107    @WebResult(name = "referenceObjectBindings")
108    public List<ReferenceObjectBinding> findReferenceObjectBindingsByReferenceDiscriminatorType(
109            @WebParam(name = "referenceObjectReferenceDiscriminatorType") String referenceObjectReferenceDiscriminatorType) throws RiceIllegalArgumentException;
110
111    /**
112     * Retrieves list of ReferenceObjectBinding objects for the given krms obj
113     * discriminator type
114     *
115     * @param referenceObjectKrmsDiscriminatorType  reference object type
116     * @return list of ReferenceObjectBinding objects for the given discriminator
117     *         type
118     * @throws RiceIllegalArgumentException if the given  referenceObjectKrmsDiscriminatorType is
119     *                                      blank or invalid
120     */
121    @WebMethod(operationName = "findReferenceObjectBindingsByKrmsDiscriminatorType")
122    @XmlElementWrapper(name = "referenceObjectBindings", required = true)
123    @XmlElement(name = "referenceObjectBinding", required = false)
124    @WebResult(name = "referenceObjectBindings")
125    public List<ReferenceObjectBinding> findReferenceObjectBindingsByKrmsDiscriminatorType(
126            @WebParam(name = "referenceObjectKrmsDiscriminatorType") String referenceObjectKrmsDiscriminatorType) throws RiceIllegalArgumentException;
127
128    
129    /**
130     * Retrieves list of ReferenceObjectBinding objects for the given obj
131     * discriminator type and reference object id
132     *
133     * @param referenceObjectReferenceDiscriminatorType  reference object type
134     * @param referenceObjectId reference object id
135     * @return list of ReferenceObjectBinding objects for the given discriminator
136     *         type
137     * @throws RiceIllegalArgumentException if the given  referenceObjectKrmsDiscriminatorType or id is
138     *                                      blank or invalid
139     */
140    @WebMethod(operationName = "findReferenceObjectBindingsByReferenceObject ")
141    @XmlElementWrapper(name = "referenceObjectBindings", required = true)
142    @XmlElement(name = "referenceObjectBinding", required = false)
143    @WebResult(name = "referenceObjectBindings")
144    public List<ReferenceObjectBinding> findReferenceObjectBindingsByReferenceObject (
145            @WebParam(name = "referenceObjectReferenceDiscriminatorType") String referenceObjectReferenceDiscriminatorType, 
146            @WebParam(name = "referenceObjectId") String referenceObjectId) 
147            throws RiceIllegalArgumentException;
148    
149    /**
150     * Retrieves list of ReferenceObjectBinding objects for the given KRMS obj
151     * id.
152     *
153     * @param krmsObjectId identifier of the KRMS obj
154     * @return list of ReferenceObjectBinding objects for the given KRMS obj
155     * @throws RiceIllegalArgumentException if the given krmsObjectId is blank or
156     *                                      invalid
157     */
158    @WebMethod(operationName = "findReferenceObjectBindingsByKrmsObjectId")
159    @XmlElementWrapper(name = "referenceObjectBindings", required = true)
160    @XmlElement(name = "referenceObjectBinding", required = false)
161    @WebResult(name = "referenceObjectBindings")
162    public List<ReferenceObjectBinding> findReferenceObjectBindingsByKrmsObject(
163            @WebParam(name = "krmsObjectId") String krmsObjectId) throws RiceIllegalArgumentException;
164
165    /**
166     * Update the ReferenceObjectBinding object specified by the identifier in the
167     * given DTO
168     *
169     * @param referenceObjectBindingDefinition DTO with updated info and id of the object to be updated
170     * @throws RiceIllegalArgumentException if the given  referenceObjectBindingDefinition
171     *                                      is null or invalid
172     */
173    @WebMethod(operationName = "updateReferenceObjectBinding")
174    public void updateReferenceObjectBinding(ReferenceObjectBinding referenceObjectBindingDefinition) throws RiceIllegalArgumentException;
175
176    /**
177     * Delete the specified ReferenceObjectBinding object
178     *
179     * @param id identifier of the object to be deleted
180     * @throws RiceIllegalArgumentException if the given  id is null or invalid
181     */
182    @WebMethod(operationName = "deleteReferenceObjectBinding")
183    public void deleteReferenceObjectBinding(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
184
185    /**
186     * Query for ReferenceObjectBinding ids based on the given search criteria
187     * which is a Map of ReferenceObjectBinding field names to values. <p/> <p>
188     * This method returns it's results as a List of ReferenceObjectBinding ids
189     * that match the given search criteria. </p>
190     *
191     * @param queryByCriteria the criteria.  Cannot be null.
192     * @return a list of ids matching the given criteria properties.  An empty
193     *         list is returned if an invalid or non-existent criteria is
194     *         supplied.
195     * @throws RiceIllegalArgumentException if the queryByCriteria is null
196     */
197    @WebMethod(operationName = "findReferenceObjectBindingIds")
198    @XmlElementWrapper(name = "referenceObjectBindingIds", required = true)
199    @XmlElement(name = "referenceObjectBindingId", required = false)
200    @WebResult(name = "referenceObjectBindingIds")
201    List<String> findReferenceObjectBindingIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
202
203    ////
204    //// agenda methods
205    ////
206    /**
207     * Create Agenda
208     *
209     * @param agendaDefinition data for the new Agenda to be created
210     * @return newly created Agenda
211     * @throws RiceIllegalArgumentException if the given agendaDefinition is
212     *                                      null or invalid
213     */
214    @WebMethod(operationName = "createAgenda")
215    @WebResult(name = "agenda")
216    public AgendaDefinition createAgenda(@WebParam(name = "AgendaDefinition") AgendaDefinition agendaDefinition) throws RiceIllegalArgumentException;
217
218    /**
219     * Retrieve Agenda for the specified id
220     *
221     * @param id identifier for the Agenda
222     * @return specified Agenda
223     * @throws RiceIllegalArgumentException if the given id is null or invalid
224     */
225    @WebMethod(operationName = "getAgenda")
226    @WebResult(name = "agenda")
227    public AgendaDefinition getAgenda(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
228
229    /**
230     * Retrieve Agendas of the specified type
231     *
232     * @param typeId type of the Agenda
233     * @return list of Agendas of the specified type
234     * @throws RiceIllegalArgumentException if the given typeId is null or
235     *                                      invalid
236     */
237    @WebMethod(operationName = "getAgendasByType")
238    @XmlElementWrapper(name = "agendas", required = true)
239    @XmlElement(name = "agenda", required = false)
240    @WebResult(name = "agendas")
241    public List<AgendaDefinition> getAgendasByType(@WebParam(name = "typeId") String typeId) throws RiceIllegalArgumentException;
242
243    /**
244     * Retrieve Agendas associated with the specified context
245     *
246     * @param contextId  context of interest
247     * @return list of Agendas associated with the context
248     * @throws RiceIllegalArgumentException if the given contextId is null or
249     *                                      invalid
250     */
251    @WebMethod(operationName = "getAgendasByContext")
252    @XmlElementWrapper(name = "agendas", required = true)
253    @XmlElement(name = "agenda", required = false)
254    @WebResult(name = "agendas")
255    public List<AgendaDefinition> getAgendasByContext(@WebParam(name = "contextId") String contextId) throws RiceIllegalArgumentException;
256
257    /**
258     * Retrieve Agendas of the specified type and context
259     *
260     * @param typeId  type of the Agenda
261     * @param contextId  context of interest
262     * @return list of Agendas associated with the specified type and context
263     * @throws RiceIllegalArgumentException if the given typeId or contextId
264     *                                      null or invalid
265     */
266    @WebMethod(operationName = "getAgendasByTypeAndContext")
267    @XmlElementWrapper(name = "agendas", required = true)
268    @XmlElement(name = "agenda", required = false)
269    @WebResult(name = "agendas")
270    public List<AgendaDefinition> getAgendasByTypeAndContext(@WebParam(name = "typeId") String typeId,
271            @WebParam(name = "contextId") String contextId) throws RiceIllegalArgumentException;
272
273    /**
274     * Update the Agenda specified by the identifier in the input DTO
275     *
276     * @param agendaDefinition DTO with updated info and identifier of the object to be updated
277     * @throws RiceIllegalArgumentException if the given agendaDefinition is
278     *                                      null or invalid
279     */
280    @WebMethod(operationName = "updateAgenda")
281    public void updateAgenda(@WebParam(name = "agendaDefinition") AgendaDefinition agendaDefinition) throws RiceIllegalArgumentException;
282
283    /**
284     * Delete the specified Agenda
285     *
286     * @param id identifier of the object to be deleted
287     * @throws RiceIllegalArgumentException if the given id is null or invalid
288     */
289    @WebMethod(operationName = "deleteAgenda")
290    public void deleteAgenda(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
291
292    ////
293    //// agenda item methods
294    ////
295    /**
296     * Create AgendaItem
297     *
298     * @param agendaItemDefinition  data for the new AgendaItem to be created
299     * @return newly created AgendaItem
300     * @throws RiceIllegalArgumentException if the given agendaItemDefinition is
301     *                                      null or invalid
302     */
303    @WebMethod(operationName = "createAgendaItem")
304    @WebResult(name = "agendaItem")
305    public AgendaItemDefinition createAgendaItem(@WebParam(name = "AgendaItemDefinition") AgendaItemDefinition agendaItemDefinition) throws RiceIllegalArgumentException;
306
307    /**
308     * Retrieve AgendaItem by the specified identifier
309     *
310     * @param id identifier of the AgendaItem
311     * @return AgendaItem specified by the identifier
312     * @throws RiceIllegalArgumentException if the given id is null or invalid
313     */
314    @WebMethod(operationName = "getAgendaItem")
315    @WebResult(name = "agendaItem")
316    public AgendaItemDefinition getAgendaItem(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
317
318    /**
319     * Retrieve AgendaItems by specified type
320     *
321     * @param typeId type of the AgendaItems
322     * @return list of AgendaItems of the specified type
323     * @throws RiceIllegalArgumentException if the given typeId is null or
324     *                                      invalid
325     */
326    @WebMethod(operationName = "getAgendaItemsByType")
327    @XmlElementWrapper(name = "agendaItems", required = true)
328    @XmlElement(name = "agendaItem", required = false)
329    @WebResult(name = "agendaItems")
330    public List<AgendaItemDefinition> getAgendaItemsByType(@WebParam(name = "typeId") String typeId) throws RiceIllegalArgumentException;
331
332    /**
333     * Retrieve AgendaItems associated with a context
334     *
335     * @param contextId context identifier
336     * @return list of AgendaItems associated with a context
337     * @throws RiceIllegalArgumentException if the given  contextId is null or
338     *                                      invalid
339     */
340    @WebMethod(operationName = "getAgendaItemsByContext")
341    @XmlElementWrapper(name = "agendaItems", required = true)
342    @XmlElement(name = "agendaItem", required = false)
343    @WebResult(name = "agendaItems")
344    public List<AgendaItemDefinition> getAgendaItemsByContext(@WebParam(name = "contextId") String contextId) throws RiceIllegalArgumentException;
345
346    /**
347     * Retrieve AgendaItems by type and context
348     *
349     * @param typeId type of the Agendas
350     * @param contextId context with which the Agendas are associated
351     * @return list of AgendaItems of the specified type and context
352     * @throws RiceIllegalArgumentException if the given  typeId or contextId
353     *                                      null or invalid
354     */
355    @WebMethod(operationName = "getAgendaItemsByTypeAndContext")
356    @XmlElementWrapper(name = "agendaItems", required = true)
357    @XmlElement(name = "agendaItem", required = false)
358    @WebResult(name = "agendaItems")
359    public List<AgendaItemDefinition> getAgendaItemsByTypeAndContext(@WebParam(name = "typeId") String typeId,
360            @WebParam(name = "contextId") String contextId) throws RiceIllegalArgumentException;
361
362    /**
363     * Update an AgendaItem
364     *
365     * @param agendaItemDefinition  updated data for the AgendaItem, with id of the object to be updated
366     * @throws RiceIllegalArgumentException if the given  agendaItemDefinition
367     *                                      is null or invalid
368     */
369    @WebMethod(operationName = "updateAgendaItem")
370    public void updateAgendaItem(@WebParam(name = "agendaItemDefinition") AgendaItemDefinition agendaItemDefinition) throws RiceIllegalArgumentException;
371
372    /**
373     * Delete the specified AgendaItem
374     *
375     * @param id identifier of the AgendaItem to be deleted
376     * @throws RiceIllegalArgumentException if the given id is null or invalid
377     */
378    @WebMethod(operationName = "deleteAgendaItem")
379    public void deleteAgendaItem(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
380
381    ////
382    //// rule methods
383    ////
384    /**
385     * Create Rule
386     *
387     * @param ruleDefinition data for the new Rule to be created
388     * @return newly created Rule
389     * @throws RiceIllegalArgumentException if the given ruleDefinition is null
390     *                                      or invalid
391     */
392    @WebMethod(operationName = "createRule")
393    @WebResult(name = "rule")
394    public RuleDefinition createRule(@WebParam(name = "ruleDefinition") RuleDefinition ruleDefinition) throws RiceIllegalArgumentException;
395
396    /**
397     * Retrieves the rule for the given ruleId.  The rule includes the
398     * propositions which define the condition that is to be evaluated on the
399     * rule.  It also defines a collection of actions which will be invoked if
400     * the rule succeeds.
401     *
402     * @param ruleId the id of the rule to retrieve
403     * @return the rule definition, or null if no rule could be located for the
404     *         given ruleId
405     * @throws IllegalArgumentException if the given ruleId is null
406     */
407    @WebMethod(operationName = "getRule")
408    @WebResult(name = "rule")
409    @Cacheable(value = RuleDefinition.Cache.NAME, key = "'ruleId=' + #p0")
410    public RuleDefinition getRule(@WebParam(name = "ruleId") String ruleId);
411
412    /**
413     * Retrieves all of the rules for the given list of ruleIds.  The rule
414     * includes the propositions which define the condition that is to be
415     * evaluated on the rule.  It also defines a collection of actions which
416     * will be invoked if the rule succeeds.
417     * <p/>
418     * <p>The list which is returned from this operation may not be the same
419     * size as the list which is passed to this method.  If a rule doesn't exist
420     * for a given rule id then no result for that id will be returned in the
421     * list.  As a result of this, the returned list can be empty, but it will
422     * never be null.
423     *
424     * @param ruleIds the list of rule ids for which to retrieve the rules
425     * @return the list of rules for the given ids, this list will only contain
426     *         rules for the ids that were resolved successfully, it will never
427     *         return null but could return an empty list if no rules could be
428     *         loaded for the given set of ids
429     * @throws IllegalArgumentException if the given list of ruleIds is null
430     */
431    @WebMethod(operationName = "getRules")
432    @XmlElementWrapper(name = "rules", required = true)
433    @XmlElement(name = "rule", required = false)
434    @WebResult(name = "rules")
435    public List<RuleDefinition> getRules(@WebParam(name = "ruleIds") List<String> ruleIds);
436
437    /**
438     * Update the Rule specified by the identifier in the DTO
439     *
440     * @param ruleDefinition updated Rule information, object specified by the id
441     * @throws RiceIllegalArgumentException if the given ruleDefinition is null
442     *                                      or invalid
443     */
444    @WebMethod(operationName = "updateRule")
445    public void updateRule(@WebParam(name = "ruleDefinition") RuleDefinition ruleDefinition) throws RiceIllegalArgumentException;
446
447    /**
448     * Delete the specified Rule
449     *
450     * @param id identifier of the Rule to be deleted
451     * @throws RiceIllegalArgumentException if the given id is null or invalid
452     */
453    @WebMethod(operationName = "deleteRule")
454    public void deleteRule(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
455
456     ////
457    //// action methods
458    ////
459    /**
460     * Create Action
461     *
462     * @param actionDefinition data for the new Action to be created
463     * @return newly created Action
464     * @throws RiceIllegalArgumentException if the given actionDefinition is null
465     * or invalid
466     */
467    @WebMethod(operationName = "createAction")
468    @WebResult(name = "action")
469    public ActionDefinition createAction(@WebParam(name = "actionDefinition") ActionDefinition actionDefinition) throws RiceIllegalArgumentException;
470
471    /**
472     * Retrieves the action for the given actionId. The action includes the
473     * propositions which define the condition that is to be evaluated on the
474     * action. It also defines a collection of actions which will be invoked if
475     * the action succeeds.
476     *
477     * @param actionId the id of the action to retrieve
478     * @return the action definition, or null if no action could be located for the
479     * given actionId
480     * @throws IllegalArgumentException if the given actionId is null
481     */
482    @WebMethod(operationName = "getAction")
483    @WebResult(name = "action")
484    @Cacheable(value = ActionDefinition.Cache.NAME, key = "'actionId=' + #p0")
485    public ActionDefinition getAction(@WebParam(name = "actionId") String actionId) throws RiceIllegalArgumentException;
486
487    /**
488     * Retrieves all of the actions for the given list of actionIds.
489     * <p/>
490     * <p>The list which is returned from this operation may not be the same
491     * size as the list which is passed to this method. If a action doesn't exist
492     * for a given action id then no result for that id will be returned in the
493     * list. As a result of this, the returned list can be empty, but it will
494     * never be null.
495     *
496     * @param actionIds the list of action ids for which to retrieve the actions
497     * @return the list of actions for the given ids, this list will only contain
498     * actions for the ids that were resolved successfully, it will never return
499     * null but could return an empty list if no actions could be loaded for the
500     * given set of ids
501     * @throws IllegalArgumentException if the given list of actionIds is null
502     */
503    @WebMethod(operationName = "getActions")
504    @XmlElementWrapper(name = "actions", required = true)
505    @XmlElement(name = "action", required = false)
506    @WebResult(name = "actions")
507    public List<ActionDefinition> getActions(@WebParam(name = "actionIds") List<String> actionIds)  throws RiceIllegalArgumentException;
508
509    /**
510     * Update the Action specified by the identifier in the DTO
511     *
512     * @param actionDefinition updated Action information, object specified by the
513     * id
514     * @throws RiceIllegalArgumentException if the given actionDefinition is null
515     * or invalid
516     */
517    @WebMethod(operationName = "updateAction")
518    public void updateAction(@WebParam(name = "actionDefinition") ActionDefinition actionDefinition) throws RiceIllegalArgumentException;
519
520    /**
521     * Delete the specified Action
522     *
523     * @param id identifier of the Action to be deleted
524     * @throws RiceIllegalArgumentException if the given id is null or invalid
525     */
526    @WebMethod(operationName = "deleteAction")
527    public void deleteAction(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
528  
529    
530    ////
531    //// proposition methods
532    ////
533    /**
534     * Create a Proposition
535     *
536     * @param propositionDefinition data for the new Proposition to be created
537     * @return newly created Proposition
538     * @throws RiceIllegalArgumentException if the given propositionDefinition
539     *                                      is null or invalid
540     */
541    @WebMethod(operationName = "createProposition")
542    @WebResult(name = "proposition")
543    public PropositionDefinition createProposition(@WebParam(name = "propositionDefinition") PropositionDefinition propositionDefinition) throws RiceIllegalArgumentException;
544
545    /**
546     * Retrieve Proposition specified by the identifier
547     *
548     * @param id identifier of the Proposition to be retrieved
549     * @return specified Proposition
550     * @throws RiceIllegalArgumentException if the given id is null or invalid
551     */
552    @WebMethod(operationName = "getProposition")
553    @WebResult(name = "proposition")
554    public PropositionDefinition getProposition(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
555
556    /**
557     * Retrieve Propositions of the specified type
558     *
559     * @param typeId type of the Propositions to be retrieved
560     * @return list of Propositions of the specified type
561     * @throws RiceIllegalArgumentException if the given typeId is null or
562     *                                      invalid
563     */
564    @WebMethod(operationName = "getPropositionsByType")
565    @XmlElementWrapper(name = "propositions", required = true)
566    @XmlElement(name = "proposition", required = false)
567    @WebResult(name = "propositions")
568    public Set<PropositionDefinition> getPropositionsByType(@WebParam(name = "typeId") String typeId) throws RiceIllegalArgumentException;
569
570    /**
571     * Retrieve Propositions associated with the specified Rule
572     *
573     * @param ruleId identifier of the Rule to which the Propositions are associated with
574     * @return list of Propositions associated with the Rule
575     * @throws RiceIllegalArgumentException if the given ruleId is null or
576     *                                      invalid
577     */
578    @WebMethod(operationName = "getPropositionsByRule")
579    @XmlElementWrapper(name = "propositions", required = true)
580    @XmlElement(name = "proposition", required = false)
581    @WebResult(name = "propositions")
582    public Set<PropositionDefinition> getPropositionsByRule(@WebParam(name = "ruleId") String ruleId) throws RiceIllegalArgumentException;
583
584    /**
585     * Update the Proposition
586     *
587     * @param propositionDefinition updated data for the Proposition, id specifies the object to be updated
588     * @throws RiceIllegalArgumentException if the given propositionDefinition
589     *                                      is null or invalid
590     */
591    @WebMethod(operationName = "updateProposition")
592    public void updateProposition(
593            @WebParam(name = "propositionDefinition") PropositionDefinition propositionDefinition) throws RiceIllegalArgumentException;
594
595    /**
596     * Delete the Proposition
597     *
598     * @param id identifier of the Proposition to be deleted
599     * @throws RiceIllegalArgumentException if the given id is null or invalid
600     */
601    @WebMethod(operationName = "deleteProposition")
602    public void deleteProposition(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
603
604    ////
605    //// natural language usages
606    ////
607    /**
608     * Create NaturalLanguageUsage
609     *
610     * @param naturalLanguageUsage data for the new NaturalLanguageUsage to be created
611     * @return newly created NaturalLanguageUsage
612     * @throws RiceIllegalArgumentException if the given naturalLanguageUsage is
613     *                                      null or invalid
614     */
615    @WebMethod(operationName = "createNaturalLanguageUsage")
616    @WebResult(name = "naturalLanguageUsage")
617    public NaturalLanguageUsage createNaturalLanguageUsage(@WebParam(name = "naturalLanguageUsage") NaturalLanguageUsage naturalLanguageUsage) throws RiceIllegalArgumentException;
618
619    /**
620     * Retrieve NaturalLanguageUsage specified by the identifier
621     *
622     * @param id identifier of the NaturalLanguageUsage to be retrieved
623     * @return NaturalLanguageUsage specified by the identifier
624     * @throws RiceIllegalArgumentException if the given id is null or invalid
625     */
626    @WebMethod(operationName = "getNaturalLanguageUsage")
627    @WebResult(name = "naturalLanguageUsage")
628    public NaturalLanguageUsage getNaturalLanguageUsage(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
629
630    /**
631     * Retrieve NaturalLanguageUsage specified by name and namespace
632     *
633     * @param name the name of the natural language usage to retrieve.
634     * @param namespace the namespace that the natural language usage is under.
635     * @return an {@link NaturalLanguageUsage} identified by the given name and
636     * namespace. A null reference is returned if an invalid or non-existent
637     * name and namespace combination is supplied.
638     * @throws RiceIllegalArgumentException if the either the name or the
639     * namespace is null or blank.
640     */
641    @WebMethod(operationName = "getNaturalLanguageUsageByNameAndNamespace")
642    @WebResult(name = "naturalLanguageUsage")
643    public NaturalLanguageUsage getNaturalLanguageUsageByNameAndNamespace(@WebParam(name = "name") String name,
644            @WebParam(name = "namespace") String namespace)
645            throws RiceIllegalArgumentException;
646
647    /**
648     * Update NaturalLanguageUsage
649     *
650     * @param naturalLanguageUsage updated data for the NaturalLanguageUsage object specified by the id
651     * @throws RiceIllegalArgumentException if the given naturalLanguageUsage is
652     *                                      null or invalid
653     */
654    @WebMethod(operationName = "updateNaturalLanguageUsage")
655    public void updateNaturalLanguageUsage(@WebParam(name = "naturalLanguageUsage") NaturalLanguageUsage naturalLanguageUsage) throws RiceIllegalArgumentException;
656
657    /**
658     * Delete NaturalLanguageUsage
659     *
660     * @param naturalLanguageUsageId  identifier of the NaturalLanguageUsage to be deleted
661     * @throws RiceIllegalArgumentException  if the given naturalLanguageUsageId is null or invalid
662     */
663    @WebMethod(operationName = "deleteNaturalLanguageUsage")
664    public void deleteNaturalLanguageUsage(@WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId) throws RiceIllegalArgumentException;
665
666    /**
667     * Translates and retrieves a NaturalLanguage for a given KRMS object (e.g, proposition
668     * or agenda), NaturalLanguage usage type (context) and language into natural language
669     * TODO: Add appropriate caching annotation
670     *
671     * @param namespace namespace to search on.
672     * @return list of NaturalLanguageUsages in a particular namespace
673     */
674    @WebMethod(operationName = "getNaturalLanguageUsagesByNamespace")
675    @XmlElementWrapper(name = "naturalLanguageUsages", required = true)
676    @XmlElement(name = "naturalLanguageUsage", required = false)
677    @WebResult(name = "naturalLanguageUsages")
678    public List<NaturalLanguageUsage> getNaturalLanguageUsagesByNamespace(@WebParam(name = "namespace") String namespace)
679            throws RiceIllegalArgumentException;
680
681    ////
682    //// context methods
683    ////
684    /**
685     * Create Context
686     *
687     * @param contextDefinition data for the new Context to be created
688     * @return newly created Context
689     * @throws RiceIllegalArgumentException if the given contextDefinition is
690     * null or invalid or already in use.
691     */
692    @WebMethod(operationName = "createContext")
693    @WebResult(name = "context")
694    public ContextDefinition createContext(@WebParam(name = "contextDefinition") ContextDefinition contextDefinition) throws RiceIllegalArgumentException;
695
696    
697    /**
698     * find Create Context
699     * 
700     * Searches for an existing context with the same name and namespace and returns it
701     * otherwise it creates the context.
702     *
703     * @param contextDefinition data for the new Context to be created
704     * @return newly created Context
705     * @throws RiceIllegalArgumentException if the given contextDefinition is
706     * null or invalid
707     */
708    @WebMethod(operationName = "findCreateContext")
709    @WebResult(name = "context")
710    public ContextDefinition findCreateContext(@WebParam(name = "contextDefinition") ContextDefinition contextDefinition) throws RiceIllegalArgumentException;
711
712    
713    /**
714     * Update the Context specified by the identifier in the input DTO
715     *
716     * @param contextDefinition DTO with updated info and identifier of the
717     * object to be updated
718     * @throws RiceIllegalArgumentException if the given contextDefinition is
719     * null or invalid
720     */
721    @WebMethod(operationName = "updateContext")
722    public void updateContext(@WebParam(name = "contextDefinition") ContextDefinition contextDefinition) throws RiceIllegalArgumentException;
723
724    /**
725     * Delete the specified Context
726     *
727     * @param id identifier of the object to be deleted
728     * @throws RiceIllegalArgumentException if the given id is null or invalid
729     */
730    @WebMethod(operationName = "deleteContext")
731    public void deleteContext(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
732
733    /**
734     * Retrieve Context for the specified id
735     *
736     * @param id identifier for the Context
737     * @return specified Context
738     * @throws RiceIllegalArgumentException if the given id is null or invalid
739     */
740    @WebMethod(operationName = "getContext")
741    @WebResult(name = "context")
742    public ContextDefinition getContext(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
743
744    /**
745     * Retrieves an Context from the repository based on the provided context
746     * name and namespace.
747     *
748     * @param name the name of the Context to retrieve.
749     * @param namespace the namespace that the context is under.
750     * @return an {@link ContextDefinition} identified by the given name and
751     * namespace. A null reference is returned if an invalid or non-existent
752     * name and namespace combination is supplied.
753     * @throws RiceIllegalArgumentException if the either the name or the
754     * namespace is null or blank.
755     */
756    @WebMethod(operationName = "getContextByNameAndNamespace")
757    @WebResult(name = "context")
758    public ContextDefinition getContextByNameAndNamespace(@WebParam(name = "name") String name,
759            @WebParam(name = "namespace") String namespace)
760            throws RiceIllegalArgumentException;
761
762    //// natural languatge template methods
763    /**
764     * This will create a {@link NaturalLanguageTemplate} exactly like the
765     * parameter passed in except the id will be assigned and create date/user 
766     * will be set.
767     *
768     * @param naturalLanguageTemplate The NaturalLanguageTemplate to create.
769     * @throws RiceIllegalArgumentException if the NaturalLanguageTemplate is null.
770     * @throws IllegalStateException if the NaturalLanguageTemplate already
771     * exists in the system.
772     * @return a {@link NaturalLanguageTemplate} exactly like the parameter
773     * passed in.
774     *
775     */
776    @WebMethod(operationName = "createNaturalLanguageTemplate")
777    @WebResult(name = "naturalLanguageTemplate")
778    public NaturalLanguageTemplate createNaturalLanguageTemplate(@WebParam(name = "naturalLanguageTemplate") NaturalLanguageTemplate naturalLanguageTemplate)
779            throws RiceIllegalArgumentException;
780
781    /**
782     * Retrieves a NaturalLanguageTemplate from the repository based on the
783     * given id.
784     *
785     * @param naturalLanguageTemplateId to retrieve.
786     * @return a {@link NaturalLanguageTemplate} identified by the given id. 
787     * @throws IllegalArgumentException if the given actionId is null     *
788     */
789    @WebMethod(operationName = "getNaturalLanguageTemplate")
790    @WebResult(name = "naturalLanguageTemplate")
791    public NaturalLanguageTemplate getNaturalLanguageTemplate(@WebParam(name = "naturalLanguageTemplateId") String naturalLanguageTemplateId)
792            throws RiceIllegalArgumentException;
793
794    /**
795     * This will update an existing {@link NaturalLanguageTemplate}.
796     *
797     * @param naturalLanguageTemplate The NaturalLanguageTemplate to update.
798     * @throws RiceIllegalArgumentException if the NaturalLanguageTemplate is null.
799     * exists in the system.
800     *
801     */
802    @WebMethod(operationName = "updateNaturalLanguageTemplate")
803    public void updateNaturalLanguageTemplate(@WebParam(name = "naturalLanguageTemplate") NaturalLanguageTemplate naturalLanguageTemplate)
804            throws RiceIllegalArgumentException;
805
806    /**
807     * Delete the {@link NaturalLanguageTemplate} with the given id.
808     *
809     * @param naturalLanguageTemplateId to delete.
810     * @throws RiceIllegalArgumentException if the NaturalLanguageTemplate is null.
811     *
812     */
813    @WebMethod(operationName = "deleteNaturalLanguageTemplate")
814    public void deleteNaturalLanguageTemplate(@WebParam(name = "naturalLanguageTemplateId") String naturalLanguageTemplateId)
815            throws RiceIllegalArgumentException;
816
817    /**
818     * Finds all the natural language templates for a particular language
819     *
820     * @param languageCode language on which to search
821     * @return list of templates for that language
822     */
823    @WebMethod(operationName = "findNaturalLanguageTemplatesByLanguageCode")
824    @XmlElementWrapper(name = "naturalLangaugeTemplates", required = true)
825    @XmlElement(name = "naturalLangaugeTemplate", required = false)
826    @WebResult(name = "naturalLangaugeTemplates")
827    public List<NaturalLanguageTemplate> findNaturalLanguageTemplatesByLanguageCode(@WebParam(name = "languageCode") String languageCode)
828            throws RiceIllegalArgumentException;
829
830    @WebMethod(operationName = "findNaturalLanguageTemplateByLanguageCodeTypeIdAndNluId")
831    @WebResult(name = "naturalLangaugeTemplate")
832    public NaturalLanguageTemplate findNaturalLanguageTemplateByLanguageCodeTypeIdAndNluId(@WebParam(name = "languageCode") String languageCode,
833            @WebParam(name = "typeId") String typeId,
834            @WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId)
835            throws RiceIllegalArgumentException;
836
837    /**
838     * Find all the natural language templates for a particular usage
839     *
840     * @param naturalLanguageUsageId the usage on which to search
841     * @return list of templates that match the usage
842     */
843    @WebMethod(operationName = "findNaturalLanguageTemplatesByNaturalLanguageUsage")
844    @XmlElementWrapper(name = "naturalLangaugeTemplates", required = true)
845    @XmlElement(name = "naturalLangaugeTemplate", required = false)
846    @WebResult(name = "naturalLangaugeTemplates")
847    public List<NaturalLanguageTemplate> findNaturalLanguageTemplatesByNaturalLanguageUsage(@WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId)
848            throws RiceIllegalArgumentException;
849
850    /**
851     * Find all the natural language templates of a particular type
852     *
853     * Template types are keys that identify the message that is to be expressed
854     * in different languages and in different usage scenarios
855     *
856     * @param typeId on which to search
857     * @return list of templates matching that type
858     */
859    @WebMethod(operationName = "findNaturalLanguageTemplatesByType")
860    @XmlElementWrapper(name = "naturalLangaugeTemplates", required = true)
861    @XmlElement(name = "naturalLangaugeTemplate", required = false)
862    @WebResult(name = "naturalLangaugeTemplates")
863    public List<NaturalLanguageTemplate> findNaturalLanguageTemplatesByType(@WebParam(name = "typeId") String typeId)
864            throws RiceIllegalArgumentException;
865
866    /**
867     * Find the natural language template using the actual text of the template.
868     *
869     * @param template text to match exactly
870     * @return list of matching templates
871     */
872    @WebMethod(operationName = "findNaturalLanguageTemplatesByTemplate")
873    @XmlElementWrapper(name = "naturalLangaugeTemplates", required = true)
874    @XmlElement(name = "naturalLangaugeTemplate", required = false)
875    @WebResult(name = "naturalLangaugeTemplates")
876    public List<NaturalLanguageTemplate> findNaturalLanguageTemplatesByTemplate(@WebParam(name = "template") String template)
877            throws RiceIllegalArgumentException;
878
879    ////
880    //// translation methods
881    ////
882    /**
883     * Translates and retrieves a NaturalLanguage for a given KRMS object (e.g,
884     * proposition or agenda), NaturalLanguage usage type (context) and language
885     * into natural language TODO: Add appropriate caching annotation
886     *
887     * @param naturalLanguageUsageId Natural language usage information
888     * @param typeId    KRMS object type id (for example, could refer to agenda
889     *                  or proposition)
890     * @param krmsObjectId KRMS object identifier
891     * @param languageCode  desired
892     * @return natural language corresponding to the NaturalLanguage usage, KRMS object id, KRMS object type and desired language
893     * @throws RiceIllegalArgumentException if the given naturalLanguageUsageId, typeId,
894     *                                      krmsObjectId or language is null or
895     *                                      invalid
896     */
897    @WebMethod(operationName = "translateNaturalLanguageForObject")
898    @WebResult(name = "naturalLanguage")
899    @Override
900    public String translateNaturalLanguageForObject(@WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId,
901            @WebParam(name = "typeId") String typeId, @WebParam(name = "krmsObjectId") String krmsObjectId,
902            @WebParam(name = "languageCode") String languageCode) throws RiceIllegalArgumentException;
903
904    /**
905     * Retrieve all the NaturalLanguageUsages
906     *
907     * @return list of NaturalLanguageUsages
908     */
909    @WebMethod(operationName = "translateNaturalLanguageForProposition")
910    @WebResult(name = "naturalLanguage")
911    @Override
912    public String translateNaturalLanguageForProposition(@WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId,
913            @WebParam(name = "propositionDefinintion") PropositionDefinition propositionDefinintion,
914            @WebParam(name = "languageCode") String languageCode)
915            throws RiceIllegalArgumentException;
916
917    /**
918     * Translates NaturalLanguage for a given proposition, returning a tree of
919     * the NaturalLanguage.
920     *
921     * This method is used to "preview" the proposition in a tree structure
922     * before saving.
923     *
924     * @param naturalLanguageUsageId Natural language usage information
925     * @param propositionDefinintion proposition to be translated
926     * @param languageCode desired
927     * @return natural language tree corresponding to the NaturalLanguage usage,
928     * proposition and desired language
929     * @throws RiceIllegalArgumentException if the given naturalLanguageUsageId,
930     * proposition, or language is null or invalid
931     */
932    @WebMethod(operationName = "translateNaturalLanguageTreeForProposition")
933    @WebResult(name = "naturalLanguageTree")
934    @Override
935    public NaturalLanguageTree translateNaturalLanguageTreeForProposition(@WebParam(name = "naturalLanguageUsageId") String naturalLanguageUsageId,
936            @WebParam(name = "propositionDefinintion") PropositionDefinition propositionDefinintion,
937            @WebParam(name = "languageCode") String languageCode)
938            throws RiceIllegalArgumentException;
939
940  
941    /**
942     * Query for Context ids based on the given search criteria which is a Map
943     * of Context field names to values.
944     * <p/>
945     * <p> This method returns it's results as a List of Context ids that match
946     * the given search criteria. </p>
947     *
948     * @param queryByCriteria the criteria. Cannot be null.
949     * @return a list of ids matching the given criteria properties. An empty
950     * list is returned if an invalid or non-existent criteria is supplied.
951     * @throws RiceIllegalArgumentException if the queryByCriteria is null
952     */
953    @WebMethod(operationName = "findContextIds")
954    @XmlElementWrapper(name = "contextIds", required = true)
955    @XmlElement(name = "context", required = false)
956    @WebResult(name = "contextIds")
957    List<String> findContextIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
958
959    /**
960     * Query for Agenda ids based on the given search criteria which is a Map of
961     * Agenda field names to values.
962     * <p/>
963     * <p> This method returns it's results as a List of Agenda ids that match
964     * the given search criteria. </p>
965     *
966     * @param queryByCriteria the criteria. Cannot be null.
967     * @return a list of ids matching the given criteria properties. An empty
968     * list is returned if an invalid or non-existent criteria is supplied.
969     * @throws RiceIllegalArgumentException if the queryByCriteria is null
970     */
971    @WebMethod(operationName = "findAgendaIds")
972    @XmlElementWrapper(name = "contextIds", required = true)
973    @XmlElement(name = "agenda", required = false)
974    @WebResult(name = "agendaIds")
975    List<String> findAgendaIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
976
977    /**
978     * Query for Rule ids based on the given search criteria which is a Map of
979     * Rule field names to values.
980     * <p/>
981     * <p> This method returns it's results as a List of Rule ids that match the
982     * given search criteria. </p>
983     *
984     * @param queryByCriteria the criteria. Cannot be null.
985     * @return a list of ids matching the given criteria properties. An empty
986     * list is returned if an invalid or non-existent criteria is supplied.
987     * @throws RiceIllegalArgumentException if the queryByCriteria is null
988     */
989    @WebMethod(operationName = "findRuleIds")
990    @XmlElementWrapper(name = "ruleIds", required = true)
991    @XmlElement(name = "rule", required = false)
992    @WebResult(name = "ruleIds")
993    List<String> findRuleIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
994
995    /**
996     * Query for Proposition ids based on the given search criteria which is a
997     * Map of Proposition field names to values.
998     * <p/>
999     * <p> This method returns it's results as a List of Proposition ids that
1000     * match the given search criteria. </p>
1001     *
1002     * @param queryByCriteria the criteria. Cannot be null.
1003     * @return a list of ids matching the given criteria properties. An empty
1004     * list is returned if an invalid or non-existent criteria is supplied.
1005     * @throws RiceIllegalArgumentException if the queryByCriteria is null
1006     */
1007    @WebMethod(operationName = "findPropositionIds")
1008    @XmlElementWrapper(name = "propositionIds", required = true)
1009    @XmlElement(name = "proposition", required = false)
1010    @WebResult(name = "propositionIds")
1011    List<String> findPropositionIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
1012
1013    /**
1014     * Query for Action ids based on the given search criteria which is a Map
1015     * of Action field names to values.
1016     * <p/>
1017     * <p> This method returns it's results as a List of Action ids that match
1018     * the given search criteria. </p>
1019     *
1020     * @param queryByCriteria the criteria. Cannot be null.
1021     * @return a list of ids matching the given criteria properties. An empty
1022     * list is returned if an invalid or non-existent criteria is supplied.
1023     * @throws RiceIllegalArgumentException if the queryByCriteria is null
1024     */
1025    @WebMethod(operationName = "findActionIds")
1026    @XmlElementWrapper(name = "actionIds", required = true)
1027    @XmlElement(name = "action", required = false)
1028    @WebResult(name = "actionIds")
1029    List<String> findActionIds(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
1030}