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.service;
017    
018    import org.kuali.kfs.fp.businessobject.CashDrawer;
019    import org.kuali.rice.kns.util.KualiDecimal;
020    
021    /**
022     * This service interface defines methods that a CashDrawerService implementation must provide.
023     * 
024     */
025    public interface CashDrawerService {
026        /**
027         * Closes the CashDrawer instance associated with the given campus code, creating one if necessary.
028         * 
029         * @param campusCode The campus code used to retrieve the cash drawer to be closed.
030         */
031        public void closeCashDrawer(String campusCode);
032    
033        /**
034         * Closes the cash drawer associated with the given document
035         * 
036         * @param cd The cash drawer to closed.
037         */
038        public void closeCashDrawer(CashDrawer cd);
039    
040        /**
041         * 
042         * Opens the CashDrawer instance associated with the given campus, creating one if necessary. Records the given
043         * documentId as the document which opened the cashdrawer.
044         * 
045         * @param campusCode The campus code to be used to retrieve the cash drawer to be closed.
046         * @param documentId The id of the document used to open the cash drawer.
047         * @return The opened version of the cash drawer.
048         */
049        public CashDrawer openCashDrawer(String campusCode, String documentId);
050        
051        /**
052         * Opens the given cash drawer
053         * 
054         * @param cd The cash drawer to open
055         * @param documentId the document number which is opening the cash drawer
056         * @return The opened version of the cash drawer
057         */
058        public CashDrawer openCashDrawer(CashDrawer cd, String documentId);
059    
060        /**
061         * Locks the currently-open CashDrawer instance associated with the given campus, throwing an IllegalStateException if
062         * that cashDrawer is not open (i.e. is closed or locked). Records the given documentId as the document which locked the
063         * cashDrawer.
064         * 
065         * @param campusCode The campus code used to retrieve the cash drawer to be locked.
066         * @param documentId The id of the document used to lock the cash drawer.
067         */
068        public void lockCashDrawer(String campusCode, String documentId);
069        
070        /**
071         * Locks the given cash drawer, if it is open
072         * 
073         * @param cd The cash drawer to open
074         * @param documentId The document id which is locking the cash drawer
075         */
076        public void lockCashDrawer(CashDrawer cd, String documentId);
077    
078        /**
079         * Unlocks the currently-locked CashDrawer instance associated with the given campus code, 
080         * throwing an IllegalStateException if that cashDrawer is not locked (i.e. is closed or open). 
081         * Records the given documentId as the document which unlocked the cashDrawer.
082         * 
083         * @param campusCode The campus code used to retrieve the cash drawer to be unlocked.
084         * @param documentId The id of the document used to unlock the cash drawer.
085         */
086        public void unlockCashDrawer(String campusCode, String documentId);
087        
088        /**
089         * Unlocks the given cash drawer, if it is open and locked
090         * 
091         * @param cd The cash drawer to unlock
092         * @param documentId The document which is unlocking the cash drawer
093         */
094        public void unlockCashDrawer(CashDrawer cd, String documentId);
095    
096        /**
097         * Retrieves the CashDrawer instance associated with the given campus code, if any. If autocreate is true, 
098         * and no CashDrawer for the given campus exists, getByCampusCode will return a newly-created 
099         * (non-persisted) CashDrawer instance.
100         * 
101         * @param campusCode The campus code used to retrieve the cash drawer.
102         * @return CashDrawer instance or null
103         */
104        public CashDrawer getByCampusCode(String campusCode);
105        
106        /**
107         * Calculates the total amount of all the currency in the drawer.  
108         * NOTE: The value returned only refers to paper currency in the drawer and does not include coin amounts.
109         * 
110         * @param drawer The cash drawer to calculate the currency total from.
111         * @return The summed amount of currency in the cash drawer.
112         */
113        public KualiDecimal getCurrencyTotal(CashDrawer drawer);
114        
115        /**
116         * Calculates the total amount of all the coins in the drawer. 
117         * 
118         * @param drawer The drawer to calculate the coin total from.
119         * @return The summed value of coins in the drawer.
120         */
121        public KualiDecimal getCoinTotal(CashDrawer drawer);
122    }