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 }