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.sys.service;
017    
018    import java.util.Collection;
019    import java.util.Iterator;
020    import java.util.List;
021    import java.util.Map;
022    
023    import org.kuali.kfs.coa.businessobject.Account;
024    import org.kuali.kfs.coa.businessobject.ObjectCode;
025    import org.kuali.kfs.gl.businessobject.Balance;
026    import org.kuali.kfs.gl.businessobject.Encumbrance;
027    import org.kuali.kfs.sys.businessobject.Bank;
028    import org.kuali.kfs.sys.businessobject.GeneralLedgerPendingEntry;
029    import org.kuali.kfs.sys.businessobject.GeneralLedgerPendingEntrySequenceHelper;
030    import org.kuali.kfs.sys.businessobject.GeneralLedgerPendingEntrySourceDetail;
031    import org.kuali.kfs.sys.document.AccountingDocument;
032    import org.kuali.kfs.sys.document.GeneralLedgerPendingEntrySource;
033    import org.kuali.kfs.sys.document.GeneralLedgerPostingDocument;
034    import org.kuali.rice.kns.util.KualiDecimal;
035    
036    /**
037     * This interface defines methods that a GeneralLedgerPendingEntry Service must provide
038     */
039    public interface GeneralLedgerPendingEntryService {
040    
041        /**
042         * This method...
043         * 
044         * @param universityFiscalYears
045         * @param chartOfAccountsCode
046         * @param accountNumber
047         * @param isDebit
048         * @return
049         */
050        public KualiDecimal getCashSummary(List universityFiscalYears, String chartOfAccountsCode, String accountNumber, boolean isDebit);
051    
052        /**
053         * This method...
054         * 
055         * @param universityFiscalYears
056         * @param chartOfAccountsCode
057         * @param accountNumber
058         * @param isDebit
059         * @return
060         */
061        public KualiDecimal getActualSummary(List universityFiscalYears, String chartOfAccountsCode, String accountNumber, boolean isDebit);
062    
063        /**
064         * This method...
065         * 
066         * @param universityFiscalYear
067         * @param chartOfAccountsCode
068         * @param accountNumber
069         * @param sufficientFundsObjectCode
070         * @param isDebit
071         * @param isYearEnd
072         * @return
073         */
074        public KualiDecimal getExpenseSummary(Integer universityFiscalYear, String chartOfAccountsCode, String accountNumber, String sufficientFundsObjectCode, boolean isDebit, boolean isYearEnd);
075    
076        /**
077         * This method...
078         * 
079         * @param universityFiscalYear
080         * @param chartOfAccountsCode
081         * @param accountNumber
082         * @param sufficientFundsObjectCode
083         * @param isDebit
084         * @param isYearEnd
085         * @return
086         */
087        public KualiDecimal getEncumbranceSummary(Integer universityFiscalYear, String chartOfAccountsCode, String accountNumber, String sufficientFundsObjectCode, boolean isDebit, boolean isYearEnd);
088    
089        /**
090         * This method...
091         * 
092         * @param universityFiscalYear
093         * @param chartOfAccountsCode
094         * @param accountNumber
095         * @param sufficientFundsObjectCode
096         * @param isYearEnd
097         * @return
098         */
099        public KualiDecimal getBudgetSummary(Integer universityFiscalYear, String chartOfAccountsCode, String accountNumber, String sufficientFundsObjectCode, boolean isYearEnd);
100    
101        /**
102         * @param transactionEntrySequenceId
103         * @param documentHeaderId
104         */
105        public GeneralLedgerPendingEntry getByPrimaryId(Integer transactionEntrySequenceId, String documentHeaderId);
106    
107        /**
108         * Invokes generateGeneralLedgerPendingEntries method on the transactional document.
109         * 
110         * @param document - document whose pending entries need generated
111         * @return whether the business rules succeeded
112         */
113        public boolean generateGeneralLedgerPendingEntries(GeneralLedgerPendingEntrySource document);
114    
115        /**
116         * The fiscal year and period is null in quite a few glpe's. This will put in a sensible default.
117         * 
118         * @param glpe
119         */
120        public void fillInFiscalPeriodYear(GeneralLedgerPendingEntry glpe);
121    
122        /**
123         * @param generalLedgerPendingEntry
124         */
125        public void save(GeneralLedgerPendingEntry generalLedgerPendingEntry);
126    
127        /**
128         * @param documentHeaderId
129         */
130        public void delete(String documentHeaderId);
131    
132        /**
133         * Delete all pending entries for a specific document approved code
134         * 
135         * @param financialDocumentApprovedCode
136         */
137        public void deleteByFinancialDocumentApprovedCode(String financialDocumentApprovedCode);
138    
139        /**
140         * Does the given account have any general ledger entries? It is necessary to check this before closing an account.
141         * 
142         * @param account
143         * @return
144         */
145        public boolean hasPendingGeneralLedgerEntry(Account account);
146    
147        /**
148         * The method finds all pending ledger entries
149         * 
150         * @return all pending ledger entries
151         */
152        public Iterator findApprovedPendingLedgerEntries();
153    
154        /**
155         * This method retrieves all pending ledger entries for the given encumbrance
156         * 
157         * @param encumbrance the encumbrance entry
158         * @param isApproved the flag that indicates whether the pending entries are approved or don't care
159         * @return all pending ledger entries of the given encumbrance
160         */
161        public Iterator findPendingLedgerEntries(Encumbrance encumbrance, boolean isApproved);
162    
163        /**
164         * This method retrieves all pending ledger entries for the given encumbrance
165         * 
166         * @param balance the balance entry
167         * @param isApproved the flag that indicates whether the pending entries are approved or don't care
168         * @param isConsolidated determine whether the search results are consolidated
169         * @return all pending ledger entries of the given encumbrance
170         */
171        public Iterator findPendingLedgerEntries(Balance balance, boolean isApproved, boolean isConsolidated);
172    
173        /**
174         * This method retrieves all pending ledger entries matching the given entry criteria
175         * 
176         * @param isApproved the flag that indicates whether the pending entries are approved or don't care
177         * @param fieldValues the input fields and values
178         * @return all pending ledger entries matching the given balance criteria
179         */
180        public Iterator findPendingLedgerEntriesForEntry(Map fieldValues, boolean isApproved);
181    
182        /**
183         * This method retrieves all pending ledger entries matching the given balance criteria
184         * 
185         * @param isApproved the flag that indicates whether the pending entries are approved or don't care
186         * @param fieldValues the input fields and values
187         * @return all pending ledger entries matching the given balance criteria
188         */
189        public Iterator findPendingLedgerEntriesForBalance(Map fieldValues, boolean isApproved);
190    
191        /**
192         * This method retrieves all pending ledger entries that may belong to cash balance in the future
193         * 
194         * @param isApproved the flag that indicates whether the pending entries are approved or don't care
195         * @return all pending ledger entries that may belong to cash balance
196         */
197        public Iterator findPendingLedgerEntriesForCashBalance(Map fieldValues, boolean isApproved);
198    
199        /**
200         * This method retrieves all pending ledger entries that may belong to encumbrance table in the future
201         * 
202         * @param isApproved the flag that indicates whether the pending entries are approved or don't care
203         * @return all pending ledger entries that may belong to encumbrance table
204         */
205        public Iterator findPendingLedgerEntriesForEncumbrance(Map fieldValues, boolean isApproved);
206    
207        /**
208         * This method retrieves all pending ledger entries that may belong to the given account balance record in the future
209         * 
210         * @param fieldValues
211         * @param isApproved the flag that indicates whether the pending entries are approved or don't care
212         * @return all pending ledger entries that may belong to encumbrance table
213         */
214        public Iterator findPendingLedgerEntrySummaryForAccountBalance(Map fieldValues, boolean isApproved);
215    
216        /**
217         * This method retrieves all pending ledger entries that may belong to the given account balance record in the future
218         * 
219         * @param fieldValues
220         * @param isApproved the flag that indicates whether the pending entries are approved or don't care
221         * @return all pending ledger entries that may belong to encumbrance table
222         */
223        public Iterator findPendingLedgerEntriesForAccountBalance(Map fieldValues, boolean isApproved);
224    
225        /**
226         * @param fieldValues
227         * @return
228         */
229        public Collection findPendingEntries(Map fieldValues, boolean isApproved);
230        
231        /**
232         * This populates an empty GeneralLedgerPendingEntry explicitEntry object instance with default values.
233         * 
234         * @param accountingDocument
235         * @param accountingLine
236         * @param sequenceHelper
237         * @param explicitEntry
238         */
239        public void populateExplicitGeneralLedgerPendingEntry(GeneralLedgerPendingEntrySource poster, GeneralLedgerPendingEntrySourceDetail postable, GeneralLedgerPendingEntrySequenceHelper sequenceHelper, GeneralLedgerPendingEntry explicitEntry);
240        
241        /**
242         * Convenience method to build a GLPE without a generalLedgerPendingEntrySourceDetail
243         * @param document a GeneralLedgerPostingDocument
244         * @param account the account for use in the GLPE
245         * @param objectCode the object code for use in the GLPE
246         * @param subAccountNumber the sub account number for use in the GLPE
247         * @param subObjectCode the subobject code for use in the GLPE
248         * @param organizationReferenceId the organization reference id to use in the GLPE
249         * @param projectCode the project code to use in the GLPE
250         * @param referenceNumber the reference number to use in the GLPE
251         * @param referenceTypeCode the reference type code to use in the GLPE
252         * @param referenceOriginCode the reference origin code to use in the GLPE
253         * @param description the description to put in the GLPE
254         * @param isDebit true if the GLPE represents a debit, false if it represents a credit
255         * @param amount the amount of the GLPE
256         * @param sequenceHelper the sequence helper to use
257         * @return a populated general ledger pending entry
258         */
259        public GeneralLedgerPendingEntry buildGeneralLedgerPendingEntry(GeneralLedgerPostingDocument document, Account account, ObjectCode objectCode, String subAccountNumber, String subObjectCode, String organizationReferenceId, String projectCode, String referenceNumber, String referenceTypeCode, String referenceOriginCode, String description, boolean isDebit, KualiDecimal amount, GeneralLedgerPendingEntrySequenceHelper sequenceHelper);
260        
261        /**
262         * This populates an GeneralLedgerPendingEntry offsetEntry object instance with values that differ from the values supplied in
263         * the explicit entry that it was cloned from. Note that the entries do not contain BOs now.
264         * 
265         * @param universityFiscalYear
266         * @param explicitEntry
267         * @param sequenceHelper
268         * @param offsetEntry Cloned from the explicit entry
269         */
270        public boolean populateOffsetGeneralLedgerPendingEntry(Integer universityFiscalYear, GeneralLedgerPendingEntry explicitEntry, GeneralLedgerPendingEntrySequenceHelper sequenceHelper, GeneralLedgerPendingEntry offsetEntry);
271        
272        /**
273         * This populates an empty GeneralLedgerPendingEntry instance with default values for a bank offset. A global error will be
274         * posted as a side-effect if the given Bank has not defined the necessary bank offset relations.
275         * 
276         * @param bank
277         * @param depositAmount
278         * @param financialDocument
279         * @param universityFiscalYear
280         * @param sequenceHelper
281         * @param bankOffsetEntry
282         * @param errorPropertyName
283         */
284        public boolean populateBankOffsetGeneralLedgerPendingEntry(Bank bank, KualiDecimal depositAmount, GeneralLedgerPostingDocument financialDocument, Integer universityFiscalYear, GeneralLedgerPendingEntrySequenceHelper sequenceHelper, GeneralLedgerPendingEntry bankOffsetEntry, String errorPropertyName);
285    
286        /**
287         * Adds up the amounts of all cash to offset GeneralLedgerPendingEntry records on the given AccountingDocument
288         * @param glPostingDocument the accounting document total the offset to cash amount for
289         * @return the offset to cash amount, where debited values have been subtracted and credited values have been added
290         */
291        public abstract KualiDecimal getOffsetToCashAmount(GeneralLedgerPostingDocument glPostingDocument);
292        
293        /**
294         * Determines if the given GeneralLedgerPendingEntry represents offsets to cash
295         * @param generalLedgerPendingEntry the GeneralLedgerPendingEntry to check
296         * @return true if the GeneralLedgerPendingEntry represents an offset to cash; false otherwise
297         */
298        public abstract boolean isOffsetToCash(GeneralLedgerPendingEntry generalLedgerPendingEntry);
299    }