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