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.module.purap.util;
017    
018    import java.util.List;
019    
020    import org.apache.struts.upload.FormFile;
021    import org.kuali.kfs.module.purap.businessobject.PurApItem;
022    
023    /**
024     * Defines an abstraction for parsing serialized <code>PurApItem</code> lines.
025     */
026    public interface ItemParser {
027    
028        /**
029         * Returns the defined format of item lines in the item import file.
030         * 
031         * @return the item line format as an array of item property names
032         */
033        public String[] getItemFormat();
034        
035        /**
036         * Returns the expected format of the items to be imported.
037         * 
038         * @param itemClass the class of the items to be imported
039         * @return the concatenation of the actual property names of the items to be imported
040         */
041        public String getExpectedItemFormatAsString( Class<? extends PurApItem> itemClass );
042        
043        /**
044         * Parses the specified item line into an instance of the specified PurApItem subclass.
045         * 
046         * @param itemLine the item line string to be parsed
047         * @param itemClass the subclass of the item to be generated
048         * @param documentNumber the number of the docment that contains the item to be generated
049         * @return the generated item
050         */
051        public PurApItem parseItem( String itemLine, Class<? extends PurApItem> itemClass, String documentNumber );
052    
053        /**
054         * Parses the items from the specified import file line by line,
055         * and generates items of the specified type from the parsed data.
056         * 
057         * @param itemFile the input file from which items are parsed
058         * @param itemClass a subclass of PurApItem, of which new items shall be generated
059         * @param documentNumber the number of the docment that contains the items to be imported
060         * @return a list of items of a subclass of PurApItem.
061         */
062        public List<PurApItem> importItems( FormFile itemFile, Class<? extends PurApItem> itemClass, String documentNumber );
063    
064    /****    
065     * 
066     */
067      /**
068       * Reads lines of <code>PurApItem</code> fields from the <code>InputStream</code> and parses them. 
069       *
070       * @param inputStream The <code>{@link InputStream}</code> to read data from.
071       * @param itemClass The subclass of <code>PurApItem</code> which parsed items belong to.
072       * @return A list of <code>{@link PurApItem}</code> instances.
073       * @exception IOException
074       *
075      public List importItemLines(InputStream inputStream, Class<? extends PurApItem> itemClass)
076          throws IOException, IllegalAccessException, InstantiationException;
077    
078      /**
079       * Determines the number of fields to be parsed.
080       *
081       * @return int number of fields expected.
082       *
083      public int getExpectedFieldCount();
084      
085    ****/  
086    }
087