001    package calhoun.analysis.crf.io;
002    
003    import java.util.Collection;
004    
005    /** represents the observed inputs.  Contains a sequence of inputs, and allows them to be retrieved by position.<p>
006     * An input sequence may be made up of different components.  If it contains components the {@link #getComponent} and 
007     * {@link #listComponents()} functions must be implemented.  Otherwise they can just trhow {@link UnsupportedOperationException}.
008     * <p>
009     * In some cases, the input may not be a sequence.  It may be a single input value that is returned for all positions.  In
010     * this case, the length value can return -1 and the {@link #getX} function can return the same object at each position.
011     * */
012    public interface InputSequence<A> {
013            
014            /** retrieves the input value at a position in the input sequence.
015             * @param x the index position at which to get the input.  This is a zero-based index.
016             * @return the object at this position in the input.
017             */
018            A getX(int x);
019            
020            /** Returns the length of this sequence 
021             * @return length */
022            int length() ;
023            
024            /**tTakes a subinterval of the input sequence with given start-end coordinates
025             * which are relative coordinates, 1-based, and inclusive.  Thus 1-10 will mean
026             * returning a new InputSequence which is the first 10 positions of the current one.<p>  
027             * An implementation that does not support subsetting should throw an {@link UnsupportedOperationException}
028             * @param start the 1-based index of the first position of the input to retrieve.
029             * @param end the 1-based index of the last position  of the input to retrieve.
030             * @return an input sequence which is a sbusequence of the original sequence.
031             *  */
032            InputSequence<A> subSequence(int start, int end) ;
033            
034            /** For input sequences that are a composite of several different input objects, returns 
035             * a particular component of the input. For simple input sequences that just return an object, 
036             * this method should throw {@link UnsupportedOperationException}. 
037             * @param name the name of the input component to return 
038             * @return the input sequence representing this component */
039            InputSequence<?> getComponent(String name);
040    
041            /** For input sequences that are a composite of several different input objects, returns a list of the names of the components in this input sequence. 
042             * For simple input sequences that just return an object, this method should throw UnsupportedOperationException. 
043             * @return a collection containing the component names */
044            Collection<String> listComponents();
045    }