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    
020    import org.kuali.kfs.fp.document.CashReceiptDocument;
021    import org.kuali.rice.kim.bo.Person;
022    
023    /**
024     * 
025     * This service interface defines the methods that a CashReceiptService implementation must provide.
026     */
027    public interface CashReceiptService {
028        /**
029         * This method retrieves the cash receipt verification unit for the given user.
030         * 
031         * TODO: change this to do something other than return null (which will require updating CashReceiptDocumentAuthorizer, since
032         * that's the one place I'm sure that returning a null is interpreted to mean that a user is a member of no verificationUnit)
033         * 
034         * @param user The user to retrieve the cash receipt verification unit for.
035         * @return Cash receipt verificationUnit campusCode associated with the given user; null if the user is not a member of any verification campus.
036         */
037        public String getCashReceiptVerificationUnitForUser(Person user);
038    
039        /**
040         * Returns a List of CashReceiptDocuments for the given verification unit whose status matches the given status code.
041         * 
042         * @param verificationUnit A verification unit for a cash receipt.
043         * @param statusCode A cash receipt status code.
044         * @return List of CashReceiptDocument instances.
045         * @throws IllegalArgumentException Thrown if verificationUnit is blank
046         * @throws IllegalArgumentException Thrown if statusCode is blank
047         */
048        public List getCashReceipts(String verificationUnit, String statusCode);
049    
050        /**
051         * Returns a List of CashReceiptDocuments for the given verificationUnit whose status matches any of the status codes in the
052         * given String[].
053         * 
054         * @param verificationUnit A verification unit for a cash receipt.
055         * @param statii A collection of potential cash receipt document statuses.
056         * @return List of CashReceiptDocument instances.
057         * @throws IllegalArgumentException Thrown if verificationUnit is blank
058         * @throws IllegalArgumentException Thrown if statii is null or empty or contains any blank statusCodes
059         */
060        public List getCashReceipts(String verificationUnit, String[] statii);
061        
062        /**
063         * This adds the currency and coin details associated with this Cash Receipt document to the proper cash drawer and to the
064         * cumulative Cash Receipt details for the document which opened the cash drawer.
065         * 
066         * @param crDoc The cash receipt document with cash details to add to the cash drawer.
067         */
068        public void addCashDetailsToCashDrawer(CashReceiptDocument crDoc);
069        
070        /**
071         * Checks whether the CashReceiptDocument's cash totals are invalid, generating global errors if so.
072         * 
073         * @param cashReceiptDocument submitted cash receipt document
074         * @return true if CashReceiptDocument's cash totals are valid
075         */
076        public abstract boolean areCashTotalsInvalid(CashReceiptDocument cashReceiptDocument);
077    }
078