001    /*
002     * Copyright 2011 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.kfs.module.bc.document.service;
017    
018    import java.math.BigDecimal;
019    import java.util.List;
020    import java.util.Map;
021    
022    import org.kuali.kfs.module.bc.businessobject.BudgetConstructionAppointmentFundingReasonCode;
023    import org.kuali.kfs.module.bc.businessobject.PendingBudgetConstructionAppointmentFunding;
024    import org.kuali.kfs.module.bc.businessobject.PendingBudgetConstructionGeneralLedger;
025    import org.kuali.kfs.module.bc.businessobject.SalarySettingExpansion;
026    import org.kuali.kfs.module.bc.util.SalarySettingFieldsHolder;
027    import org.kuali.rice.kim.bo.Person;
028    import org.kuali.rice.kns.util.KualiInteger;
029    
030    /**
031     * This class defines methods a Salary Setting Service must provide The Salary Setting Service supports functionality associated
032     * with detailed salary setting for an account as well as organization based salary setting by incumbent and by position.
033     */
034    public interface SalarySettingService {
035    
036        /**
037         * This method returns the disabled setting of the System Parameter controlling Budget module Salary Setting. Disabling Salary
038         * Setting will cause any UI controls related to the salary setting functionality to not be displayed. Disabling will also cause
039         * associated business rules checks to behave differently or not be run.
040         * 
041         * @return
042         */
043        public boolean isSalarySettingDisabled();
044    
045        /**
046         * determine whehter the given pending budget construction general ledger is paid at a biweekly or hourly rate
047         * 
048         * @param pendingBudgetConstructionGeneralLedger the given pending budget construction general ledger
049         * @return true if the given given pending budget construction general ledger is paid at a biweekly or hourly rate; otherwise,
050         *         false
051         */
052        public boolean isHourlyPaid(PendingBudgetConstructionGeneralLedger pendingBudgetConstructionGeneralLedger);
053    
054        /**
055         * determine whehter the given appointment funding is paid at a biweekly or hourly rate
056         * 
057         * @param appointmentFunding the given appointment funding
058         * @return true if the given appointment funding is paid at a biweekly or hourly rate; otherwise, false
059         */
060        public boolean isHourlyPaid(PendingBudgetConstructionAppointmentFunding appointmentFunding);
061    
062        /**
063         * determine whehter the given object code is of a biweekly or hourly pay type
064         * 
065         * @param fiscalYear the given fiscal year
066         * @param chartOfAccountsCode the given chart of accounts code
067         * @param objectCode the given object code
068         * @return true if the given object code is of a biweekly or hourly pay type; otherwise, false
069         */
070        public boolean isHourlyPaidObject(Integer fiscalYear, String chartOfAccountsCode, String objectCode);
071    
072        /**
073         * calculate the hourly pay rate from the request amount in the given appointment funding
074         * 
075         * @param appointmentFunding the given apporintment funding
076         * @return the hourly pay rate
077         */
078        public BigDecimal calculateHourlyPayRate(PendingBudgetConstructionAppointmentFunding appointmentFunding);
079    
080        /**
081         * calculate the annual pay amount from the request pay rate in the given appointment funding
082         * 
083         * @param appointmentFunding the given apporintment funding
084         * @return the annual pay amount
085         */
086        public KualiInteger calculateAnnualPayAmount(PendingBudgetConstructionAppointmentFunding appointmentFunding);
087    
088        /**
089         * normalize the hourly pay rate and annual pay amount of the given appointment funding
090         * 
091         * @param appointmentFunding the given appointment funding
092         */
093        public void normalizePayRateAndAmount(PendingBudgetConstructionAppointmentFunding appointmentFunding);
094    
095        /**
096         * calculate the fte quantity based on the information of the given appointment funding
097         * 
098         * @param appointmentFunding the given appointment funding
099         * @return the fte quantity calculated from the information of the given appointment funding
100         */
101        public BigDecimal calculateFteQuantityFromAppointmentFunding(PendingBudgetConstructionAppointmentFunding appointmentFunding);
102    
103        /**
104         * calculate the FTE quantity through the given information
105         * 
106         * @param payMonth the given number of pay months
107         * @param fundingMonth the given number of funding months
108         * @param requestedTimePercent the requested FTE time percent
109         * @return the FTE quantity calculated from the given information
110         */
111        public BigDecimal calculateFteQuantity(Integer payMonth, Integer fundingMonth, BigDecimal requestedTimePercent);
112    
113        /**
114         * calculate the CSF fte quantity based on the information of the given appointment funding
115         * 
116         * @param appointmentFunding
117         * @return the CSF fte quantity calculated from the information of the given appointment funding
118         */
119        public BigDecimal calculateCSFFteQuantityFromAppointmentFunding(PendingBudgetConstructionAppointmentFunding appointmentFunding);
120    
121        /**
122         * calculate the CSF FTE quantity through the given information
123         * 
124         * @param payMonth the given number of pay months
125         * @param normalWorkMonth the given number of normal work months
126         * @param requestedCSFTimePercent the requested CSF time percent
127         * @return the CSF FTE quantity from the given information
128         */
129        public BigDecimal calculateCSFFteQuantity(Integer payMonth, Integer normalWorkMonth, BigDecimal requestedCSFTimePercent);
130    
131        /**
132         * determine whether the given appointment funding can be vacated
133         * 
134         * @param appointmentFunding the given appointment funding
135         * @return true if the given appointment funding can be vacated; otherwise, false
136         */
137        public boolean canBeVacant(PendingBudgetConstructionAppointmentFunding appointmentFunding);
138    
139        /**
140         * determine whehter the given appointment funding can be vacated
141         * 
142         * @param appointmentFundings the given appointment funding collection that the given appointment funding belongs to
143         * @param appointmentFunding the given appointment funding
144         * @return true if the given appointment funding can be vacated; otherwise, false
145         */
146        public boolean canBeVacant(List<PendingBudgetConstructionAppointmentFunding> appointmentFundings, PendingBudgetConstructionAppointmentFunding appointmentFunding);
147    
148        /**
149         * vacate the given appointment funding and create a vacant appointment funding based on the given funding
150         * 
151         * @param appointmentFunding the given apporintment funding
152         * @return a vacant appointment funding
153         */
154        public PendingBudgetConstructionAppointmentFunding vacateAppointmentFunding(PendingBudgetConstructionAppointmentFunding appointmentFunding);
155    
156        /**
157         * vacate the given appointment funding, create a vacant appointment funding based on the given funding, and add the vacant line
158         * into the given appointment funding collection
159         * 
160         * @param appointmentFundings the given appointment funding collection that the given appointment funding belongs to
161         * @param appointmentFunding the given apporintment funding
162         * @return a vacant appointment funding
163         */
164        public PendingBudgetConstructionAppointmentFunding vacateAppointmentFunding(List<PendingBudgetConstructionAppointmentFunding> appointmentFundings, PendingBudgetConstructionAppointmentFunding appointmentFunding);
165    
166        /**
167         * permanently delete the given appointment funding lines being purged
168         * 
169         * @param purgedAppointmentFundings the given appointment funding collection being purged
170         */
171        public void purgeAppointmentFundings(List<PendingBudgetConstructionAppointmentFunding> purgedAppointmentFundings);
172    
173        /**
174         * find the appointment funding from the given appointment funding collection, which has the same key information as the
175         * specified vacant appointment funding
176         * 
177         * @param appointmentFundings the given appointment funding collection
178         * @param vacantAppointmentFunding the given vacant apporintment funding
179         * @return the appointment funding from the given appointment funding collection, which has the same key information as the
180         *         specified vacant appointment funding
181         */
182        public PendingBudgetConstructionAppointmentFunding findVacantAppointmentFunding(List<PendingBudgetConstructionAppointmentFunding> appointmentFundings, PendingBudgetConstructionAppointmentFunding vacantAppointmentFunding);
183    
184        /**
185         * find the appointment funding from the given appointment funding collection, which has the same key information as the
186         * specified appointment funding
187         * 
188         * @param appointmentFundings the given appointment funding collection
189         * @param vacantAppointmentFunding the given apporintment funding
190         * @return the appointment funding from the given appointment funding collection, which has the same key information as the
191         *         specified appointment funding
192         */
193        public PendingBudgetConstructionAppointmentFunding findAppointmentFunding(List<PendingBudgetConstructionAppointmentFunding> appointmentFundings, PendingBudgetConstructionAppointmentFunding appointmentFunding);
194    
195        /**
196         * adjust the requested salary amount of the given appointment funding by amount
197         * 
198         * @param appointmentFunding the given appointment funding
199         */
200        public void adjustRequestedSalaryByAmount(PendingBudgetConstructionAppointmentFunding appointmentFunding);
201    
202        /**
203         * adjust the requested salary amount of the given appointment funding by percent
204         * 
205         * @param appointmentFunding the given appointment funding
206         */
207        public void adjustRequestedSalaryByPercent(PendingBudgetConstructionAppointmentFunding appointmentFunding);
208    
209        /**
210         * save the salary setting and its associated appointment funding
211         * 
212         * @param salarySettingExpansion the given salary setting expansion, a pending budget construction GL object
213         */
214        public void saveSalarySetting(SalarySettingExpansion salarySettingExpansion);
215    
216        /**
217         * save the pending budget general ledger rows associated with a given salary setting expansion
218         * this also handles updating the special 2PLG row
219         * 
220         * @param salarySettingExpansion
221         */
222        public void savePBGLSalarySetting(SalarySettingExpansion salarySettingExpansion);
223    
224        /**
225         * save the given appointment fundings and associated salary setting expansion,
226         * also known as, pending budget general ledger row
227         * 
228         * @param appointmentFundings
229         * @param isSalarySettingByIncumbent
230         */
231        public void saveSalarySetting(List<PendingBudgetConstructionAppointmentFunding> appointmentFundings, Boolean isSalarySettingByIncumbent);
232    
233        /**
234         * save the given appointment fundings
235         * 
236         * @param appointmentFundings the given appointment funding collection
237         */
238        public void saveAppointmentFundings(List<PendingBudgetConstructionAppointmentFunding> appointmentFundings);
239    
240        /**
241         * reset the given appointment funcding as deleted
242         * 
243         * @param appointmentFunding the given appointment funcding
244         */
245        public void resetAppointmentFunding(PendingBudgetConstructionAppointmentFunding appointmentFunding);
246    
247        /**
248         * mark the given appointment funding as deleted
249         * 
250         * @param appointmentFunding the given appointment funding
251         */
252        public void markAsDelete(PendingBudgetConstructionAppointmentFunding appointmentFunding);
253    
254        /**
255         * revert the given appointment funding if it is just vacated
256         * 
257         * @param appointmentFundings the given appointment funding collection
258         * @param appointmentFunding the given appointment funding
259         */
260        public void revert(List<PendingBudgetConstructionAppointmentFunding> appointmentFundings, PendingBudgetConstructionAppointmentFunding appointmentFunding);
261    
262        /**
263         * retrive the salary setting expension from the information provided by the given appointment funding
264         * 
265         * @param appointmentFunding the given appointment funding
266         * @return the salary setting expension with the information provided by the given appointment funding
267         */
268        public SalarySettingExpansion retriveSalarySalarySettingExpansion(PendingBudgetConstructionAppointmentFunding appointmentFunding);
269    
270        /**
271         * retrieve a list of PendingBudgetConstructionAppointmentFunding from the information provided by
272         * the given SalarySettingExpansion
273         * 
274         * @param salarySettingExpansion
275         * @return the list of PendingBudgetConstructionAppointmentFunding
276         */
277        public List<PendingBudgetConstructionAppointmentFunding> retrievePendingBudgetConstructionAppointmentFundings(SalarySettingExpansion salarySettingExpansion);
278        
279        /**
280         * update the access flags of the given appointment funding according to the given information
281         * 
282         * @param appointmentFunding the given appointment funding
283         * @param salarySettingFieldsHolder the field holder that contains the values passed from the user
284         * @param budgetByObjectMode the budget by object mode flag
285         * @param hasDocumentEditAccess indicates whether the user has edit permission for the budget document (for budget by object)
286         * @param person the specified user
287         * @return true if the access flags are updated successfully; otherwise, false
288         */
289        public boolean updateAccessOfAppointmentFunding(PendingBudgetConstructionAppointmentFunding appointmentFunding, SalarySettingFieldsHolder salarySettingFieldsHolder, boolean budgetByObjectMode, boolean hasDocumentEditAccess, Person person);
290    
291        /**
292         * update the access flags of the given appointment funding according to the user level and document organization level
293         * 
294         * @param appointmentFunding the given appointment funding
295         * @param person the specified user
296         * @return true if the access flags are updated successfully; otherwsie, false
297         */
298        public boolean updateAccessOfAppointmentFundingByUserLevel(PendingBudgetConstructionAppointmentFunding appointmentFunding, Person person);
299    
300        /**
301         * update the fields before saving the given appointment fundings
302         * 
303         * @param appointmentFundings the given collection of appointment fundings
304         */
305        public void updateAppointmentFundingsBeforeSaving(List<PendingBudgetConstructionAppointmentFunding> appointmentFundings);
306    
307        /**
308         * update the fields with the values that can be derived from the existing information, for example, hourly rate and FTE
309         * 
310         * @param appointmentFundings the given appointment funding
311         */
312        public void recalculateDerivedInformation(PendingBudgetConstructionAppointmentFunding appointmentFunding);
313    
314        /**
315         * checks if a reason code has existing appointment funding reasons
316         * 
317         * @param budgetConstructionAppointmentFundingReasonCode
318         * @return
319         */
320        public boolean hasExistingFundingReason(BudgetConstructionAppointmentFundingReasonCode budgetConstructionAppointmentFundingReasonCode);
321    }