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.service;
017
018import org.kuali.ole.fp.businessobject.CashDrawer;
019import org.kuali.rice.core.api.util.type.KualiDecimal;
020
021/**
022 * This service interface defines methods that a CashDrawerService implementation must provide.
023 * 
024 */
025public 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}