/*
    * The Kuali Financial System, a comprehensive financial management system for higher education.
    * 
    * Copyright 2005-2014 The Kuali Foundation
    * 
    * This program is free software: you can redistribute it and/or modify
    * it under the terms of the GNU Affero General Public License as
    * published by the Free Software Foundation, either version 3 of the
    * License, or (at your option) any later version.
   * 
   * This program is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   * GNU Affero General Public License for more details.
   * 
   * You should have received a copy of the GNU Affero General Public License
   * along with this program.  If not, see <http://www.gnu.org/licenses/>.
   */
  package org.kuali.kfs.module.tem.document.service;
  
  import java.sql.Date;
  import java.sql.Timestamp;
  import java.util.Collection;
  import java.util.List;
  import java.util.Map;
  import java.util.Set;
  
  import org.kuali.kfs.integration.ar.AccountsReceivableOrganizationOptions;
  import org.kuali.kfs.module.tem.businessobject.ActualExpense;
  import org.kuali.kfs.module.tem.businessobject.ExpenseTypeAware;
  import org.kuali.kfs.module.tem.businessobject.GroupTraveler;
  import org.kuali.kfs.module.tem.businessobject.PerDiem;
  import org.kuali.kfs.module.tem.businessobject.PerDiemExpense;
  import org.kuali.kfs.module.tem.businessobject.SpecialCircumstances;
  import org.kuali.kfs.module.tem.businessobject.TemExpense;
  import org.kuali.kfs.module.tem.businessobject.TemSourceAccountingLine;
  import org.kuali.kfs.module.tem.businessobject.TransportationModeDetail;
  import org.kuali.kfs.module.tem.businessobject.TravelAdvance;
  import org.kuali.kfs.module.tem.businessobject.TripType;
  import org.kuali.kfs.module.tem.document.TEMReimbursementDocument;
  import org.kuali.kfs.module.tem.document.TravelAuthorizationDocument;
  import org.kuali.kfs.module.tem.document.TravelDocument;
  import org.kuali.kfs.module.tem.document.TravelReimbursementDocument;
  import org.kuali.rice.core.api.util.KeyValue;
  import org.kuali.rice.core.api.util.type.KualiDecimal;
  import org.kuali.rice.kew.api.exception.WorkflowException;
  import org.kuali.rice.kim.api.identity.Person;
  import org.kuali.rice.krad.document.Document;
  import org.kuali.rice.krad.uif.field.LinkField;
  
  /**
   * Travel Document Service
   */
  public interface TravelDocumentService {
  
      public String getMessageFrom(final String messageType, String... args);
  
      List<SpecialCircumstances> findActiveSpecialCircumstances(String documentNumber, String documentType);
  
      List<TravelAuthorizationDocument> findAuthorizationDocuments(final String travelDocumentNumber);
  
      /**
       * Retrieves the numbers of any Travel Authorization (or child) documents associated with the given trip id
       * @param travelDocumentIdentifier the trip id to find authorizations related to
       * @return a List of TravelAuthorization (or child!) document numbers for authorizations associated with the given trip id
       */
      List<String> findAuthorizationDocumentNumbers(final String travelDocumentIdentifier);
  
      List<TravelReimbursementDocument> findReimbursementDocuments(final String travelDocumentIdentifier);
  
      /**
       * Updates the perdiem items in a {@link TravelReimbursementDocument}. Can be used on an empty {@link Collection}. This means
       * that if there are no perdiem items, it will recreate. Perfect do all stupid method.
       *
       * @param documentNumber is the original document number for reference to link the {@link Collection} items to
       * @param perDiemList is the {@link List} that holds the per diem items. Please let this not be null
       * @param perDiemId is the id of the {@link PerDiem} object used for this item
       * @param start is the {@link Date} for the start of the trip
       * @param end is the {@link Date} for the end of the trip
       */
      void updatePerDiemItemsFor(final TravelDocument document, final List<PerDiemExpense> perDiemList, final Integer perDiemId, final Timestamp start, final Timestamp end);
  
      /**
       * Wrapper function to retrieve by document number
       *
       * @param document
       * @return
       * @throws WorkflowException
       */
      Map<String, List<Document>> getDocumentsRelatedTo(final TravelDocument document) throws WorkflowException;
  
      /**
       *  Get DV, TA, TAA, TAC, TR, and AV documents related to the given <code>documentNumber</code>. travel document either
       * have a TEM document number or they have the value of the <code>travelDocumentIdentifier</code> in their organization doc
       * ids.
       *
       * @param documentNumber
       * @return
       * @throws WorkflowException
      */
     Map<String, List<Document>> getDocumentsRelatedTo(final String documentNumber) throws WorkflowException;
 
     /**
      * Get related document lists filtering by the document type
      *
      * @param document
      * @param documentType
      * @return
      */
     List<Document> getDocumentsRelatedTo(final TravelDocument document, String... documentType);
 
 
     /**
      * @deprecated This method is no longer called and will be removed in KFS 6.0.
      *
      * This method will add fyi notes to initiator when document is cancelled, closed, etc.
      *
      * @param document
      */
     @Deprecated
     void addAdHocFYIRecipient(final Document document);
 
     /**
      * This method will add fyi notes to initiator when document is cancelled, closed, etc.
      *
      * @param document
      * @param initiatorUserId
      */
     void addAdHocFYIRecipient(final Document document, String initiatorUserId);
 
     /**
      * This method will add notes to initiator when document is cancelled, closed, etc.
      *
      * @param document
      * @param initiatorUserId
      */
     void addAdHocRecipient(Document document, String initiatorUserId, String actionRequested);
 
     void routeToFiscalOfficer(final TravelDocument document, final String noteText) throws WorkflowException, Exception;
 
     /**
      * This method copies the per diem expense object
      *
      * @param perDiemExpense
      * @return the copied per diem expense
      */
     PerDiemExpense copyPerDiemExpense(PerDiemExpense perDiemExpense);
 
     /**
      * This method calculates mileage and returns calculated value
      *
      * @param actualExpense
      * @return mileageAmount
      */
     KualiDecimal calculateMileage(ActualExpense actualExpense);
 
     /**
      *
      */
     public void handleNewActualExpense(final ActualExpense newActualExpenseLine);
 
     /**
      * This method calculates the daily total for a given per diem mileage expense
      *
      * @param perDiemMilaeage
      * @return a map for each expense (mileage, lodging, per diem)
      */
     Map<String, KualiDecimal> calculateDailyTotal(PerDiemExpense perDiemMilaeage);
 
     /**
      * This method calculates the daily totals for a list of per diem mileage expenses
      *
      * @param perDiemExpenses
      * @return a list of mapped totals
      */
     List<Map<String, KualiDecimal>> calculateDailyTotals(List<PerDiemExpense> perDiemExpenses);
 
     /**
      * This method copies from one per diem mileage down the rest of the list
      *
      * @param travelDocument the travel document (with begin or end dates) to help determine how much of the per diem expense to copy down
      * @param copyIndex
      * @param perDiemExpenses
      * @return the modified list of perDiemExpenses back
      */
     void copyDownPerDiemExpense(TravelDocument travelDocument, int copyIndex, List<PerDiemExpense> perDiemExpenses);
 
     /**
      * Determines if an object with an expense type is that of a "hosted" meal. In TEM a hosted meal is a meal that has been
      * provided by a hosting institution and cannot be taken as a reimbursement.
      *
      * @param havingExpenseType has an expense type to check for meal hosting
      * @return true if the expense is a hosted meal or not
      */
     boolean isHostedMeal(final ExpenseTypeAware havingExpenseType);
 
     /**
      * Check to see if the user has the travel manager role assigned to them
      *
      * @param user
      * @return true if the user is a travel manager, false otherwise
      */
     public boolean isTravelManager(final Person user);
 
     public Integer calculateProratePercentage(PerDiemExpense perDiemExpense, String perDiemCalcMethod, Timestamp tripEnd);
 
     public boolean isOpen(TravelDocument document);
 
     public boolean isProcessed(TravelDocument document);
 
     public boolean isFinal(TravelDocument document);
 
     /**
      * Check if the Travel authorization document has been successfully processed
      *
      * @param document
      * @return
      */
     public boolean isTravelAuthorizationProcessed(TravelAuthorizationDocument document);
 
     /**
      * Check if the Travel authroization document is processed AND is open for reimbursement in the app doc status
      *
      * @param document
      * @return
      */
     public boolean isTravelAuthorizationOpened(TravelAuthorizationDocument document);
 
     public boolean isUnsuccessful(TravelDocument document);
 
     public Integer calculatePerDiemPercentageFromTimestamp(PerDiemExpense perDiemExpense, Timestamp tripEnd);
 
     public KualiDecimal getAmountDueFromInvoice(String documentNumber, KualiDecimal requestedAmount);
 
     public TravelAuthorizationDocument findCurrentTravelAuthorization(TravelDocument document);
 
     public TravelDocument findRootForTravelReimbursement(String travelDocumentIdentifier);
 
     public KualiDecimal getTotalCumulativeReimbursements(TravelDocument document);
 
     public KualiDecimal getTotalAuthorizedEncumbrance(TravelDocument document);
 
     public boolean isResponsibleForAccountsOn(final TravelDocument document, String principalId);
 
     public boolean checkNonEmployeeTravelerTypeCode(String travelerTypeCode);
 
     /**
      * This is a ajax method, will be used to retrieve all states based on the country code passed
      *
      * @param countryCode
      * @return String
      */
     public String getAllStates(final String countryCode);
 
     /**
      * Copies group travelers and sets new document number
      */
     public List<GroupTraveler> copyGroupTravelers(List<GroupTraveler> groupTravelers, String documentNumber);
 
     /**
      * Copies other travel expenses and sets new document number
      */
     public List<? extends TemExpense> copyActualExpenses(List<? extends TemExpense> actualExpenses, String documentNumber);
 
     /**
      * Copies per diem expenses and sets new document number
      */
     public List<PerDiemExpense> copyPerDiemExpenses(List<PerDiemExpense> perDiemExpenses, String documentNumber);
 
     /**
      * Copies travel advances and sets new document number
      */
     public List<TravelAdvance> copyTravelAdvances(List<TravelAdvance> travelAdvances, String documentNumber);
 
     /**
      * Copies special circumstances and sets new document number
      */
     public List<SpecialCircumstances> copySpecialCircumstances(List<SpecialCircumstances> specialCircumstancesList, String documentNumber);
 
     /**
      * Copies transportation mode details and sets new document number
      */
     public List<TransportationModeDetail> copyTransportationModeDetails(List<TransportationModeDetail> transportationModeDetails, String documentNumber);
 
     /**
      *
      * @param document
      */
     public void showNoTravelAuthorizationError(TravelReimbursementDocument document);
 
     /**
      *
      * This method gets the total of all advances given for the trip relating to the travel document.
      * @param travelDocument
      * @return {@linK KualiDecimal} that is the total of all advances
      */
     KualiDecimal getAdvancesTotalFor(final TravelDocument travelDocument);
 
     /**
      * get all outstanding travel advances by the given invoice document numbers. The advances must have not been used to generate
      * taxable ramification
      *
      * @param arInvoiceDocNumbers the given AR invoice document numbers
      * @return a list of outstanding travel advances
      */
 
     List<TravelAdvance> getOutstandingTravelAdvanceByInvoice(Set<String> arInvoiceDocNumber);
 
     String retrieveAddressFromLocationCode(String locationCode);
 
     /**
      * Remove the imported expense from the document (though DB)
      *
      * @param document
      */
     public void detachImportedExpenses(TravelDocument document);
 
     /**
      * Adding the imported expense to the document (in the DB)
      *
      * @param document
      */
     public void attachImportedExpenses(TravelDocument document);
 
     public boolean checkHoldGLPEs(TravelDocument document);
 
     public void revertOriginalDocument(TravelDocument travelDocument, String status);
 
     /**
      * find the latest taxable ramification notification date
      *
      * @return the latest taxable ramification notification date
      */
     Date findLatestTaxableRamificationNotificationDate();
 
     /**
      * Perform validation on accounting lines that have already been entered, but have the potential to have bad data inserted into the db.
      * @param TravelDocument
      * @return
      *      true if valid, false otherwise
      */
     public boolean validateSourceAccountingLines(TravelDocument travelDocument, boolean addToErrorPath);
 
     /**
      * Get the Generic document type name of the travel document
      *
      * TA(not TAC, TAA), TR, ENT, RELO
      *
      * @param document
      * @return
      */
     public String getDocumentType(TravelDocument document);
 
     /**
      *
      * This method creates a key-value pair of MileageRates that are valid for the searchDate.
      * @param searchDate
      * @return
      */
     List<KeyValue> getMileageRateKeyValues(Date searchDate);
 
     /**
      * Import {@link GroupTraveler} instances into a {@link TravelDocument} via CSV data
      *
      *  @param document to add {@link GroupTraveler} instances to
      *  @param csvData
      *  @throws Exception when there's an error parsing the CSV data
      */
     List<GroupTraveler> importGroupTravelers(final TravelDocument document, final String csvData) throws Exception;
 
     /**
      *
      * This method imports the file and convert it to a list of objects (of the class specified in the parameter)
      * @param formFile
      * @param c
      * @param attributeNames
      * @param tabErrorKey
      * @return
      */
     <T> List<T> importFile(final String fileContents, final Class<T> c, final String[] attributeNames,
                            final Map<String,List<String>> defaultValues, final Integer[] attributeMaxLength, final String tabErrorKey);
 
     /**
      * Returns all travel advances associated with the passed in trip id
      * @param travelDocumentIdentifier the trip id of the reimbursement
      * @return a List of all TravelAdvances associated with that trip
      */
     public List<TravelAdvance> getTravelAdvancesForTrip(String travelDocumentIdentifier);
 
     /**
      * @return the default AR organization options for TEM documents
      */
     public AccountsReceivableOrganizationOptions getOrgOptions();
 
     /**
      * This method searches to make sure that the expense entered doesn't already exist
      * If they exist, disable them in the per diem table and notify the user.
      * @param trDocument
      *          the current doc.
      * @param actualExpense
      *          the expense in question
      */
     public void disableDuplicateExpenses(TravelDocument trDocument, ActualExpense actualExpense);
 
     /**
      * Sets the meal and incidental amounts on the given per diem expense
      * @param expense the expense to set amounts on
      * @param perDiem the per diem record amounts are based off of
      * @param tripType the trip type being taken
      * @param tripEnd the end time of the trip
      * @param shouldProrate whether this expense should be prorated
      */
     public void setPerDiemMealsAndIncidentals(PerDiemExpense expense, PerDiem perDiem, TripType tripType, Timestamp tripEnd, boolean shouldProrate);
 
     /**
      *
      * This method gets the parent travel document by travel document identifier
      * This means: the current TA which is the authorization of the trip; or if no TA is present, the root TR, ENT, or RELO document
      *  @param travelDocumentIdentifier
      *  @return
      */
     public TravelDocument getParentTravelDocument(String travelDocumentIdentifier);
 
     /**
      * Returns the root travel document by the travel document identifier.  This is the progenitor document of the trip - either the first TA,
      * first TR, first ENT, or first RELO which began the trip
      * It does not retrieve the workflow document of the associated document
      * @param travelDocumentIdentifier
      * @return the root document of the trip
      */
     public TravelDocument getRootTravelDocumentWithoutWorkflowDocument(String travelDocumentIdentifier);
 
     /**
      * This method retrieves a list of approved documents related to a travelDocumentIdentifier. It will grab the most current TA (TAA, TAC)
      * and all TR, ENT, and RELO for the given identifier.
      *
      * @param travelDocumentIdentifier
      * @return
      */
     public Collection<String> getApprovedTravelDocumentNumbersByTrip(String travelDocumentIdentifier);
 
     /**
      * This method determines whether a document is in the correct state for reconciling external vendor charges.
      *
      * @param travelDocument
      * @return
      */
     public boolean isDocumentStatusValidForReconcilingCharges(TravelDocument travelDocument);
 
     /**
      * find matching trips  for the same traveler, dates
      *
      */
     public List<String> findMatchingTrips(TravelDocument document);
 
     /**
      * If a value on a per diem expense has been zero'd out, this method will restore it to its default value
      * @param document the document with per diem expenses
      * @param property the property to restore
      */
     public void restorePerDiemProperty(TravelDocument document, String property);
 
     /**
      * This smooshes the accounting lines which will do advance clearing.  Here, since we're replacing the object code, we'll smooth together all accounting lines
      * which have the same chart - account - sub-acount.
      * @param originalAccountingLines the List of accounting lines to smoosh
      * @return the smooshed accounting lines
      */
     public List<TemSourceAccountingLine> smooshAccountingLinesToSubAccount(List<TemSourceAccountingLine> originalAccountingLines);
 
     /**
      * Generates a list of agency links for the document.  If property config.document.travelRelocation.agencySites.enable is false,
      * then an empty list will be returned; otherwise uses values from the url.document.travelRelocation.agencySites, customized by
      * the customizeAgencyLink method
      * @param travelDocument the travel document we're currently building a link for
      * @return a List of links to external agencies
      */
     public List<LinkField> getAgencyLinks(TravelDocument travelDocument);
 
     /**
      * A hook which allows implementers to customize an agency link.  Currently, it will just see if the config.document.travelRelocation.agencySites.include.tripId
      * is set to true; if so, it will append ?tripId= the trip id
      * @param travelDocument the travel document we are creating agency links for
      * @param agencyName the name of the agency
      * @param link the current link text
      * @return the customized link text
      */
     public String customizeAgencyLink(TravelDocument travelDocument, String agencyName, String link);
 
     /**
      * Checks whether the TEMReimbursementDocument require traveler's approval routing based on its travel arranger's profile.
      * @param trDoc the TEMReimbursementDocument to be checked
      * @return true if the trDoc requires traveler's approval; false otherwise
      */
     public boolean requiresTravelerApproval(TEMReimbursementDocument trDoc);
 
     /**
      * Checks whether the TravelAuthorizationDocument require traveler's approval routing based on its travel arranger's profile.
      * @param taDoc the TravelAuthorizationDocument to be checked
      * @return true if the taDoc requires traveler's approval; false otherwise
      */
     public boolean requiresTravelerApproval(TravelAuthorizationDocument taDoc);
 
     /**
      * Checks whether the TravelDocument's initiator is the traveler him/herself (if not, then the initiator is one of the arranger).
      * @param travelDoc the TravelDocument to be checked
      * @return true if the TravelDocument's initiator is the traveler.
      */
     public boolean isInitiatorTraveler(TravelDocument travelDoc);
 
 }