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.util.List; 019 020 import org.kuali.rice.kim.bo.Person; 021 import org.kuali.rice.kns.document.Document; 022 import org.kuali.rice.kns.exception.ValidationException; 023 import org.kuali.rice.kns.rule.event.KualiDocumentEvent; 024 import org.kuali.rice.kns.util.KualiInteger; 025 import org.kuali.kfs.coa.businessobject.Account; 026 import org.kuali.kfs.coa.businessobject.SubAccount; 027 import org.kuali.kfs.module.bc.BCConstants.MonthSpreadDeleteType; 028 import org.kuali.kfs.module.bc.businessobject.BudgetConstructionAccountOrganizationHierarchy; 029 import org.kuali.kfs.module.bc.businessobject.BudgetConstructionAccountReports; 030 import org.kuali.kfs.module.bc.businessobject.BudgetConstructionHeader; 031 import org.kuali.kfs.module.bc.businessobject.BudgetConstructionMonthly; 032 import org.kuali.kfs.module.bc.businessobject.PendingBudgetConstructionAppointmentFunding; 033 import org.kuali.kfs.module.bc.businessobject.PendingBudgetConstructionGeneralLedger; 034 import org.kuali.kfs.module.bc.businessobject.SalarySettingExpansion; 035 import org.kuali.kfs.module.bc.document.BudgetConstructionDocument; 036 import org.kuali.kfs.module.bc.document.web.struts.MonthlyBudgetForm; 037 038 import org.kuali.rice.kew.exception.WorkflowException; 039 040 041 /** 042 * This defines the methods a BudgetDocumentService must implement 043 */ 044 public interface BudgetDocumentService { 045 046 /** 047 * Gets a BudgetConstructionHeader by the candidate key instead of primary key 048 * 049 * @param chartOfAccountsCode 050 * @param accountNumber 051 * @param subAccountNumber 052 * @param fiscalYear 053 * @return 054 */ 055 public BudgetConstructionHeader getByCandidateKey(String chartOfAccountsCode, String accountNumber, String subAccountNumber, Integer fiscalYear); 056 057 /** 058 * Performs all actions needed to validate and save a Budget Construction document to the database and workflow. 059 * 060 * @param document 061 * @return 062 * @throws WorkflowException 063 * @throws ValidationException 064 */ 065 public Document saveDocument(BudgetConstructionDocument budgetConstructionDocument) throws WorkflowException, ValidationException; 066 067 /** 068 * Performs all actions needed to validate and save a Budget Construction document to the database only. 069 * 070 * @param document 071 * @return 072 * @throws ValidationException 073 */ 074 public Document saveDocumentNoWorkflow(BudgetConstructionDocument budgetConstructionDocument) throws ValidationException; 075 076 /** 077 * Performs all actions needed to validate and save a Budget Construction document to the database only. Whether or not the 078 * monthly RI check is performed during validation is controlled using doMonthRICheck. Passing in false is a case used by the 079 * monthlySpread deletion functionality. No need to perform monthly RI check if the action is to remove all the records 080 * 081 * @param bcDoc 082 * @param doMonthRICheck 083 * @return 084 * @throws ValidationException 085 */ 086 public Document saveDocumentNoWorkFlow(BudgetConstructionDocument bcDoc, MonthSpreadDeleteType monthSpreadDeleteType, boolean doMonthRICheck) throws ValidationException; 087 088 /** 089 * Saves a single BudgetConstructionMonthly row 090 * 091 * @param budgetConstructionMonthly 092 */ 093 public void saveMonthlyBudget(MonthlyBudgetForm monthlyBudgetForm, BudgetConstructionMonthly budgetConstructionMonthly); 094 095 /** 096 * Sets benefits calculation flags in Budget Construction Document associated with the monthly screen 097 * 098 * @param bcDoc 099 * @param budgetConstructionMonthly 100 * @param pbglChangeAmount 101 */ 102 public void callForBenefitsCalcIfNeeded(BudgetConstructionDocument bcDoc, BudgetConstructionMonthly budgetConstructionMonthly, KualiInteger pbglChangeAmount); 103 104 /** 105 * Checks if annual and/or monthly benefits need calculated and calls the associated calculation method 106 * 107 * @param bcDoc 108 */ 109 public void calculateBenefitsIfNeeded(BudgetConstructionDocument bcDoc); 110 111 /** 112 * Explicitly calls both the annual and monthly benefits calculation methods 113 * 114 * @param bcDoc 115 */ 116 public void calculateBenefits(BudgetConstructionDocument bcDoc); 117 118 // /** 119 // * Calculates annual benefits for a budget construction document using the persisted data currently stored in the database. 120 // * 121 // * @param bcDoc 122 // */ 123 // public void calculateAnnualBenefits(BudgetConstructionDocument bcDoc); 124 // 125 // /** 126 // * Calculates the monthly benefits for a budget construction document using the persisted data currently stored in the 127 // database. 128 // * 129 // * @param bcDoc 130 // */ 131 // public void calculateMonthlyBenefits(BudgetConstructionDocument bcDoc); 132 133 /** 134 * Gets the salary detail lines request sum for a budget document expenditure accounting line 135 * 136 * @param salaryDetailLine 137 * @return 138 */ 139 public KualiInteger getPendingBudgetConstructionAppointmentFundingRequestSum(PendingBudgetConstructionGeneralLedger salaryDetailLine); 140 141 public List<BudgetConstructionAccountOrganizationHierarchy> getPushPullLevelList(BudgetConstructionDocument bcDoc, Person u); 142 143 /** 144 * update the pending budget construction GL record assocating with the given appointment funding. If there exists any pbgl 145 * record, a new one will be created and stored 146 * 147 * @param appointmentFunding the given appointment funding 148 * @param updateAmount the amount that can be used to update the amounts of the pending budget construction GL record 149 */ 150 public void updatePendingBudgetGeneralLedger(PendingBudgetConstructionAppointmentFunding appointmentFunding, KualiInteger updateAmount); 151 152 /** 153 * update the pending budget construction GL plug record assocating with the given appointment funding. If there exists any pbgl 154 * plug record, a new one will be created and stored 155 * 156 * @param appointmentFunding the given appointment funding 157 * @param updateAmount the amount that can be used to update the amounts of the pending budget construction GL plug record 158 */ 159 public void updatePendingBudgetGeneralLedgerPlug(PendingBudgetConstructionAppointmentFunding appointmentFunding, KualiInteger updateAmount); 160 161 /** 162 * get the budget document with the information provided by the given appointment funding 163 * 164 * @param appointmentFunding the given appointment funding 165 * @return the budget document with the information provided by the given appointment funding 166 */ 167 public BudgetConstructionHeader getBudgetConstructionHeader(PendingBudgetConstructionAppointmentFunding appointmentFunding); 168 169 /** 170 * get the budget document with the information provided by the given appointment funding 171 * 172 * @param appointmentFunding the given appointment funding 173 * @return the budget document with the information provided by the given appointment funding 174 */ 175 public BudgetConstructionDocument getBudgetConstructionDocument(PendingBudgetConstructionAppointmentFunding appointmentFunding); 176 177 /** 178 * get the budget document with the information provided by the given salary setting expansion 179 * 180 * @param salarySettingExpansion 181 * @return the budget document with the information provided by the given salary setting expansion 182 */ 183 public BudgetConstructionDocument getBudgetConstructionDocument(SalarySettingExpansion salarySettingExpansion); 184 185 /** 186 * determine whether the given document is budgetable 187 * 188 * @param bcHeader the given budget document 189 * @return true if the given document is budgetable; otherwise, false 190 */ 191 public boolean isBudgetableDocument(BudgetConstructionHeader bcHeader); 192 193 /** 194 * determine whether the given document is budgetable skipping the wages allowed check 195 * 196 * @param bcHeader the given budget document 197 * @return true if the given document is budgetable; otherwise, false 198 */ 199 public boolean isBudgetableDocumentNoWagesCheck(BudgetConstructionHeader bcHeader); 200 201 /** 202 * determine whether the given document is budgetable 203 * 204 * @param document the given budget document 205 * @return true if the given document is budgetable; otherwise, false 206 */ 207 public boolean isBudgetableDocument(BudgetConstructionDocument document); 208 209 /** 210 * determine whether the given document is budgetable skipping the wages allowed check 211 * 212 * @param document the given budget document 213 * @return true if the given document is budgetable; otherwise, false 214 */ 215 public boolean isBudgetableDocumentNoWagesCheck(BudgetConstructionDocument document); 216 217 /** 218 * determine whether the given appointment funding is associated with a budgetable document 219 * 220 * @param appointmentFunding the given appointment funding 221 * @return true if the given appointment funding is associated with a budgetable document; otherwise, false 222 */ 223 public boolean isAssociatedWithBudgetableDocument(PendingBudgetConstructionAppointmentFunding appointmentFunding); 224 225 /** 226 * determine whether the given account is budgetable for the specified budget year 227 * 228 * @param budgetYear the specified budget year 229 * @param account the given account 230 * @param isWagesCheck whether or not to include the no wages check 231 * @return true if the given account is budgetable for the specified budget year; otherwise, false 232 */ 233 public boolean isBudgetableAccount(Integer budgetYear, Account account, boolean isWagesCheck); 234 235 /** 236 * determine whether the given subaccount is budgetable 237 * 238 * @param subAccount the given subaccount 239 * @param subAccountNumber the sub account number associated with the given sub account. If sub account is null, the number can 240 * be empty or the default. 241 * @return true if the given subaccount is budgetable; otherwise, false 242 */ 243 public boolean isBudgetableSubAccount(SubAccount subAccount, String subAccountNumber); 244 245 /** 246 * Determine if account reports exists for the key passed in. 247 * 248 * @param chartOfAccountsCode 249 * @param accountNumber 250 * @return 251 */ 252 public boolean isAccountReportsExist(String chartOfAccountsCode, String accountNumber); 253 254 /** 255 * retrieve all pending budget construction GL records associated with the given budget contruction header 256 * 257 * @param budgetConstructionHeader the budget construction header associated with the pending budget construction GL records to 258 * be retrieved 259 * @return all pending budget construction GL records associated with the given budget contruction header 260 */ 261 public List<PendingBudgetConstructionGeneralLedger> retrievePendingBudgetConstructionGeneralLedger(BudgetConstructionHeader budgetConstructionHeader); 262 263 /** 264 * Returns a list of Pending Budget GL rows from the DB for the BudgetConstructionDocument that are associated with Salary 265 * Setting including any 2PLG rows. 266 * 267 * @param bcDocument 268 * @return 269 */ 270 public List<PendingBudgetConstructionGeneralLedger> getPBGLSalarySettingRows(BudgetConstructionDocument bcDocument); 271 272 /** 273 * Adds or Updates a Pending Budget GL row to a BudgetConstruction document with the passed in Pending Budget GL object. Any 274 * inserts are added in the proper order in the list based on object code, sub-object code sort order 275 * 276 * @param bcDoc 277 * @param sourceRow 278 * @return 279 */ 280 public BudgetConstructionDocument addOrUpdatePBGLRow(BudgetConstructionDocument bcDoc, PendingBudgetConstructionGeneralLedger sourceRow); 281 282 /** 283 * Adds or updates the 2PLG row in a BudgetConstructionDocument adding the updateAmount into any existing request amount 284 * 285 * @param bcDoc 286 * @param updateAmount 287 * @return 288 */ 289 public PendingBudgetConstructionGeneralLedger updatePendingBudgetGeneralLedgerPlug(BudgetConstructionDocument bcDoc, KualiInteger updateAmount); 290 291 /** 292 * Performs Budgetconstructiondocument validation as if saving, but does not perform the actual save. This is used to 293 * immediately give feedback to the user when returning from Salary Setting in the event there are Monthly RI issues. 294 * 295 * @param document 296 * @throws ValidationException 297 */ 298 public void validateDocument(Document document) throws ValidationException; 299 300 /** 301 * Populates references for a given Pending Budget GL row. 302 * 303 * @param line 304 */ 305 public void populatePBGLLine(PendingBudgetConstructionGeneralLedger line); 306 307 /** 308 * Retrieves the Account Organization Hierarchy for the primary key passed in. If not found, it attempts to build the hierarchy 309 * and return that. Unsuccessful builds are caused by either overflows (cycles in the reports to structure) or a missing account 310 * reports to mapping. In these cases an empty hierarchy list is returned. 311 * 312 * @param universityFiscalYear 313 * @param chartOfAccountsCode 314 * @param accountNumber 315 * @return 316 */ 317 public List<BudgetConstructionAccountOrganizationHierarchy> retrieveOrBuildAccountOrganizationHierarchy(Integer universityFiscalYear, String chartOfAccountsCode, String accountNumber); 318 319 /** 320 * Persists a brand new (blank) Budget Construction Document and prepares it to accept revenue/expenditure lines. 321 * 322 * @param budgetConstructionDocument 323 * @return 324 * @throws WorkflowException 325 */ 326 public BudgetConstructionDocument instantiateNewBudgetConstructionDocument(BudgetConstructionDocument budgetConstructionDocument) throws WorkflowException; 327 328 329 } 330