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 }