001    package calhoun.analysis.crf.io;
002    
003    import java.io.IOException;
004    import java.io.Serializable;
005    import java.util.List;
006    import java.util.Map;
007    
008    /** interface to read or write {@link InputSequence} components to or from a file.  A single <code>InputComponentIO</code> is responsible for 
009     * reading and writing data at a single location, but may work with multiple components of the input sequence.
010     */
011    public interface InputComponentIO extends Serializable {
012            
013            /** A list of names of the components of the InputSequence created by this reader. 
014             * @return a list of input sequence component names. */
015            List<String> getComponentNames();
016            
017            /** reads input sequences from this location.  In most cases the location will be a file and this object will read in one or more components of the
018             * overall input from that file.  Alist of inputs is returned.  Each input consists of a set of key-value pairs, where the key is the name of the 
019             * input component and the value is an (@link InputSequence) object.  If this is not the first component to be loaded, this list may already contain
020             * entries for the input.  
021             * @param location the location of the data to read.  Meaning of the location is implementation dependent, but will usually be a file name.
022             * @param inputs a list of input sequences.  For each input sequence, a map is returned that maps component names to their
023             * associated {@link InputSequence} objects.
024             */
025            void readInputSequences(String location, List<Map<String, InputSequence<?>>> inputs) throws IOException;  
026    
027            /** writes input sequences to this location.  <code>InputComponentIO</code> optionally can implement this function to provide the ability to write input
028             * data as well as read it.  This is used by many of the data manipulation tools, such as those for subsetting and creating cross-validation sets.
029             * @param location the location of the data to write.  Meaning of the location is implementation dependent, but will usually be a file name.
030             * @param inputComponents an iterator over input sequences.  For each input sequence, a map is returned that maps component names to their
031             * associated {@link InputSequence} objects.  All components of the input are passed, and this object is reponsible for knowing which components
032             * it should be writing.
033             */
034            void writeInputSequences(String location, List<? extends Map<String, ? extends InputSequence<?>>> inputComponents)  throws IOException;  
035    }