001/**
002 * Copyright 2005-2018 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        @Cacheable(value= ContextDefinition.Cache.NAME, key="'contextSelectionCriteria=' + #p0.getNamespaceCode() + #p0.getName()")
059        public ContextDefinition selectContext(@WebParam(name = "contextSelectionCriteria") ContextSelectionCriteria contextSelectionCriteria)
060            throws RiceIllegalArgumentException;
061        
062        /**
063         * Retrieves the agenda tree for the given agendaId.  The agenda tree includes
064         * the entire agenda definition in the appropriate order and with the
065         * defined agenda branching.
066         * 
067         * @param agendaId the id of the agenda for which to retrieve the agenda tree
068         * @return the agenda tree, or null if no agenda could be located for the given agendaId
069         * 
070         * @throws RiceIllegalArgumentException if the given agendaId is null
071         */
072        @WebMethod(operationName = "getAgendaTree")
073        @WebResult(name = "agendaTree")
074    @Cacheable(value= AgendaTreeDefinition.Cache.NAME, key="'agendaId=' + #p0")
075        public AgendaTreeDefinition getAgendaTree(@WebParam(name = "agendaId") String agendaId)
076            throws RiceIllegalArgumentException;
077
078    /**
079         * Retrieves all of the agendas trees for the given list of agendaIds.  The agenda tree includes
080         * the entire agenda definition in the appropriate order and with the
081         * defined agenda branching.
082         * 
083         * <p>The list which is returned from this operation may not be the same size as the list
084         * which is passed to this method.  If an agenda doesn't exist for a given agenda id then
085         * no result for that id will be returned in the list.  As a result of this, the returned
086         * list can be empty, but it will never be null.
087         * 
088         * @param agendaIds the list of agenda ids for which to retrieve the agenda trees
089         * @return the list of agenda trees for the given ids, this list will only contain agenda trees for the ids
090         * that were resolved successfully, it will never return null but could return an empty list if no agenda
091         * trees could be loaded for the given set of ids
092         * 
093         * @throws RiceIllegalArgumentException if the given list of agendaIds is null
094         */
095        @WebMethod(operationName = "getAgendaTrees")
096    @XmlElementWrapper(name = "agendaTrees", required = true)
097    @XmlElement(name = "agendaTree", required = false)
098        @WebResult(name = "agendaTrees")
099        @Cacheable(value= AgendaTreeDefinition.Cache.NAME, key="'agendaIds=' + #p0.toString()")
100        public List<AgendaTreeDefinition> getAgendaTrees(@WebParam(name = "agendaIds") List<String> agendaIds)
101            throws RiceIllegalArgumentException;
102
103    /**
104         * Retrieves the rule for the given ruleId.  The rule includes the propositions
105         * which define the condition that is to be evaluated on the rule.  It also
106         * defines a collection of actions which will be invoked if the rule succeeds.
107         * 
108         * @param ruleId the id of the rule to retrieve
109         * @return the rule definition, or null if no rule could be located for the given ruleId
110         * 
111         * @throws RiceIllegalArgumentException if the given ruleId is null
112         */
113        @WebMethod(operationName = "getRule")
114        @WebResult(name = "rule")
115    @Cacheable(value= RuleDefinition.Cache.NAME, key="'ruleId=' + #p0")
116        public RuleDefinition getRule(@WebParam(name = "ruleId") String ruleId) throws RiceIllegalArgumentException;
117        
118        /**
119         * Retrieves all of the rules for the given list of ruleIds.  The rule includes the propositions
120         * which define the condition that is to be evaluated on the rule.  It also
121         * defines a collection of actions which will be invoked if the rule succeeds.
122         * 
123         * <p>The list which is returned from this operation may not be the same size as the list
124         * which is passed to this method.  If a rule doesn't exist for a given rule id then
125         * no result for that id will be returned in the list.  As a result of this, the returned
126         * list can be empty, but it will never be null.
127         * 
128         * @param ruleIds the list of rule ids for which to retrieve the rules
129         * @return the list of rules for the given ids, this list will only contain rules for the ids
130         * that were resolved successfully, it will never return null but could return an empty list if no
131         * rules could be loaded for the given set of ids
132         * 
133         * @throws RiceIllegalArgumentException if the given list of ruleIds is null
134         */
135        @WebMethod(operationName = "getRules")
136    @XmlElementWrapper(name = "rules", required = true)
137    @XmlElement(name = "rule", required = false)
138        @WebResult(name = "rules")
139        @Cacheable(value= RuleDefinition.Cache.NAME, key="'ruleIds=' + #p0.toString()")
140        public List<RuleDefinition> getRules(@WebParam(name = "ruleIds") List<String> ruleIds)
141            throws RiceIllegalArgumentException;
142
143}