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 org.biojava.bio.seq.StrandedFeature;
025import org.biojava.utils.ParserException;
026
027/**
028 * Interface which captures any errors which occur when parsing
029 * a GFF stream.  Providing a custom implementation of this
030 * interface allows intelligent recovery from errors when
031 * parsing GFF.
032 *
033 * <p>
034 * Each of these methods has three options:
035 *
036 * <ul>
037 * <li>Throw a ParserException.  This need only contain a 
038 * detail message, the parser will fill in other fields.
039 * parsing will be aborted.</li>
040 * <li>Throw an IgnoreRecordException.  This line of the GFF
041 * file will be ignored, but parsing will not be aborted</li>
042 * <li>Return a value for the field.
043 * </ul>
044 * </p>
045 *
046 * @author Thomas Down
047 * @author Matthew Pocock
048 */
049
050public interface GFFErrorHandler {
051    /** 
052     * The `start' field of the GFF entry was not a valid value.
053     *
054     * @param token The start token found.
055     * @return A parsed value, if this is possible
056     * @throws ParserException If parsing should be aborted
057     * @throws IgnoreRecordException If this record should be silently skipped.
058     */
059
060    public int invalidStart(String token) 
061        throws ParserException, IgnoreRecordException;
062
063    /** 
064     * The `end' field of the GFF entry was not a valid value.
065     *
066     * @param token The end token found.
067     * @return A parsed value, if this is possible
068     * @throws ParserException If parsing should be aborted
069     * @throws IgnoreRecordException If this record should be silently skipped.
070     */
071
072    public int invalidEnd(String token) 
073        throws ParserException, IgnoreRecordException;
074
075    /** 
076     * The `score' field of the GFF entry was not a valid value.
077     *
078     * @param token The score token found.
079     * @return A parsed value, if this is possible
080     * @throws ParserException If parsing should be aborted
081     * @throws IgnoreRecordException If this record should be silently skipped.
082     */
083
084    public double invalidScore(String token) 
085        throws ParserException, IgnoreRecordException;
086
087    /** 
088     * The `frame' field of the GFF entry was not a valid value.
089     *
090     * @param token The frame token found.
091     * @return A parsed value, if this is possible
092     * @throws ParserException If parsing should be aborted
093     * @throws IgnoreRecordException If this record should be silently skipped.
094     */
095
096    public int invalidFrame(String token) 
097        throws ParserException, IgnoreRecordException;
098
099    /** 
100     * The `strand' field of the GFF entry was not a valid value.
101     *
102     * @param token The strand token found.
103     * @return A parsed value, if this is possible
104     * @throws ParserException If parsing should be aborted
105     * @throws IgnoreRecordException If this record should be silently skipped.
106     */
107
108    public StrandedFeature.Strand invalidStrand(String token) 
109        throws ParserException, IgnoreRecordException;
110
111    public static final GFFErrorHandler ABORT_PARSING = new AbortErrorHandler();
112
113    static class AbortErrorHandler implements GFFErrorHandler {
114        public int invalidStart(String token) throws ParserException {
115            throw new ParserException("Invalid start token");
116        }
117
118        public int invalidEnd(String token) throws ParserException {
119            throw new ParserException("Invalid end token");
120        }
121
122        public double invalidScore(String token) throws ParserException {
123            throw new ParserException("Invalid score token");
124        }
125
126        public int invalidFrame(String token) throws ParserException {
127            throw new ParserException("Invalid frame token");
128        }
129
130        public StrandedFeature.Strand invalidStrand(String token) throws ParserException {
131            throw new ParserException("Invalid strand token");
132        }
133    }
134
135    public static final GFFErrorHandler SKIP_RECORD = new SkipRecordErrorHandler();
136    
137    static class SkipRecordErrorHandler implements GFFErrorHandler {
138        public int invalidStart(String token) throws IgnoreRecordException {
139            throw new IgnoreRecordException();
140        }
141
142        public int invalidEnd(String token) throws IgnoreRecordException {
143            throw new IgnoreRecordException();
144        }
145        
146        public double invalidScore(String token) throws IgnoreRecordException {
147            throw new IgnoreRecordException();
148        }
149
150        public int invalidFrame(String token) throws IgnoreRecordException {
151            throw new IgnoreRecordException();
152        }
153
154        public StrandedFeature.Strand invalidStrand(String token) throws IgnoreRecordException {
155            throw new IgnoreRecordException();
156        }
157    }
158}
159
160
161