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.sys.batch.service;
017    
018    import java.io.File;
019    import java.io.FileNotFoundException;
020    import java.io.InputStream;
021    import java.text.ParseException;
022    import java.util.List;
023    
024    import org.kuali.kfs.sys.batch.BatchInputFileType;
025    import org.kuali.kfs.sys.exception.FileStorageException;
026    import org.kuali.rice.kim.bo.Person;
027    import org.kuali.rice.kns.exception.AuthorizationException;
028    
029    /**
030     * Interface defining methods to manage batch input files.
031     */
032    public interface BatchInputFileService {
033        /**
034         * Unmarshalls the file contents to an Object using the digestor and digestor rules file specified in the batch input type.
035         * 
036         * @param batchInputFileType - batch input file type for the file to parse
037         * @param fileByteContent - byte contents of file to parse
038         * @return - Object built from the file contents based on its xml unmarshalling rules
039         */
040        public Object parse(BatchInputFileType batchInputFileType, byte[] fileByteContent);
041    
042        /**
043         * Using the input type object parses and validates the file contents by calling validate on the batch input type. If there were
044         * validation errors, GlobalVariables.errorMap will contain the error messages.
045         * 
046         * @param inputType - instance of a BatchInputFileType
047         * @param parsedObject - the Object built from parsing xml contents
048         * @return boolean - true if validation was successful, false if there were errors
049         */
050        public boolean validate(BatchInputFileType inputType, Object parsedObject);
051    
052        /**
053         * Stores the inputstream as a file on the server, identified by the given user file name.
054         * 
055         * @param user - user who is requesting the save
056         * @param inputType - instance of a BatchInputFileType
057         * @param fileUserIdentifier - file identifier specified by user
058         * @param fileContents - contents of the uploaded file
059         * @param parsedObject - object parsed from the input file
060         * @return String - name of file that was saved, or null if errors were enountered
061         * @throws FileStorageException - if errors were encountered while attempting to write the file
062         */
063        public String save(Person user, BatchInputFileType inputType, String fileUserIdentifier, InputStream fileContents, Object parsedObject) throws AuthorizationException, FileStorageException;
064    
065        /**
066         * Checks if the batch input type is active (can be used for upload).
067         * 
068         * @param batchInputFileType - input type to check is active
069         * @return boolean - true if type is active, false if not active
070         */
071        public boolean isBatchInputTypeActive(BatchInputFileType batchInputFileType);
072    
073        /**
074         * Returns a list of batch type file names (without path) that the given user has permissions to manage. Path is intentionally
075         * excluded to prevent security problems arising from giving users access to the full path.
076         * 
077         * @param user - user for checking permissions
078         * @return List<String> - List of filenames
079         */
080        public List<String> listBatchTypeFilesForUser(BatchInputFileType batchInputFileType, Person user) throws AuthorizationException;
081    
082        /**
083         * Returns a list of existing input files for the batch type that have an associated .done file
084         * 
085         * @param batchInputFileType - batch type to retieve files for
086         * @return List<String> - List of filenames
087         */
088        public List<String> listInputFileNamesWithDoneFile(BatchInputFileType batchInputFileType);
089    
090        /**
091         * Returns whether a file user identifier is properly formatted.
092         * 
093         * @param fileUserIdentifier
094         * @return
095         */
096        public boolean isFileUserIdentifierProperlyFormatted(String fileUserIdentifier);
097    }
098