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.taxa;
023import java.util.Set;
024
025import org.biojava.utils.ChangeType;
026import org.biojava.utils.ChangeVetoException;
027import org.biojava.utils.Changeable;
028
029/**
030 * Represents an NCBI Taxon entry, a combination of the taxon and taxon_name
031 * tables in BioSQL.
032 * @author Mark Schreiber
033 * @author Richard Holland
034 * @since 1.5
035 */
036public interface NCBITaxon extends Comparable,Changeable {
037    
038    public static final ChangeType NAMES = new ChangeType(
039            "This taxon's names have changed",
040            "org.biojavax.bio.taxa.NCBITaxon",
041            "NAMES"
042            );
043    public static final ChangeType PARENT = new ChangeType(
044            "This taxon's parent has changed",
045            "org.biojavax.bio.taxa.NCBITaxon",
046            "PARENT"
047            );
048    public static final ChangeType NODERANK = new ChangeType(
049            "This taxon's node rank has changed",
050            "org.biojavax.bio.taxa.NCBITaxon",
051            "NODERANK"
052            );
053    public static final ChangeType GENETICCODE = new ChangeType(
054            "This taxon's genetic code has changed",
055            "org.biojavax.bio.taxa.NCBITaxon",
056            "GENETICCODE"
057            );
058    public static final ChangeType MITOGENETICCODE = new ChangeType(
059            "This taxon's mito genetic code has changed",
060            "org.biojavax.bio.taxa.NCBITaxon",
061            "MITOGENETICCODE"
062            );
063    public static final ChangeType LEFTVALUE = new ChangeType(
064            "This taxon's left value has changed",
065            "org.biojavax.bio.taxa.NCBITaxon",
066            "LEFTVALUE"
067            );
068    public static final ChangeType RIGHTVALUE = new ChangeType(
069            "This taxon's right value has changed",
070            "org.biojavax.bio.taxa.NCBITaxon",
071            "RIGHTVALUE"
072            );
073    
074        public static final ChangeType HIDDEN = new ChangeType(
075                        "This taxon's visibility in genbank hierarchy has changed",
076                        "org.biojavax.bio.taxa.NCBITaxon",
077                        "HIDDEN"
078        );
079        
080    /**
081     * Use this to define scientific names for things. There should
082     * usually only be one scientific name for an organism.
083     */
084    public static final String SCIENTIFIC = "scientific name";
085    
086    /**
087     * Use this to define common names for things. There can be as many
088     * common names as you like.
089     */
090    public static final String COMMON = "common name";
091    
092    /**
093     * Use this to define common names for things. There can be as many
094     * synonyms as you like.
095     */
096    public static final String SYNONYM = "synonym";
097    
098    /**
099     * Use this to define acronyms for things. There can be as many
100     * acronyms as you like.
101     */
102    public static final String ACRONYM = "acronym";
103    
104    /**
105     * Use this to define equivalent names for things. There can be as many
106     * equivalent names as you like.
107     */
108    public static final String EQUIVALENT = "equivalent name";
109    
110    /**
111     * Returns all the name classes available for a taxon. These are Strings.
112     * @return a set of name classes, or the empty set if there are none.
113     */
114    public Set getNameClasses();
115    
116    /**
117     * Returns all the names available for a taxon in a given class.
118     * These are Strings.
119     * @param nameClass the name class to retrieve names from.
120     * @return a set of names, or the empty set if there are none.
121     * @throws IllegalArgumentException if the name is null.
122     */
123    public Set getNames(String nameClass) throws IllegalArgumentException;
124    
125    /**
126     * Adds the name to this taxon in the given name class. Neither can be null.
127     * @param nameClass the class to add the name in.
128     * @param name the name to add.
129     * @throws ChangeVetoException in case of objections.
130     * @throws IllegalArgumentException if the name is null.
131     */
132    public void addName(String nameClass, String name) throws IllegalArgumentException,ChangeVetoException;
133    
134    /**
135     * Removes the name from the given name class. Neither can be null.
136     * @return True if the name was found and removed, false otherwise.
137     * @param nameClass the class to remove the name from.
138     * @param name the name to remove.
139     * @throws ChangeVetoException in case of objections.
140     * @throws IllegalArgumentException if the name is null.
141     */
142    public boolean removeName(String nameClass, String name) throws IllegalArgumentException,ChangeVetoException;
143    
144    /**
145     * Tests for the presence of a name in a given class. Neither can be null.
146     * @param nameClass the class to look the name up in.
147     * @param name the name to text for existence of.
148     * @return True if the name exists in that class, false otherwise.
149     * @throws IllegalArgumentException if the name is null.
150     */
151    public boolean containsName(String nameClass, String name) throws IllegalArgumentException;
152    
153    /**
154     * Returns the parent NCBI taxon ID, if known.
155     * @return Value of property parent.
156     */
157    public Integer getParentNCBITaxID();
158    
159    /**
160     * Sets the parent NCBI taxon ID. May be null if not known.
161     * @param parent New value of property parent.
162     * @throws ChangeVetoException in case of objections.
163     */
164    public void setParentNCBITaxID(Integer parent) throws ChangeVetoException;
165    
166    /**
167     * Gets the NCBI taxon ID. This is never null and is immutable, as otherwise
168     * we would have no way of distinguishing between various taxa. It should
169     * be set by the constructor of an implementation.
170     * @return Value of property NCBITaxID.
171     */
172    public int getNCBITaxID();
173    
174    /**
175     * Gets the node rank of this taxon. May be null.
176     * @return Value of property nodeRank.
177     */
178    public String getNodeRank();
179    
180    /**
181     * Sets the node rank of this taxon. May be null, in which case it is unset.
182     * @param nodeRank New value of property nodeRank.
183     * @throws ChangeVetoException in case of objections.
184     */
185    public void setNodeRank(String nodeRank) throws ChangeVetoException;
186    
187    /**
188     * Returns the genetic code of this taxon, which may be null if not known.
189     * @return Value of property geneticCode.
190     */
191    public Integer getGeneticCode();
192    
193    /**
194     * Sets the genetic code of this taxon, which may be null, which will unset it.
195     * @param geneticCode New value of property geneticCode.
196     * @throws ChangeVetoException in case of objections.
197     */
198    public void setGeneticCode(Integer geneticCode) throws ChangeVetoException;
199    
200    /**
201     * Returns the mitochondrial genetic code of this taxon, which may be null 
202     * if not known.
203     * @return Value of property mitoGeneticCode.
204     */
205    public Integer getMitoGeneticCode();
206    
207    /**
208     * Sets the mitochondrial genetic code of this taxon, which may be null, 
209     * which will unset it.
210     * @param mitoGeneticCode New value of property mitoGeneticCode.
211     * @throws ChangeVetoException in case of objections.
212     */
213    public void setMitoGeneticCode(Integer mitoGeneticCode) throws ChangeVetoException;
214    
215    /**
216     * Gets the left value. May be null.
217     * @return Value of property leftValue.
218     */
219    public Integer getLeftValue();
220    
221    /**
222     * Sets the left value. May be null.
223     * @param leftValue New value of property leftValue.
224     * @throws ChangeVetoException in case of objections.
225     */
226    public void setLeftValue(Integer leftValue) throws ChangeVetoException;
227    
228    /**
229     * Gets the right value. May be null.
230     * @return Value of property rightValue.
231     */
232    public Integer getRightValue();
233    
234    /**
235     * Sets the right value. May be null.
236     * @param rightValue New value of property rightValue.
237     * @throws ChangeVetoException in case of objections.
238     */
239    public void setRightValue(Integer rightValue) throws ChangeVetoException;
240
241    /**
242     * Returns the name of this taxon entry in the form:
243     *   scientific (common)
244     * or if there is no common name:
245     *   scientific
246     * @return the display name as described above.
247     */
248    public String getDisplayName();
249
250    /**
251     * Returns the taxonomy hierarchy of this taxon entry in the form:
252     *   least specific; more specific; ...; most specific.
253     * It follows the chain up the tree as far as it can, and will stop
254     * at the first one it comes to that returns null for getParentNCBITaxID()
255     * @return the display name as described above.
256     */
257    public String getNameHierarchy();
258    
259        /**
260         * used in getNameHierarchy() to determine whether this taxonomy level is displayed
261         */
262        public boolean isTaxonHidden();
263        
264        /**
265         * determines whether this taxonomy level is displayed in etNameHierarchy()
266         * @param isTaxonHidden - if true it is displayed
267         * @throws ChangeVetoException
268         */
269    public void setTaxonHidden(final boolean isTaxonHidden) throws ChangeVetoException;
270}
271