001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 */
021
022package org.biojava.bio.program.gff;
023
024import java.util.Comparator;
025import java.util.Map;
026
027import org.biojava.bio.seq.StrandedFeature;
028
029/**
030 * A single GFF record.
031 * <p>
032 * This object has fields for each GFF field. It also defines a couple of
033 * useful constants.
034 * <p>
035 * GFF is described at http://www.sanger.ac.uk/Software/formats/GFF/
036 *
037 * @author Matthew Pocock
038 * @author Keith James (docs)
039 */
040public interface GFFRecord {
041  /**
042   * The sequence name field.
043   * <p>
044   * This should be the name of the sequence that this GFF record is within.
045   *
046   * @return the name of the sequence
047   */
048  public String getSeqName();
049  
050  /**
051   * The source, or creator of this feature.
052   * <p>
053   * This is usualy a program name.
054   *
055   * @return the feature source
056   */
057  public String getSource();
058  
059  /**
060   * The feature type filed.
061   * <p>
062   * This is something like "exon" - usualy corresponds to an EMBL term.
063   *
064   * @return the feature type
065   */
066  public String getFeature();
067  
068  /**
069   * The start of this feature within the source sequence.
070   *
071   * @return the start index
072   */
073  public int getStart();
074
075  /**
076   * The end of this feature within the source sequence.
077   *
078   * @return the end index
079   */
080  public int getEnd();
081  
082  /**
083   * The score of the feature.
084   * <p>
085   * For sequences that have no score, this will be set to
086   * <span class="type">GFFRecord</span>.<span class="const">NO_SCORE</span>.
087   *
088   * @return the score, or NO_SCORE
089   */
090  public double getScore();
091  
092  /**
093   * The strand of the feature.
094   * <p>
095   * This will be one of <span class="type">GFFRecord</span>.<span class="const">POSITIVE_STRAND</span>,
096   * <span class="type">GFFRecord</span>.<span class="const">NEGATIVE_STRAND</span>,
097   * or <span class="type">GFFRecord</span>.<span class="const">NO_STRAND</span>.
098   *
099   * @return the strand field
100   */
101  public StrandedFeature.Strand getStrand();
102  
103  /**
104   * The frame of the feature.
105   * <p>
106   * This will be one of <code>{1, 2, 3}</code> or
107   * <span class="type">GFFRecord</span>.<span class="const">NO_FRAME</span>.
108   *
109   * @return the frame field
110   */
111  public int getFrame();
112  
113  /**
114   * A <span class="type">Map</span> containing the group / attribute information.
115   * <p>
116   * This will be a <span class="type">Map</span> of group-names to
117   * <span class="type">List</span> objects.
118   *
119   * @return a <span class="type">Map</span> containing the group and attribute info.
120   */
121  public Map getGroupAttributes();
122  
123  /**
124   * The feature comment.
125   *
126   * @return <span class="kw">null</span> or the feature comment
127   */
128  public String getComment();
129  
130  /**
131   * Flag to indicate that there is no score info.
132   *
133   * @deprecated  Use GFFTools.NO_SCORE instead
134   */
135  public static double NO_SCORE = GFFTools.NO_SCORE;
136
137  /**
138   * Flag to indicate that there is no frame info.
139   *
140   * @deprecated  Use GFFTools.NO_FRAME instead
141   */
142  public static int NO_FRAME = GFFTools.NO_FRAME;
143  
144  /**
145   * Comparator which defines a useful sort order for GFF records.
146   * GFFRecord properties are considered in the following order
147   *
148   * <ol>
149   * <li>Sequence name</li>
150   * <li>Feature start</li>
151   * <li>Feature end</li>
152   * <li>Feature type</li>
153   * <li>Feature source</li>
154   * <li>The complete GFF line corresponding to this record</li>
155   * </ol>
156   *
157   * <p>
158   * Two records are equal iff their GFF lines are character-for-character
159   * identical.
160   * </p>
161   *
162   * @since 1.4
163   */
164  
165  public static final Comparator NATURAL_ORDER = new GFFComparator();
166}
167