/*
 * Copyright 2007 The Kuali Foundation
 * 
 * Licensed under the Educational Community License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 * http://www.opensource.org/licenses/ecl2.php
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.kuali.ole.sys.batch.service;

import java.io.InputStream;
import java.util.List;

import org.kuali.ole.sys.batch.BatchInputFileType;
import org.kuali.ole.sys.exception.FileStorageException;
import org.kuali.rice.kim.api.identity.Person;
import org.kuali.rice.krad.exception.AuthorizationException;

/**
 * Interface defining methods to manage batch input files.
 */
public interface BatchInputFileService {
    /**
     * Unmarshalls the file contents to an Object using the digestor and digestor rules file specified in the batch input type.
     * 
     * @param batchInputFileType - batch input file type for the file to parse
     * @param fileByteContent - byte contents of file to parse
     * @return - Object built from the file contents based on its xml unmarshalling rules
     */
    public Object parse(BatchInputFileType batchInputFileType, byte[] fileByteContent);

    /**
     * Using the input type object parses and validates the file contents by calling validate on the batch input type. If there were
     * validation errors, GlobalVariables.errorMap will contain the error messages.
     * 
     * @param inputType - instance of a BatchInputFileType
     * @param parsedObject - the Object built from parsing xml contents
     * @return boolean - true if validation was successful, false if there were errors
     */
    public boolean validate(BatchInputFileType inputType, Object parsedObject);
    /**
     * Stores the inputstream as a file on the server, identified by the given user file name.
     * 
     * @param user - user who is requesting the save
     * @param inputType - instance of a BatchInputFileType
     * @param fileUserIdentifier - file identifier specified by user
     * @param fileContents - contents of the uploaded file
     * @param parsedObject - object parsed from the input file
     * @return String - name of file that was saved, or null if errors were enountered
     * @throws FileStorageException - if errors were encountered while attempting to write the file
     */
    public String save(Person user, BatchInputFileType inputType, String fileUserIdentifier, InputStream fileContents, Object parsedObject) throws AuthorizationException, FileStorageException;
    
    /**
     * Stores the inputstream as a file on the server, identified by the given user file name.
     * 
     * @param user - user who is requesting the save
     * @param inputType - instance of a BatchInputFileType
     * @param fileUserIdentifier - file identifier specified by user
     * @param fileContents - contents of the uploaded file
     * @param parsedObject - object parsed from the input file
     * @param destinationFilePath - destination path selected by user for storing the ole format xml.
     * @param extension - extension of the file selected through marc file upload screen 
     * @return String - name of file that was saved, or null if errors were enountered
     * @throws FileStorageException - if errors were encountered while attempting to write the file
     */
    public String save(Person user, BatchInputFileType inputType, String fileUserIdentifier, InputStream fileContents, Object parsedObject,String destinationFilePath,String extension) throws AuthorizationException, FileStorageException;

    /**
     * Checks if the batch input type is active (can be used for upload).
     * 
     * @param batchInputFileType - input type to check is active
     * @return boolean - true if type is active, false if not active
     */
    public boolean isBatchInputTypeActive(BatchInputFileType batchInputFileType);

    /**
     * Returns a list of batch type file names (without path) that the given user has permissions to manage. Path is intentionally
     * excluded to prevent security problems arising from giving users access to the full path.
     * 
     * @param user - user for checking permissions
     * @return List<String> - List of filenames
     */
    public List<String> listBatchTypeFilesForUser(BatchInputFileType batchInputFileType, Person user) throws AuthorizationException;

    /**
     * Returns a list of existing input files for the batch type that have an associated .done file
     * 
     * @param batchInputFileType - batch type to retieve files for
     * @return List<String> - List of filenames
     */
    public List<String> listInputFileNamesWithDoneFile(BatchInputFileType batchInputFileType);

    /**
     * Returns whether a file user identifier is properly formatted.
     * 
     * @param fileUserIdentifier
     * @return
     */
    public boolean isFileUserIdentifierProperlyFormatted(String fileUserIdentifier);
   
}