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.biojavax.bio.seq.io; 023 024import org.biojava.bio.seq.io.ParseException; 025import org.biojava.bio.seq.io.SeqIOListener; 026import org.biojavax.Namespace; 027import org.biojavax.RankedCrossRef; 028import org.biojavax.RankedDocRef; 029import org.biojavax.bio.BioEntryRelationship; 030import org.biojavax.bio.seq.RichFeature; 031import org.biojavax.bio.taxa.NCBITaxon; 032 033/** 034 * An interface for classes that listen to BioEntry or 035 * RichSequence I/O streams. The listener works as a call back interface. 036 * The callback methods would be generated by an object that is, for example, 037 * reading a sequence flat file. Guidelines on how many times the listener can 038 * expect each callback to occur are given below. 039 * Exactly what the Listener does with each call back is totally at the discretion 040 * of the implementor. The listener may aggregate events and build objects. 041 * The listener may selectively filter events and parse on others to another 042 * listener. The listener may choose to modify events. The options are endless. 043 * Although the name of the class and the name of some of the events suggest a 044 * sequence centric design the class could be used to listen to a parser of a 045 * bioentry style record that doesn't actually contain any sequence. In this 046 * case no addSymbols() methods would be called. The listener may 047 * be an implementation that only builds BioEntry objects and 048 * ignores sequence information completely. 049 * @author Mark Schreiber 050 * @author Richard Holland 051 * @since 1.5 052 */ 053public interface RichSeqIOListener extends SeqIOListener { 054 055 /** 056 * Call back method so the event emitter can tell the listener 057 * the accession of the record being read. It is possible that some 058 * records have more than one accession. As a guide the first one 059 * sent to the listener should be the primary one. 060 * @param accession The accession of the record 061 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 062 * to deal with the event or is not expecting the event. 063 * 064 * @see #setName(String name) 065 * @see #setURI(String uri) 066 * @see #setIdentifier(String identifier) 067 * 068 */ 069 public void setAccession(String accession) throws ParseException; 070 071 /** 072 * Call back method so the event emitter can tell the listener 073 * the identifier of the record being read. There should be 074 * zero or one identifier per bioentry. If there is more 075 * than one the Listener should consider throwing an exception. 076 * For some formats like fasta the identifier may not exist. For others 077 * like GenBank the identifier best maps to the GI. 078 * @param identifier The identifier of the Bioentry. 079 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 080 * to deal with the event or is not expecting the event. 081 * @see #setName(String name) 082 * @see #setAccession(String accession) 083 * @see #setURI(String uri) 084 */ 085 public void setIdentifier(String identifier) throws ParseException; 086 087 /** 088 * Call back method so the event emitter can tell the listener 089 * the division of the record being read. If the source of the 090 * calls back is a GenBank parser the division will be a Genbank division. 091 * This method would typically be called 0 or 1 times. It should 092 * not be called more than once per entry and an exception could be thrown 093 * if it is. 094 * @param division The division the entry belongs too. 095 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 096 * to deal with the event or is not expecting the event. 097 */ 098 public void setDivision(String division) throws ParseException; 099 100 /** 101 * Call back method so the event emitter can tell the listener 102 * the description of the record being read. For example the description 103 * line of a FASTA format file would be the description. This method 104 * would typically be called 0 or 1 times and may cause an exception 105 * if it is called more than once per entry. 106 * @param description The description of the record 107 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 108 * to deal with the event or is not expecting the event. 109 */ 110 public void setDescription(String description)throws ParseException; 111 112 /** 113 * Call back method so the event emitter can tell the listener 114 * the version of the record being read. This method would typically 115 * be called 0 or 1 times per entry. If it is not called the 116 * Listener should assume the version is 0. If it is called more 117 * than once per entry an exception should be thrown. 118 * @param version the version of the record 119 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 120 * to deal with the event or is not expecting the event. 121 */ 122 public void setVersion(int version) throws ParseException; 123 124 /** 125 * Call back method so the event emitter can tell the listener 126 * the version of the sequence of the record being read. This method would typically 127 * be called 0 or 1 times per entry. If it is not called the 128 * Listener should assume the version is 0. If it is called more 129 * than once per entry an exception should be thrown. 130 * @param version the version of the record 131 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 132 * to deal with the event or is not expecting the event. 133 */ 134 public void setSeqVersion(String version) throws ParseException; 135 136 /** 137 * Call back method so the event emitter can tell the listener 138 * about a comment in the record being read. The comment is typically 139 * one or more comment lines relevant to the record as a whole and 140 * bundled in a Commment object. 141 * This method may be called zero or one times per entry. It can be called zero or more times. 142 * @param comment The comment 143 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 144 * to deal with the event or is not expecting the event. 145 */ 146 public void setComment(String comment) throws ParseException; 147 148 /** 149 * Call back method so the event emitter can tell the listener 150 * about a literature reference in the record being read. This method 151 * may be called zero or more times. 152 * @param ref A literature reference contained in the entry. 153 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 154 * to deal with the event or is not expecting the event. 155 */ 156 public void setRankedDocRef(RankedDocRef ref) throws ParseException; 157 158 /** 159 * Call back method so the event emitter can tell the listener 160 * the Taxon of the record being read. This method may be called 161 * zero or one times. An exception may be thrown if it is called 162 * more than once. As a design decision NCBI's taxon model was chosen as it 163 * is commonly used and is supported by the BioSQL schema. The setting of 164 * an NCBI taxon should be considered entirely optional. 165 * 166 * @param taxon The taxon information relevant to this entry. 167 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 168 * to deal with the event or is not expecting the event. 169 */ 170 public void setTaxon(NCBITaxon taxon) throws ParseException; 171 172 /** 173 * Call back method so the event emitter can tell the listener 174 * the namespace of the record being read. The method can be called 175 * zero or one time. If it is called more than once an exception 176 * may be thrown.<p> 177 * The namespace is a concept from the BioSQL schema that enables 178 * Bioentries to be disambiguated. It is possible in BioSQL and should be possible 179 * in other collections of BioEntries to have records that have the same 180 * name, accession and version but different namespaces. This method would be 181 * expected to be called if you are reading a sequence from a biosql database or 182 * if you are implementing a listener that knows how to write to a biosql database. 183 * If you give a sequence a namespace and it is persited to biosql at somepoint in it's 184 * life you could expect it to be persisted to that namespace (if possible). 185 * 186 * @param namespace The namespace of the entry. 187 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 188 * to deal with the event or is not expecting the event. 189 */ 190 public void setNamespace(Namespace namespace) throws ParseException; 191 192 /** 193 * Call back method so the event emitter can tell the listener 194 * about a relationship between the bioentry or sequence in the 195 * record being read and another bioentry. This may be called zero 196 * or more times. 197 * @param relationship The relationship 198 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 199 * to deal with the event or is not expecting the event. 200 */ 201 public void setRelationship(BioEntryRelationship relationship) throws ParseException; 202 203 /** 204 * Call back method so the event emitter can tell the listener about a cross reference. 205 * This could be called zero or more times per entry. 206 * @param crossRef the cross reference 207 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 208 * to deal with the event or is not expecting the event. 209 */ 210 public void setRankedCrossRef(RankedCrossRef crossRef) throws ParseException; 211 212 /** 213 * {@inheritDoc} 214 * @deprecated There is no clear mapping between URI and BioSQL. This 215 * method is no longer used or supported in biojavax. Don't use it. Calling 216 * it may result in exceptions. Use instead setName(String name), 217 * setAccession(String accession), setVersion(int version) etc as 218 * appropriate. 219 */ 220 public void setURI(String uri) throws ParseException; 221 222 /** 223 * Gets the feature currently being created. 224 * @return the feature under construction. 225 * @throws ParseException if a feature is not currently being created. 226 */ 227 public RichFeature getCurrentFeature() throws ParseException; 228 229 /** 230 * Defined this sequence being parser as circular. It is best to call this 231 * as early as possible during parsing. It should definitely be called 232 * before doing anything with locations or features. 233 * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable 234 * to deal with the event or is not expecting the event. 235 * @param circular set this to true if you want it to be circular. 236 */ 237 public void setCircular(boolean circular) throws ParseException; 238 239}