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.fp.document.service;
017
018 import java.util.List;
019 import java.util.Map;
020
021 import org.kuali.kfs.fp.businessobject.CashieringItemInProcess;
022 import org.kuali.kfs.fp.businessobject.Check;
023 import org.kuali.kfs.fp.businessobject.CoinDetail;
024 import org.kuali.kfs.fp.businessobject.CurrencyDetail;
025 import org.kuali.kfs.fp.businessobject.Deposit;
026 import org.kuali.kfs.fp.document.CashManagementDocument;
027 import org.kuali.kfs.fp.document.CashReceiptDocument;
028 import org.kuali.kfs.sys.businessobject.Bank;
029 import org.kuali.rice.kns.util.KualiDecimal;
030
031 /**
032 * This service interface defines methods that a CashManagementService implementation must provide.
033 *
034 */
035 public 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 }