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
022
023package org.biojavax.ga;
024
025import java.util.Iterator;
026import java.util.Set;
027
028import org.biojava.utils.ChangeType;
029import org.biojava.utils.ChangeVetoException;
030import org.biojava.utils.Changeable;
031import org.biojavax.ga.exception.IllegalOrganismException;
032
033/**
034 * A collection of GA organisms
035 *
036 * @author Mark Schreiber
037 * @version 1.0
038 * @since 1.5
039 */
040
041public interface Population extends Changeable{
042
043  /**
044   * @return the name of the population
045   */
046  public String getName();
047
048  /**
049   * Sets the name of the population
050   * @param name set the name to this.
051   * @throws ChangeVetoException if the name may not be changed
052   */
053  public void setName(String name) throws ChangeVetoException;
054
055  /**
056   * Adds an Organism to the Population
057   * @param org the organism
058   * @throws ChangeVetoException
059   * @throws IllegalOrganismException if for some reason the organism is invalid
060   */
061  public void addOrganism(Organism org) throws ChangeVetoException, IllegalOrganismException;
062
063  /**
064   * Adds several organisms to the population
065   * @param orgs the organisms to add
066   * @throws ChangeVetoException
067   * @throws IllegalOrganismException if for some reason the organism is invalid
068   */
069  public void addOrganisms(Organism[] orgs)throws ChangeVetoException, IllegalOrganismException;
070
071  /**
072   * Adds several organisms to the population
073   * @param orgs the organisms to add
074   * @throws ChangeVetoException
075   * @throws IllegalOrganismException if for some reason the organism is invalid
076   */
077  public void addOrganisms(Set orgs)throws ChangeVetoException, IllegalOrganismException;
078
079  /**
080   * Adds the residents of one population to this one
081   * @param orgs the population to add
082   * @throws ChangeVetoException
083   * @throws IllegalOrganismException if for some reason the organism is invalid
084   */
085  public void addOrganisms(Population orgs)throws ChangeVetoException, IllegalOrganismException;
086
087  /**
088   * Kills off the organism
089   * @param org the organism to kill
090   * @throws ChangeVetoException
091   */
092  public void removeOrganism(Organism org) throws ChangeVetoException;
093
094  /**
095   * Removes all the <code>Organisms</code> in <code>orgs</code>
096   * @param orgs the <code>Organisms</code> to remove.
097   * @throws ChangeVetoException if the change is vetoed
098   */
099  public void removeOrganisms(Organism[] orgs) throws ChangeVetoException;
100
101  /**
102   * Removes all the <code>Organisms</code> in <code>orgs</code>
103   * @param orgs the <code>Organisms</code> to remove.
104   * @throws ChangeVetoException if the change is vetoed
105   */
106  public void removeOrganisms(Set orgs) throws ChangeVetoException;
107
108  /**
109   * Removes all the <code>Organisms</code> in this <code>Population</code>
110   * @throws ChangeVetoException if the change is vetoed
111   */
112  public void removeAllOrganisms() throws ChangeVetoException;
113
114  /**
115   * Gets the specified organism
116   * @param name the name of the organism to retreive
117   * @return the organism named or null if that organism doesn't exist.
118   */
119  public Organism getOrganismByName(String name);
120
121  /**
122   * Gets the Set of Organisms
123   * @return a Set
124   */
125  public Set getOrganisms();
126
127  /**
128   *
129   * @return an iterator over the set of Organisms.
130   */
131  public Iterator organisms();
132
133  /**
134   * Gets the Size of the population
135   * @return the size
136   */
137  public int size();
138
139
140  public static ChangeType ORGANISMS =
141      new ChangeType("Organisms changed",Population.class,"ORGANISMS");
142
143  public static ChangeType NAME =
144      new ChangeType("Name changed",Population.class,"NAME");
145
146}