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