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.document.service;
017
018import java.util.List;
019
020import org.kuali.ole.fp.document.CashReceiptDocument;
021import org.kuali.rice.kim.api.identity.Person;
022
023/**
024 * 
025 * This service interface defines the methods that a CashReceiptService implementation must provide.
026 */
027public 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