001 package org.jaga.definitions;
002
003
004 /**
005 * Basis for individual factories.
006 * Individuals should not have a public constructor, but be rather constructed
007 * by corresponding factories.
008 *
009 * <p><u>Project:</u> JAGA - Java API for Genetic Algorithms.</p>
010 *
011 * <p><u>Company:</u> University College London and JAGA.Org
012 * (<a href="http://www.jaga.org" target="_blank">http://www.jaga.org</a>).
013 * </p>
014 *
015 * <p><u>Copyright:</u> (c) 2004 by G. Paperin.<br/>
016 * This program is free software; you can redistribute it and/or modify
017 * it under the terms of the GNU General Public License as published by
018 * the Free Software Foundation, ONLY if you include a note of the original
019 * author(s) in any redistributed/modified copy.<br/>
020 * This program is distributed in the hope that it will be useful,
021 * but WITHOUT ANY WARRANTY; without even the implied warranty of
022 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
023 * GNU General Public License for more details.<br/>
024 * You should have received a copy of the GNU General Public License
025 * along with this program; if not, write to the Free Software
026 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
027 * or see http://www.gnu.org/licenses/gpl.html</p>
028 *
029 * @author Greg Paperin (greg@jaga.org)
030 *
031 * @version JAGA public release 1.0 beta
032 */
033
034 public interface IndividualsFactory {
035
036 /**
037 * Creates a new default individual. For same factory settings, this method must
038 * always return the same individual (a new instance holding the same values),
039 * which is considered the defaut individual for those settings.
040 *
041 * @param params Experiment parameters.
042 *
043 * @return A new instance of the dafault individual for this factory's current
044 * settings.
045 */
046 public Individual createDefaultIndividual(GAParameterSet params);
047
048 /**
049 * Creates a random individual according to this factory's current internal
050 * settings and expariment paramanters.
051 *
052 * @param params Experiment parameters.
053 *
054 * @return A new instanc eof a randomly created individual.
055 */
056 public Individual createRandomIndividual(GAParameterSet params);
057
058 /**
059 * Creates a new individual and initialises it to the specified value(s).
060 * The parameter <code>init</code> can hold any value(s) which this factory
061 * knows to interprete.<br/>
062 * In particular, a factory should be able to handle
063 * <code>Individual</code>-objects of the same type as produced by the
064 * factory. If such an <code>Individual</code>-object is passed as the
065 * <code>init</code>-value, a deep copy of the individual should be created
066 * and returned by this method.<br/>
067 * Any other type is permited for the <code>init</code>-value, but the
068 * value should not be <code>null</code>. This method should create a new
069 * individual and initialise it with the value(s) packed encoded in
070 * <code>init</code>.
071 *
072 * @param init Initialisation value(s) for a new individual.
073 *
074 * @param params Experiment parameters.
075 *
076 * @return A new instance of an individual produced by this factory,
077 * initialised to the value(s) specified in <code>init</code>.
078 *
079 * @throws NullPointerException If <code>init</code> is <code>null</code>.
080 *
081 * @throws ClassCastException If <code>init</code> is of a type not supported
082 * by this factory for initalisation of individuals.
083 */
084 public Individual createSpecificIndividual(Object init, GAParameterSet params)
085 throws NullPointerException, ClassCastException;
086
087 }