001/**
002 * Copyright 2005-2016 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.exception.RiceIllegalArgumentException;
019import org.kuali.rice.krms.api.KrmsConstants;
020import org.kuali.rice.krms.api.repository.agenda.AgendaTreeDefinition;
021import org.kuali.rice.krms.api.repository.context.ContextDefinition;
022import org.kuali.rice.krms.api.repository.context.ContextSelectionCriteria;
023import org.kuali.rice.krms.api.repository.rule.RuleDefinition;
024import org.springframework.cache.annotation.Cacheable;
025
026import javax.jws.WebMethod;
027import javax.jws.WebParam;
028import javax.jws.WebResult;
029import javax.jws.WebService;
030import javax.jws.soap.SOAPBinding;
031import javax.xml.bind.annotation.XmlElement;
032import javax.xml.bind.annotation.XmlElementWrapper;
033import java.util.List;
034
035/**
036 * The rule repository contains all of the information about context definitions,
037 * agendas, and business rules.
038 * 
039 * @author Kuali Rice Team (rice.collab@kuali.org)
040 *
041 */
042@WebService(name = "ruleRepositoryService", targetNamespace = KrmsConstants.Namespaces.KRMS_NAMESPACE_2_0)
043@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
044public interface RuleRepositoryService {
045
046        /**
047         * Locates a ContextDefinition based on the given map of context qualifiers. The requirements for valid selection
048     * criteria are implementation dependent.  An IllegalArgumentException may be thrown if the implementation can't
049     * operate with the given criteria.
050         * 
051         * @param contextSelectionCriteria
052         * @return
053     * @see ContextSelectionCriteria
054     * @throws RiceIllegalArgumentException if the implementation can't handle the given ContextSelectionCriteria
055         */
056        @WebMethod(operationName = "selectContext")
057        @WebResult(name = "contextDefinition")
058        public ContextDefinition selectContext(@WebParam(name = "contextSelectionCriteria") ContextSelectionCriteria contextSelectionCriteria)
059            throws RiceIllegalArgumentException;
060        
061        /**
062         * Retrieves the agenda tree for the given agendaId.  The agenda tree includes
063         * the entire agenda definition in the appropriate order and with the
064         * defined agenda branching.
065         * 
066         * @param agendaId the id of the agenda for which to retrieve the agenda tree
067         * @return the agenda tree, or null if no agenda could be located for the given agendaId
068         * 
069         * @throws RiceIllegalArgumentException if the given agendaId is null
070         */
071        @WebMethod(operationName = "getAgendaTree")
072        @WebResult(name = "agendaTree")
073    @Cacheable(value= AgendaTreeDefinition.Cache.NAME, key="'agendaId=' + #p0")
074        public AgendaTreeDefinition getAgendaTree(@WebParam(name = "agendaId") String agendaId)
075            throws RiceIllegalArgumentException;
076
077    /**
078         * Retrieves all of the agendas trees for the given list of agendaIds.  The agenda tree includes
079         * the entire agenda definition in the appropriate order and with the
080         * defined agenda branching.
081         * 
082         * <p>The list which is returned from this operation may not be the same size as the list
083         * which is passed to this method.  If an agenda doesn't exist for a given agenda id then
084         * no result for that id will be returned in the list.  As a result of this, the returned
085         * list can be empty, but it will never be null.
086         * 
087         * @param agendaIds the list of agenda ids for which to retrieve the agenda trees
088         * @return the list of agenda trees for the given ids, this list will only contain agenda trees for the ids
089         * that were resolved successfully, it will never return null but could return an empty list if no agenda
090         * trees could be loaded for the given set of ids
091         * 
092         * @throws RiceIllegalArgumentException if the given list of agendaIds is null
093         */
094        @WebMethod(operationName = "getAgendaTrees")
095    @XmlElementWrapper(name = "agendaTrees", required = true)
096    @XmlElement(name = "agendaTree", required = false)
097        @WebResult(name = "agendaTrees")
098        public List<AgendaTreeDefinition> getAgendaTrees(@WebParam(name = "agendaIds") List<String> agendaIds)
099            throws RiceIllegalArgumentException;
100
101    /**
102         * Retrieves the rule for the given ruleId.  The rule includes the propositions
103         * which define the condition that is to be evaluated on the rule.  It also
104         * defines a collection of actions which will be invoked if the rule succeeds.
105         * 
106         * @param ruleId the id of the rule to retrieve
107         * @return the rule definition, or null if no rule could be located for the given ruleId
108         * 
109         * @throws RiceIllegalArgumentException if the given ruleId is null
110         */
111        @WebMethod(operationName = "getRule")
112        @WebResult(name = "rule")
113    @Cacheable(value= RuleDefinition.Cache.NAME, key="'ruleId=' + #p0")
114        public RuleDefinition getRule(@WebParam(name = "ruleId") String ruleId) throws RiceIllegalArgumentException;
115        
116        /**
117         * Retrieves all of the rules for the given list of ruleIds.  The rule includes the propositions
118         * which define the condition that is to be evaluated on the rule.  It also
119         * defines a collection of actions which will be invoked if the rule succeeds.
120         * 
121         * <p>The list which is returned from this operation may not be the same size as the list
122         * which is passed to this method.  If a rule doesn't exist for a given rule id then
123         * no result for that id will be returned in the list.  As a result of this, the returned
124         * list can be empty, but it will never be null.
125         * 
126         * @param ruleIds the list of rule ids for which to retrieve the rules
127         * @return the list of rules for the given ids, this list will only contain rules for the ids
128         * that were resolved successfully, it will never return null but could return an empty list if no
129         * rules could be loaded for the given set of ids
130         * 
131         * @throws RiceIllegalArgumentException if the given list of ruleIds is null
132         */
133        @WebMethod(operationName = "getRules")
134    @XmlElementWrapper(name = "rules", required = true)
135    @XmlElement(name = "rule", required = false)
136        @WebResult(name = "rules")
137        public List<RuleDefinition> getRules(@WebParam(name = "ruleIds") List<String> ruleIds)
138            throws RiceIllegalArgumentException;
139
140}