001/**
002 * Copyright 2005-2017 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.impl.repository;
017
018import java.util.List;
019import java.util.Set;
020
021import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
022import org.kuali.rice.krms.api.repository.agenda.AgendaDefinition;
023import org.kuali.rice.krms.api.repository.agenda.AgendaItemDefinition;
024import org.kuali.rice.krms.api.repository.agenda.AgendaTreeDefinition;
025import org.kuali.rice.krms.api.repository.context.ContextDefinition;
026import org.springframework.cache.annotation.CacheEvict;
027import org.springframework.cache.annotation.Cacheable;
028
029/**
030 * This is the interface for accessing KRMS repository Agenda related
031 * business objects. 
032 * 
033 * @author Kuali Rice Team (rice.collab@kuali.org)
034 *
035 */
036public interface AgendaBoService {
037
038    /**
039     * This will create a {@link AgendaDefinition} exactly like the parameter passed in.
040     *
041     * @param agenda  The Agenda to create
042     * @throws IllegalArgumentException if the Agenda is null
043     * @throws IllegalStateException if the Agenda already exists in the system
044     */
045    @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
046        public AgendaDefinition createAgenda(AgendaDefinition agenda);
047        
048    /**
049     * This will update an existing {@link AgendaDefinition}.
050     *
051     * @param agenda  The Agenda to update
052     * @throws IllegalArgumentException if the Agenda is null
053     * @throws IllegalStateException if the Agenda does not exists in the system
054     */
055    @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
056        public AgendaDefinition updateAgenda(AgendaDefinition agenda);
057
058    /**
059     * Delete the {@link AgendaDefinition} with the given id.
060     *
061     * @param agendaId to delete.
062     * @throws IllegalArgumentException if the Agenda is null.
063     * @throws IllegalStateException if the Agenda does not exists in the system
064     *
065     */
066    @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
067    public void deleteAgenda(String agendaId);
068
069    /**
070     * Retrieves an Agenda from the repository based on the given agenda id.
071     *
072     * @param agendaId the id of the Agenda to retrieve
073     * @return an {@link AgendaDefinition} identified by the given agendaId.  
074     * A null reference is returned if an invalid or non-existent id is supplied.
075     */
076    @Cacheable(value= AgendaDefinition.Cache.NAME, key="'agendaId=' + #p0")
077        public AgendaDefinition getAgendaByAgendaId(String agendaId);
078        
079    /**
080     * Retrieves an Agenda from the repository based on the provided agenda name
081     * and context id.
082     *
083     * @param name the name of the Agenda to retrieve.
084     * @param contextId the id of the context that the agenda belongs to.
085     * @return an {@link AgendaDefinition} identified by the given name and namespace.  
086     * A null reference is returned if an invalid or non-existent name and
087     * namespace combination is supplied.
088     */
089    @Cacheable(value= AgendaDefinition.Cache.NAME, key="'name=' + #p0 + '|' + 'contextId=' + #p1")
090        public AgendaDefinition getAgendaByNameAndContextId(String name, String contextId);
091        
092    /**
093     * Retrieves a set of Agendas associated with a context.
094     *
095     * @param contextId the id of the context
096     * @return a set of {@link AgendaDefinition} associated with the given context.  
097     * A null reference is returned if an invalid or contextId is supplied.
098     */
099    @Cacheable(value= AgendaDefinition.Cache.NAME, key="'contextId=' + #p0")
100        public List<AgendaDefinition> getAgendasByContextId(String contextId);
101        
102    /**
103     * This will create an {@link org.kuali.rice.krms.api.repository.agenda.AgendaItemDefinition} in the repository exactly like
104     * the parameter passed in.
105     *
106     * @param agendaItem  The AgendaItemDefinition to create
107     * @throws IllegalArgumentException if the AgendaItemDefinition is null
108     * @throws IllegalStateException if the AgendaItemDefinition already exists in the system
109     */
110    @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
111        public AgendaItemDefinition createAgendaItem(AgendaItemDefinition agendaItem);
112        
113    /**
114     * This will update an existing {@link org.kuali.rice.krms.api.repository.agenda.AgendaItemDefinition}.
115     *
116     * @param agendaItem  The AgendaItemDefinition to update
117     * @throws IllegalArgumentException if the AgendaItemDefinition is null
118     * @throws IllegalStateException if the AgendaItemDefinition does not exists in the system
119     */
120    @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
121        public AgendaItemDefinition updateAgendaItem(AgendaItemDefinition agendaItem);
122        
123    /**
124     * This will create an {@link org.kuali.rice.krms.api.repository.agenda.AgendaItemDefinition} in the repository exactly like
125     * the parameter passed in.  The AgendaItemDefinition will be linked to an existing
126     * AgendaItemDefinition in the relationship provided. Linking the AgendaItems effectively
127     * builds a tree of AgendaItems that may be traversed by the engine.
128     *
129     * @param agendaItem  The AgendaItemDefinition to create
130     * @param parentId  The id of the existing AgendaItemDefinition to be linked with the
131     *  newly created AgendaItemDefinition
132     * @param position A boolean used to specify the relationship between the
133     *  linked AgendaItems.
134     *  <p> If the position parameter is true, the new AgendaItemDefinition is linked as the next
135     *  AgendaItemDefinition to be evaluated if the parent AgendaItemDefinition evaluates to TRUE.
136     *  <p> If the position parameter is false, the new AgendaItemDefinition is linked as the next
137     *  AgendaItemDefinition to be evaluated if the parent AgendaItemDefinition evaluates to FALSE.
138     *  <p> If the position parameter is null,  the new AgendaItemDefinition is linked as the next
139     *  AgendaItemDefinition to be evaluated after any true or false branches of the tree have
140     *  been traversed.
141     * @throws IllegalArgumentException if the AgendaItemDefinition is null
142     * @throws IllegalStateException if the parent AgendaItemDefinition does not already exists in the system
143     */
144    @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
145        public void addAgendaItem(AgendaItemDefinition agendaItem, String parentId, Boolean position);
146        
147    /**
148     * Retrieves an AgendaItemDefinition from the repository based on the given agenda id.
149     *
150     * @param id the id of the AgendaItemDefinition to retrieve
151     * @return an {@link org.kuali.rice.krms.api.repository.agenda.AgendaItemDefinition} identified by the given id.
152     * A null reference is returned if an invalid or non-existent id is supplied.
153     */
154    @Cacheable(value= AgendaItemDefinition.Cache.NAME, key="'id=' + #p0")
155        public AgendaItemDefinition getAgendaItemById(String id);
156
157    // TODO: caching annotations
158    public List<AgendaItemDefinition> getAgendaItemsByAgendaId(String id);
159
160    // TODO: caching annotations
161    public List<AgendaDefinition> getAgendasByType(String typeId) throws RiceIllegalArgumentException;
162
163    // TODO: caching annotations
164    public List<AgendaDefinition> getAgendasByTypeAndContext(String typeId, String contextId)
165            throws RiceIllegalArgumentException;
166
167    // TODO: caching annotations
168    public List<AgendaItemDefinition> getAgendaItemsByType(String typeId) throws RiceIllegalArgumentException;
169
170    // TODO: caching annotations
171    public List<AgendaItemDefinition> getAgendaItemsByContext(String contextId) throws RiceIllegalArgumentException;
172
173    // TODO: caching annotations
174    public List<AgendaItemDefinition> getAgendaItemsByTypeAndContext(String typeId, String contextId)
175            throws RiceIllegalArgumentException;
176
177    @CacheEvict(value={AgendaTreeDefinition.Cache.NAME, AgendaDefinition.Cache.NAME, AgendaItemDefinition.Cache.NAME, ContextDefinition.Cache.NAME}, allEntries = true)
178    public void deleteAgendaItem(String id) throws RiceIllegalArgumentException;
179
180        /**
181        * Converts a mutable bo to it's immutable counterpart
182        * @param bo the mutable business object
183        * @return the immutable object
184        */
185        public AgendaDefinition to(AgendaBo bo);
186
187   /**
188        * Converts a immutable object to it's mutable bo counterpart
189        * @param im immutable object
190        * @return the mutable bo
191        */
192        public AgendaBo from(AgendaDefinition im);
193}