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 */
021package org.biojava.bio.taxa;
022
023import java.util.Set;
024
025import org.biojava.bio.Annotatable;
026import org.biojava.utils.ChangeType;
027import org.biojava.utils.ChangeVetoException;
028
029/**
030 * <p>A taxon within a classification.</p>
031 *
032 * <p>Taxa may be 'leaf' nodes specifying species, or 'internal' nodes
033 * specifying kingdoms and the like.</p>
034 *
035 * @author Matthew Pocock
036 * @deprecated replaced by classes in {@link org.biojavax.bio.taxa org.biojavax.bio.taxa}
037 */
038public interface Taxon extends Annotatable {
039  /**
040   * Change type to indicate that the common name of this Taxon is
041   * changing.
042   */
043  public final static ChangeType CHANGE_COMMON_NAME = new ChangeType(
044    "Common name change",
045    Taxon.class,
046    "CHANGE_COMMON_NAME"
047  );
048  
049  /**
050   * Change type to indicate that the scientific name of this Taxon is
051   * changing.
052   */
053  public final static ChangeType CHANGE_SCIENTIFIC_NAME = new ChangeType(
054    "Scientific name change",
055    Taxon.class,
056    "CHANGE_SCIENTIFIC_NAME"
057  );
058
059  /**
060   * <p>The common name of the Taxon.</p>
061   *
062   * <p>This is the normal name used in common speech, such as
063   * 'human'.</p>
064   *
065   * @return a String representing this Taxon's common name
066   */
067  public String getCommonName();
068  
069  /**
070   * <p>Set the new common name of this Taxon.</p>
071   *
072   * @param commonName  the new common name
073   * @throws ChangeVetoException if the name can't be changed at this time
074   */
075  public void setCommonName(String commonName)
076  throws ChangeVetoException;
077  
078  /**
079   * <p>The scientific name of this taxon.</p>
080   *
081   * <p>This will be the portion of the scientific classification
082   * pertaining to just this node within the classifictaion. It will
083   * be something like 'homo sapiens' or 'archaeal group 2', rather
084   * than the full classification list.</p>
085   */
086  public String getScientificName();
087
088  /**
089   * Change the scientific name of this species.
090   *
091   * @param scientificName the new scientific name
092   * @throws ChangeVetoException if the scientific name can't be
093   * changed at this time
094   */
095  public void setScientificName(String scientificName)
096  throws ChangeVetoException;
097  
098  /**
099   * <p>The parent of this Taxon.</p>
100   *
101   * <p>Taxa live within a tree data-structure, so every taxon has a
102   * single parent except for the root type. This has the null
103   * parent.</p>
104   *
105   * @return the parent Taxon, or null if this is the root type.
106   */
107  public Taxon getParent();
108  
109  /**
110   *  <p>The children of this Taxon.</p>
111   *
112   * <p>Taxa live within a tree data-structure, so every taxon has
113   * zero or more children. In the case of zero children, the empty
114   * set is returned.</p>
115   *
116   * <p>? read-only ? dynamicaly updated with taxon object ? copy of
117   * data ?</p>
118   *
119   * @return the Set (possibly empty) of all child Taxa
120   */
121  public Set getChildren();
122  
123  /**
124   * <p>Two taxa are equal if they have equivalent children, common
125   * and scientific names.</p>
126   *
127   * <p>Two different implementations of Taxon should be able to
128   * appropriately trans-class equality. The parent of a Taxon is not
129   * considered in testing equality as this potentially leads to
130   * combinatorial problems checking whole taxa hierachies against one
131   * another.</p>
132   *
133   * @param o  the object to check
134   * @return true if o is a Taxon instance and has the same properties
135   * as this
136   */
137  public boolean equals(Object o);
138  
139  /**
140   * The hash-code of a Taxon is equal to the hash-code of it's
141   * scientific name.
142   */
143  public int hashCode();
144}