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 org.biojava.utils.ChangeVetoException;
024
025/**
026 * Factory for handling a particular implementation of a Taxon.
027 *
028 * @author Matthew Pocock
029 * @deprecated replaced by classes in {@link org.biojavax.bio.taxa org.biojavax.bio.taxa}
030 */
031
032public interface TaxonFactory {
033  /**
034   * <p>Name for this TaxonFactory.</p>
035   *
036   * @return the name of this TaxonFactory
037   */
038  public String getName();
039  
040  /**
041   * <p>Import a Taxon and all its children into the implementation
042   * provided by this factory.</p>
043   *
044   * <p>The return value of this method should be .equals() and
045   * .hasCode() compatable with the taxon parameter. It may not be
046   * implemented by the same underlying implementation.</p>
047   *
048   * @param source the Taxon to copy
049   * @return a new Taxon
050   */
051  public Taxon importTaxon(Taxon source);
052  
053  /**
054   * <p>Retrieve the root upon which all rooted Taxon that this
055   * factory knows about are rooted.</p>
056   *
057   * @return the 'root' Taxon
058   */
059  public Taxon getRoot();
060  
061  /**
062   * <p>Retrieve a Taxon that matches some ID.</p>
063   *
064   * <p>This method is here out of desperation. It's nasty and should
065   * be replaced by some propper querying API. Without having
066   * different methods for every TaxonFactory I don't know what to
067   * do. All ideas appreciated.</p>
068   *
069   * @param id  the Object identifying a Taxon
070   * @return the Taxon matching the ID, or null if none match
071   */
072  public Taxon search(Object id);
073  
074  /**
075   * <p>Create a new orphan Taxon with a given scientific and common
076   * name.</p>
077   *
078   * @param scientificName  the scientificName to give the Taxon
079   * @param commonName  the common name to give the Taxon
080   * @return a new Taxon with no parent and no children
081   */
082  public Taxon createTaxon(String scientificName, String commonName);
083  
084  
085  /**
086   * <p>Add a taxon as a child to a parent.</p>
087   *
088   * <p>The TaxonFactory may chose to add the child directly, or make
089   * a new object which is .equals() compatable with child. The actual
090   * Taxon instance inserted into the child set is returned by the add
091   * method.</p>
092   *
093   * @param parent the parent Taxon to add the child to
094   * @param child  the Taxon to add as a child
095   * @return the Taxon object actualy present as the child
096   * @throws ChangeVetoException if for any reason the child can't be added
097   * @throws CircularReferenceException if child is this Taxon or any
098   * of its parents
099   */
100  public Taxon addChild(Taxon parent, Taxon child)
101  throws ChangeVetoException,
102  CircularReferenceException;
103  
104  /**
105   * <p>Remove a Taxon as a child to this one.</p>
106   *
107   * <p>This Taxon should attempt to remove a child that is .equals()
108   * compatable with child. If it is sucessful, it should return the
109   * Taxon instance that was removed. If not, it should return
110   * null.</p>
111   *
112   * @param parent the parent Taxon to remove the child from
113   * @param child  the Taxon to remove as a child
114   * @return the actual Taxon removed, or null if none were removed
115   * @throws ChangeVetoException if for any reason the child can't be
116   * removed
117   */
118  public Taxon removeChild(Taxon parent, Taxon child)
119  throws ChangeVetoException;
120}