001: /*
002: * Copyright 2007 The Kuali Foundation.
003: *
004: * Licensed under the Educational Community License, Version 1.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/ecl1.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.service;
017:
018: import java.io.File;
019: import java.io.FileNotFoundException;
020: import java.io.InputStream;
021: import java.util.List;
022:
023: import org.kuali.core.bo.user.UniversalUser;
024: import org.kuali.core.exceptions.AuthorizationException;
025: import org.kuali.kfs.batch.BatchInputFileType;
026: import org.kuali.kfs.exceptions.FileStorageException;
027: import org.kuali.kfs.exceptions.XMLParseException;
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: * @throws XMLParseException - if there were errors encountered during parsing of the xml
040: */
041: public Object parse(BatchInputFileType batchInputFileType,
042: byte[] fileByteContent) throws XMLParseException;
043:
044: /**
045: * Using the input type object parses and validates the file contents by calling validate on the batch input type. If there were
046: * validation errors, GlobalVariables.errorMap will contain the error messages.
047: *
048: * @param inputType - instance of a BatchInputFileType
049: * @param parsedObject - the Object built from parsing xml contents
050: * @return boolean - true if validation was successful, false if there were errors
051: */
052: public boolean validate(BatchInputFileType inputType,
053: Object parsedObject);
054:
055: /**
056: * Stores the inputstream as a file on the server, identified by the given user file name.
057: *
058: * @param user - user who is requesting the save
059: * @param inputType - instance of a BatchInputFileType
060: * @param fileUserIdentifier - file identifier specified by user
061: * @param fileContents - contents of the uploaded file
062: * @param parsedObject - object parsed from the input file
063: * @return String - name of file that was saved, or null if errors were enountered
064: * @throws FileStorageException - if errors were encountered while attempting to write the file
065: */
066: public String save(UniversalUser user,
067: BatchInputFileType inputType, String fileUserIdentifier,
068: InputStream fileContents, Object parsedObject)
069: throws AuthorizationException, FileStorageException;
070:
071: /**
072: * Returns the contents of a batch input file contained on the server if the user has permissions for the files batch input
073: * type.
074: *
075: * @param user - user who is requesting the download
076: * @param inputType - instance of a BatchInputFileType
077: * @param downloadFileNameWithNoPath - name of the file to retrieve, with no path information
078: * @return File - File representation of the batch input, or null if errors occured. Check GlobalVariables.errorMap for error
079: * messages.
080: * @throws AuthorizationException - if user does not have permission to view batch files of this type FileNotFoundException - if
081: * given file does not exist on the file system
082: */
083: public File download(UniversalUser user,
084: BatchInputFileType inputType, String downloadFileName)
085: throws AuthorizationException, FileNotFoundException;
086:
087: /**
088: * Deletes a batch input file contained on the server if the user has permissions for the files batch input type. Also deletes
089: * the associated .done file if one exists. If deletion fails, this method will place the reason for failure in the
090: * GlobalVariables error map.
091: *
092: * @param user - user who is requesting the delete
093: * @param inputType - instance of a BatchInputFileType
094: * @param deleteFileNameWithNoPath - name of the file to remove, with no path information
095: * @return whether the file (and its done file) was deleted
096: * @throws AuthorizationException - if user does not have permission to delete batch files of this type FileNotFoundException -
097: * if given file does not exist on the file system
098: */
099: public boolean delete(UniversalUser user,
100: BatchInputFileType inputType,
101: String deleteFileNameWithNoPath)
102: throws AuthorizationException, FileNotFoundException;
103:
104: /**
105: * Returns whether a the given file has been processed by the associated batch job
106: *
107: * @param inputType
108: * @param fileNameWithNoPath
109: * @return
110: */
111: public boolean hasBeenProcessed(BatchInputFileType inputType,
112: String fileNameWithNoPath);
113:
114: /**
115: * Checks if the batch input type is active (can be used for upload).
116: *
117: * @param batchInputFileType - input type to check is active
118: * @return boolean - true if type is active, false if not active
119: */
120: public boolean isBatchInputTypeActive(
121: BatchInputFileType batchInputFileType);
122:
123: /**
124: * Checks if the user has permissions to manage the batch input type.
125: *
126: * @param batchInputFileType - input type to check user permissions on
127: * @param user - user to check
128: * @return boolean - true if user has permissions for the type, false if the user does not have permission
129: */
130: public boolean isUserAuthorizedForBatchType(
131: BatchInputFileType batchInputFileType, UniversalUser user);
132:
133: /**
134: * Returns a list of batch type file names (without path) that the given user has permissions to manage. Path is intentionally
135: * excluded to prevent security problems arising from giving users access to the full path.
136: *
137: * @param user - user for checking permissions
138: * @return List<String> - List of filenames
139: */
140: public List<String> listBatchTypeFilesForUser(
141: BatchInputFileType batchInputFileType, UniversalUser user)
142: throws AuthorizationException;
143:
144: /**
145: * Returns a list of existing input files for the batch type that have an associated .done file
146: *
147: * @param batchInputFileType - batch type to retieve files for
148: * @return List<String> - List of filenames
149: */
150: public List<String> listInputFileNamesWithDoneFile(
151: BatchInputFileType batchInputFileType);
152:
153: /**
154: * Returns whether a file user identifier is properly formatted.
155: *
156: * @param fileUserIdentifier
157: * @return
158: */
159: public boolean isFileUserIdentifierProperlyFormatted(
160: String fileUserIdentifier);
161: }
|