001    /*
002     * Copyright 2007, 2012 Stephen Fisher and Junhyong Kim, University of
003     * Pennsylvania.
004     *
005     * This file is part of Glo-DB.
006     * 
007     * Glo-DB is free software: you can redistribute it and/or modify it
008     * under the terms of the GNU General Public License as published by
009     * the Free Software Foundation, either version 3 of the License, or
010     * (at your option) any later version.
011     * 
012     * Glo-DB is distributed in the hope that it will be useful, but
013     * WITHOUT ANY WARRANTY; without even the implied warranty of
014     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015     * General Public License for more details.
016     * 
017     * You should have received a copy of the GNU General Public License
018     * along with Glo-DB. If not, see <http://www.gnu.org/licenses/>.
019     *
020     * @(#)Feature.java
021     */
022    
023    package edu.upenn.gloDB;
024    
025    import java.util.HashMap;
026    import java.io.Serializable;
027    
028    /** 
029     * Feature interface.  Features implement Comparable and thus must
030     * implement a compareTo() method.  This is required to maintain the
031     * sorting of Features in Tracks.
032     *
033     * @author  Stephen Fisher
034     * @version $Id: Feature.java,v 1.53.2.9 2007/03/01 21:17:32 fisher Exp $
035     */
036    
037    public interface Feature extends Comparable, Serializable { 
038    
039        /** Set the Feature attributes. */
040             public void setAttributes(String attributes);
041    
042        /** Set the Feature attributes from a HashMap. */
043             public void setAttributes(HashMap attribMap);
044    
045        /** Get the Feature attributes. */
046             public String getAttributes();
047    
048        /** Returns true if attribute 'key' exists. */
049        public boolean containsAttribute(String key);
050    
051        /** Get the Feature attributes as HashMap. */
052             public HashMap getAttributesMap();
053    
054        /** Get value for attribute 'key'. */
055        public String getAttribute(String key);
056    
057             /**
058              * Returns the start position of the Feature.  This should return
059              * the same value as getMin().
060              */
061             public int getStart();
062    
063             /**
064              * Returns the maximum position of the Feature.  If the Feature
065              * consists of a fuzzy Feature, this may not be the maximum
066              * position.
067              */
068             public int getStop();
069    
070             /**
071              * Returns the number of positions contained in the Feature.
072              */
073             public int length();
074    
075             /**
076              * Returns the initial position of the Feature.  This should return 
077              * the same value as getStart().
078              */
079             public int getMin();
080    
081             /**
082              * Returns the maximum position of the Feature.  If the Feature
083              * consists of a fuzzy Feature, this may not be equal to 'stop'.
084              */
085             public int getMax();
086    
087             /** 
088              * Returns the underlying Sequence object.  
089              */
090             public Sequence getSource();
091    
092             /** 
093              * Returns the underlying Sequence object's ID.  
094              */
095             public String getSourceID();
096    
097             /** 
098              * Returns the underlying sequence data.
099              */
100             public String getData();
101    
102             /** 
103              * Returns the Sequence data, with "\n" inserted every
104              * Sequence.FORMAT_WIDTH characters (usually 50 to 80 chars).
105              */
106             public String getDataFormatted();
107    
108             /**
109              * Compares this object with the specified object for order.
110              * Returns a negative integer, zero, or a positive integer as this
111              * object is less than, equal to, or greater than the specified
112              * object.
113              * @XXX This is necessary for 'Comparable'.
114              */
115             public int compareTo(Object o);
116    
117             /**
118              * This will return true if the features are equal and the sources
119              * are the same.  If can't cast argument as a valid feature, then
120              * throws a java.lang.ClassCastException.
121              */
122             public boolean equals(Object o);
123    
124             /**
125              * Returns '-1' if this Feature exists after the integer 'pos',
126              * returns '0' if 'pos' is contained in this Feature, and '1' if
127              * 'pos' occurs after this Feature.
128              * @XXX This assumes 'pos' is positive within this Feature's
129              * Sequence boundaries.
130              * @XXX Not clear how to deal with Sequences in Tracks.
131              * @XXX For Tracks, this should test contains() for each
132              * Feature within the Track.
133              */
134             public int contains(int pos);
135    
136             /**
137              * Returns 'true' if the Feature 'feature' exists in this Feature.
138              */
139             public boolean contains(Feature feature);
140    
141             /**
142              * Returns 'true' if the Feature 'feature' has at least one
143              * position that overlaps positions in this Feature.
144              */
145             public boolean overlaps(Feature feature);
146    
147             /**
148              * Returns the overlapping region between the two Features.  If no
149              * overlap, then null is returned.
150              */
151             public Feature overlap(Feature feature);
152    
153             /**
154              * Inverts the positions, returning a new Feature object.  For
155              * example, if the Feature had a start position of 10 and a stop
156              * position of 20 on a Sequence that was 100 positions long, then
157              * flipping the Feature would result in a new Feature object with
158              * a start position of 80 and a stop position of 90.  
159              */
160             public Feature flip();
161    
162             /** Only returns basic Feature information. */
163             public String toString();
164    
165             /** Only returns Feature start/stop information. */
166             public String toStringMin();
167    
168             /** Returns all Feature information, except the data. */
169             public String toStringFull();
170    
171    } // Feature.java