1 /*
2 * Copyright 2006 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.ole.fp.document.service;
17
18 import java.util.List;
19 import java.util.Map;
20
21 import org.kuali.ole.fp.businessobject.CashieringItemInProcess;
22 import org.kuali.ole.fp.businessobject.Check;
23 import org.kuali.ole.fp.businessobject.CoinDetail;
24 import org.kuali.ole.fp.businessobject.CurrencyDetail;
25 import org.kuali.ole.fp.businessobject.Deposit;
26 import org.kuali.ole.fp.document.CashManagementDocument;
27 import org.kuali.ole.fp.document.CashReceiptDocument;
28 import org.kuali.ole.sys.businessobject.Bank;
29 import org.kuali.rice.core.api.util.type.KualiDecimal;
30
31 /**
32 * This service interface defines methods that a CashManagementService implementation must provide.
33 *
34 */
35 public interface CashManagementService {
36 /**
37 * Creates and returns a CashManagementDocument, opening the CashDrawer associated with the given verification unit.
38 *
39 * @param campusCode
40 * @param docDescription
41 * @param annotation
42 * @return A properly initialized CashManagementDocument instance.
43 */
44 public CashManagementDocument createCashManagementDocument(String campusCode, String docDescription, String annotation);
45
46
47 /**
48 * Uses the given information to lock the appropriate CashDrawer, create a Deposit, and associate it with the given
49 * CashManagementDocument and CashReceipts.
50 *
51 * @param cashManagementDoc
52 * @param depositTicketNumber
53 * @param bank
54 * @param selectedCashReceipts
55 * @param isFinalDeposit
56 */
57 public void addDeposit(CashManagementDocument cashManagementDoc, String depositTicketNumber, Bank bank, List selectedCashReceipts, List selectedCashieringChecks, boolean isFinalDeposit);
58
59
60 /**
61 * Cancels the given Deposit, updating the related CashManagementDocument, CashReceipts, and CashDrawer as needed
62 *
63 * @param deposit
64 */
65 public void cancelDeposit(Deposit deposit);
66
67 /**
68 * Cancels the given CashManagementDocument, canceling the Deposits it contains and closing the CashDrawer associated with the
69 * given verification unit. Called in response to a workflow CANCEL request, so this method doesn't invoke workflow itself.
70 *
71 * @param cmDoc
72 */
73 public void cancelCashManagementDocument(CashManagementDocument cmDoc);
74
75
76 /**
77 * Finalizes the given CashManagementDocument, updating the status of the CashReceipt documents in the Deposits it contains and
78 * closing the CashDrawer associated with the given verification unit. Called in response to a workflow document status change,
79 * so this method doesn't invoke workflow itself.
80 *
81 * @param cmDoc
82 */
83 public void finalizeCashManagementDocument(CashManagementDocument cmDoc);
84
85
86 /**
87 * Retrieves a CashManagementDocument instance associated with the cash receipt id provided.
88 *
89 * @param documentId The id of the cash receipt document associated with the cash management document.
90 * @return CashManagementDocument which contains the Deposit which contains the given CashReceipt, or null if the CashReceipt is
91 * not contained in a Deposit
92 */
93 public CashManagementDocument getCashManagementDocumentForCashReceiptId(String documentId);
94
95
96 /**
97 * Returns a List of all CashReceipts associated with the given Deposit.
98 *
99 * @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 }