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.tagvalue;
023
024import org.biojava.utils.ParserException;
025
026/**
027 * <p>
028 * An object that wishes to be informed of events during the parsing of a file.
029 * </p>
030 *
031 * <p>
032 * This interface is similar in spirit to the SAX interfaces for parsing XML.
033 * Many of the methods will always be called in appropriately nested pairs.
034 * Entire records will be bracketed by a startRecord and endRecord pair. Within
035 * these, any number of startTag and endTag pairs may be called. Within a
036 * tag pair, any number of value invocations may be called. If a value is
037 * complex and requires parsing as a sub-entry, then the TagValueContext
038 * interface can be used to push a new TagValueParser and listener pair onto the parser
039 * stack. This will result in the pushed listener recieving a start/end document
040 * notification encapsulating the entire sub-set of events generated by the
041 * parser using the pushed TagValueParser to process the sub-document.
042 * </p>
043 *
044 * @author Matthew Pocock
045 * @since 1.2
046 */
047public interface TagValueListener {
048  /**
049   * A new record is about to start.
050   *
051   * @throws ParserException if the record can not be started
052   */
053  public void startRecord()
054  throws ParserException;
055  
056  /**
057   * The current record has ended.
058   *
059   * @throws ParserException if the record can not be ended
060   */
061  public void endRecord()
062  throws ParserException;
063  
064  /**
065   * Start a new tag.
066   *
067   * @param tag the Object representing the new tag
068   * @throws ParserException if the tag could not be started
069   */
070  public void startTag(Object tag)
071  throws ParserException;
072  
073  /**
074   * End the current tag.
075   *
076   * @throws ParserException if the tag could not be ended
077   */
078  public void endTag()
079  throws ParserException;
080  
081  /**
082   * A value has been seen.
083   *
084   * @param ctxt a TagValueContext that could be used to push a sub-document
085   * @param value  the value Object observed
086   * @throws ParserException if the value could not be processed
087   */
088  public void value(TagValueContext ctxt, Object value)
089  throws ParserException;
090}