001/*
002 * Copyright 2006 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 */
016package org.kuali.ole.fp.document.service;
017
018import java.util.List;
019import java.util.Map;
020
021import org.kuali.ole.fp.businessobject.CashieringItemInProcess;
022import org.kuali.ole.fp.businessobject.Check;
023import org.kuali.ole.fp.businessobject.CoinDetail;
024import org.kuali.ole.fp.businessobject.CurrencyDetail;
025import org.kuali.ole.fp.businessobject.Deposit;
026import org.kuali.ole.fp.document.CashManagementDocument;
027import org.kuali.ole.fp.document.CashReceiptDocument;
028import org.kuali.ole.sys.businessobject.Bank;
029import org.kuali.rice.core.api.util.type.KualiDecimal;
030
031/**
032 * This service interface defines methods that a CashManagementService implementation must provide.
033 * 
034 */
035public interface CashManagementService {
036    /**
037     * Creates and returns a CashManagementDocument, opening the CashDrawer associated with the given verification unit.
038     * 
039     * @param campusCode
040     * @param docDescription
041     * @param annotation
042     * @return A properly initialized CashManagementDocument instance.
043     */
044    public CashManagementDocument createCashManagementDocument(String campusCode, String docDescription, String annotation);
045
046
047    /**
048     * Uses the given information to lock the appropriate CashDrawer, create a Deposit, and associate it with the given
049     * CashManagementDocument and CashReceipts.
050     * 
051     * @param cashManagementDoc
052     * @param depositTicketNumber
053     * @param bank
054     * @param selectedCashReceipts
055     * @param isFinalDeposit
056     */
057    public void addDeposit(CashManagementDocument cashManagementDoc, String depositTicketNumber, Bank bank, List selectedCashReceipts, List selectedCashieringChecks, boolean isFinalDeposit);
058
059
060    /**
061     * Cancels the given Deposit, updating the related CashManagementDocument, CashReceipts, and CashDrawer as needed
062     * 
063     * @param deposit
064     */
065    public void cancelDeposit(Deposit deposit);
066
067    /**
068     * Cancels the given CashManagementDocument, canceling the Deposits it contains and closing the CashDrawer associated with the
069     * given verification unit. Called in response to a workflow CANCEL request, so this method doesn't invoke workflow itself.
070     * 
071     * @param cmDoc
072     */
073    public void cancelCashManagementDocument(CashManagementDocument cmDoc);
074
075
076    /**
077     * Finalizes the given CashManagementDocument, updating the status of the CashReceipt documents in the Deposits it contains and
078     * closing the CashDrawer associated with the given verification unit. Called in response to a workflow document status change,
079     * so this method doesn't invoke workflow itself.
080     * 
081     * @param cmDoc
082     */
083    public void finalizeCashManagementDocument(CashManagementDocument cmDoc);
084
085
086    /**
087     * Retrieves a CashManagementDocument instance associated with the cash receipt id provided.  
088     * 
089     * @param documentId The id of the cash receipt document associated with the cash management document.
090     * @return CashManagementDocument which contains the Deposit which contains the given CashReceipt, or null if the CashReceipt is
091     *         not contained in a Deposit
092     */
093    public CashManagementDocument getCashManagementDocumentForCashReceiptId(String documentId);
094
095
096    /**
097     * Returns a List of all CashReceipts associated with the given Deposit.
098     * 
099     * @param deposit The deposit the cash receipts will be retrieved from.
100     * @return List the of CashReceipts associated with given deposit.
101     */
102    public List retrieveCashReceipts(Deposit deposit);
103    
104    /**
105     * Apply a cashiering transaction to a cash management document.  This means:
106     * 0. check rules???
107     * 1. Updating the cash drawer with any incoming currency and coin
108     * 2. Moving any checks from the transaction to the CM document
109     * 3. Checking if any items in process were closed; if so, saving that info
110     * 4. Saving currency and coin records
111     * 5. Saving any new item in process
112     * 6. saving any checks
113     * 
114     * @param cmDoc The transaction to apply to the cash management document.
115     * @param cashieringTransaction The transaction being applied to the cash management document.
116     */
117    public void applyCashieringTransaction(CashManagementDocument cmDoc);
118    
119    /**
120     * Retrieve the open cashiering items in process for the given cash management document.
121     * 
122     * @param cmDoc The cash management document to retrieve the items in process for.
123     * @return A list of all open items in process.
124     */
125    public List<CashieringItemInProcess> getOpenItemsInProcess(CashManagementDocument cmDoc);
126    
127    /**
128     * Returns all items in process associated with this workgroup, closed within the past 30 days
129     * 
130     * @param cmDoc The cash management document which is associated with the workgroup that the closed items in process would have also been associated with.
131     * @return A list of any items in process recently closed.
132     */
133    public List<CashieringItemInProcess> getRecentlyClosedItemsInProcess(CashManagementDocument cmDoc);
134    
135    /**
136     * Generates the master currency detail, which sounds bad, but which is really just okay.
137     * A master currency detail is the composite effect of all the transactions of a cash
138     * management document on a cash drawer.
139     * 
140     * @param cmDoc The cash management document to generate the master record for.
141     * @return The master currency detail record.  "Master" in the sense of "Platonic ideal" from which
142     * all else is a copy.
143     */
144    public CurrencyDetail generateMasterCurrencyDetail(CashManagementDocument cmDoc);
145    
146    /**
147     * This generates the "master" coin detail record - a composite of all the coin detail activity that occurred to the cash drawer.
148     * 
149     * @param cmDoc The cash management document to generate the master record for.
150     * @return The master coin detail record.  "Master" in the sense of "Platonic ideal" from which
151     * all else is a copy.
152     */
153    public CoinDetail generateMasterCoinDetail(CashManagementDocument cmDoc);
154    
155    /**
156     * Verifies if a given cash receipt is deposited as part of the given cash management document.
157     * 
158     * @param cmDoc The cash management document to search through.
159     * @param crDoc The cash receipt to check  the deposited status of.
160     * @return true If the given cash receipt document is deposited as part of the given cash management document, false if otherwise.
161     */
162    public boolean verifyCashReceiptIsDeposited(CashManagementDocument cmDoc, CashReceiptDocument crDoc);
163    
164    /**
165     * This method verifies that all cash receipts for the document are deposited.
166     * 
167     * @param cmDoc The cash management document to verify.
168     * @return True if all CRs are deposited, false if otherwise.
169     */
170    public boolean allVerifiedCashReceiptsAreDeposited(CashManagementDocument cmDoc);
171    
172    /**
173     * This method turns the last interim deposit into the final deposit and locks the cash drawer.
174     * 
175     * @param cmDoc The cash management document to take deposits from for finalization.
176     */
177    public void finalizeLastInterimDeposit(CashManagementDocument cmDoc);
178    
179    /**
180     * This method creates new cumulative currency and coin details for a document.
181     * 
182     * @param cmDoc The cash management document the cumulative details will be associated with.
183     * @param cashieringSource The cashiering record source for the new details.
184     */
185    public void createNewCashDetails(CashManagementDocument cmDoc, String cashieringSource);
186    
187    /**
188     * Grab the currency and coin detail for final deposits.
189     * 
190     * @param cmDoc The cash management document which has deposits to populate.
191     */
192    public void populateCashDetailsForDeposit(CashManagementDocument cmDoc);
193    
194    /**
195     * Retrieves from the database any undeposited cashiering transaction checks associated with the given cash management document.
196     * 
197     * @param documentNumber The document number of a cash management document that cashiering transaction checks may be associated with.
198     * @return A list of checks associated with the document number given.
199     */
200    public List<Check> selectUndepositedCashieringChecks(String documentNumber);
201    
202    /**
203     * Retrieves from the database all deposited cashiering transaction checks associated with the given cash management document number.
204     * 
205     * @param documentNumber The document number of a cash management document that cashiering transaction checks may be associated with.
206     * @return A list of deposited cashiering checks associated with the document number given.
207     */
208    public List<Check> selectDepositedCashieringChecks(String documentNumber);
209    
210    /**
211     * Retrieves from the database all cashiering transaction checks deposited for a given deposit.
212     * 
213     * @param documentNumber The document number of a cash management document that cashiering transaction checks have been deposited for.
214     * @param depositLineNumber The line number of the deposit to find checks deposited for.
215     * @return A list of checks associated with the given deposit.
216     */
217    public List<Check> selectCashieringChecksForDeposit(String documentNumber, Integer depositLineNumber);
218    
219    /**
220     * Total up the amounts of all checks so far deposited as part of the given cash management document.
221     * 
222     * @param documentNumber The id of a cash management document.
223     * @return The total of cashiering checks deposited so far as part of that document.
224     */
225    public KualiDecimal calculateDepositedCheckTotal(String documentNumber);
226    
227    /**
228     * Total up the amounts of all cashiering checks not yet deposited as part of the given cash management document.
229     * 
230     * @param documentNumber The id of a cash management document.
231     * @return The total of cashiering checks not yet deposited as part of that document.
232     */
233    public KualiDecimal calculateUndepositedCheckTotal(String documentNumber);
234    
235    /**
236     * This method determines whether or not the given cash management document can be canceled.
237     * 
238     * @param cmDoc The cash management document to be canceled.
239     * @return True if cancellation is possible, false if otherwise.
240     */
241    public boolean allowDocumentCancellation(CashManagementDocument cmDoc);
242    
243    /**
244     * Select the next available check line number for the given cash management document.
245     * 
246     * @param documentNumber The document number of a cash management document.
247     * @return The next available check line number for cashiering checks.
248     */
249    public Integer selectNextAvailableCheckLineNumber(String documentNumber);
250    
251    /**
252     * This returns the currency and coin details for the final deposit, in a map keyed on the detail class
253     * 
254     * This returns the currency and coin details for the final deposit, in a map keyed on the detail class.
255     * 
256     * @param documentNumber The document number to find the final deposit cash details for.
257     * @return A map with the cash details in it.
258     */
259    public Map<Class, Object> getCashDetailsForFinalDeposit(String documentNumber);
260}