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.gff3;
023
024
025/**
026 * The interface for things that listen to GFF event streams.
027 * <p>
028 * This allows the GFF push model to run over large collections of GFF, filter
029 * them and access other resources without requiring vast numbers of GFF
030 * records to be in memory at any one time.
031 * <p>
032 * The stream includes both GFF records and comment lines. A particular
033 * handeler may choose to discard either of these.
034 * <p>
035 * It is assumed that a particular handler will only be used to listen to
036 * a single stream of events in a single thread. Particular implementations
037 * may not impose this restriction.
038 * 
039 * @author Matthew Pocock
040 * @author Thomas Down
041 * @author Keith James (docs)
042 */
043
044public interface GFF3DocumentHandler {
045  /**
046   * Indicates that a new GFF document has been started.
047   * This gives you a hook to set up per-document resources.
048   *
049   * @param locator A URI for the stream being parsed.
050   */
051  void startDocument(String locator);
052
053  /**
054   * Indicates that the current GFF document has now ended.
055   * <p>
056   * This gives you the chance to flush results, or do calculations if
057   * you wish.
058   */
059  void endDocument();
060  
061  /**
062   * A comment line has been encountered.
063   * <p>
064   * <span class="arg">comment</span> has already had the leading '<code>#</code>'
065   * removed, and may have had leading-and-trailing whitespace trimmed.
066   *
067   * @param comment  the comment <span class="type">String</span>
068   */
069  void commentLine(String comment);
070  
071  /**
072   * A record line has been encountered.
073   * <p>
074   * It is already preseneted to you into a <span class="type">GFFRecord</span> object.
075   *
076   * @param record  the <span class="type">GFFRecord</span> containing all the info
077   */
078  void recordLine(GFF3Record record);
079}