001 /**
002 * Copyright 2005-2012 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.kuali.rice.krms.api.repository;
017
018 import org.kuali.rice.core.api.criteria.QueryByCriteria;
019 import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
020 import org.kuali.rice.krms.api.KrmsConstants;
021 import org.kuali.rice.krms.api.repository.agenda.AgendaDefinition;
022 import org.kuali.rice.krms.api.repository.agenda.AgendaItemDefinition;
023 import org.kuali.rice.krms.api.repository.language.NaturalLanguageUsage;
024 import org.kuali.rice.krms.api.repository.proposition.PropositionDefinition;
025 import org.kuali.rice.krms.api.repository.reference.ReferenceObjectBinding;
026 import org.kuali.rice.krms.api.repository.rule.RuleDefinition;
027 import org.springframework.cache.annotation.Cacheable;
028
029 import javax.jws.WebMethod;
030 import javax.jws.WebParam;
031 import javax.jws.WebResult;
032 import javax.jws.WebService;
033 import javax.jws.soap.SOAPBinding;
034 import javax.xml.bind.annotation.XmlElement;
035 import javax.xml.bind.annotation.XmlElementWrapper;
036 import java.util.List;
037 import java.util.Set;
038 import org.kuali.rice.krms.api.repository.action.ActionDefinition;
039 import org.kuali.rice.krms.api.repository.context.ContextDefinition;
040 import 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,
050 parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
051 public 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 }